ضبط الحقول النصية

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يسمح الرمز TextField للمستخدمين بإدخال النص وتعديله. هناك نوعان من حقول النصوص التي يمكنك استخدامها: حقول النصوص المستندة إلى الحالة و حقول النصوص المستندة إلى القيمة. اختَر النوع الذي تريد عرض المحتوى له:

وننصحك باستخدام الحقول النصية المستندة إلى الحالة، لأنّها توفّر نهجًا أكثر اكتمالاً و موثوقية لإدارة حالة TextField. يوضّح الجدول التالي الاختلافات بين هذين النوعَين من الحقول النصية، ويشمل المزايا الرئيسية التي تقدّمها الحقول النصية المستندة إلى الحالة:

توضّح هذه الصفحة كيفية تنفيذ TextField وتنسيق إدخال TextField وضبط خيارات TextField الأخرى، مثل خيارات لوحة المفاتيح وتحويل إدخال المستخدِم بشكل مرئي.

اختيار عملية تنفيذ TextField

هناك مستويان لتنفيذ TextField:

1. TextField هو تنفيذ Material Design. ننصحك باختيار هذا التنفيذ لأنّه يتبع إرشادات Material Design:
   • النمط التلقائي هو مملوء
   • OutlinedTextField هو إصدار التصميم المحدّد
2. يتيح BasicTextField للمستخدمين تعديل النص باستخدام لوحة مفاتيح برمجية أو حقيقية، ولكن لا يوفّر أي زخارف مثل التلميح أو العنصر النائب.

TextField(
    state = rememberTextFieldState(initialText = "Hello"),
    label = { Text("Label") }
)
StateBasedText.kt

OutlinedTextField(
    state = rememberTextFieldState(),
    label = { Text("Label") }
)
StateBasedText.kt

النمط TextField

تتشارك TextField وBasicTextField العديد من المَعلمات الشائعة للتخصيص. تتوفّر القائمة الكاملة لـ TextField في رمز مصدر TextField. في ما يلي قائمة غير شاملة ببعض المَعلمات المفيدة:

• textStyle
• lineLimits

TextField(
    state = rememberTextFieldState("Hello\nWorld\nInvisible"),
    lineLimits = TextFieldLineLimits.MultiLine(maxHeightInLines = 2),
    placeholder = { Text("") },
    textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
    label = { Text("Enter text") },
    modifier = Modifier.padding(20.dp)
)
StateBasedText.kt

ننصحك باستخدام TextField بدلاً من BasicTextField عندما يتطلّب تصميمك استخدام مادة TextField أو OutlinedTextField. ومع ذلك، يجب استخدام BasicTextField عند إنشاء تصميمات لا تحتاج إلى الزخارف من مواصفات Material.

ضبط حدود السطر

تتيح العناصر القابلة للتجميع TextField الانتقال على طول محور واحد. يتم تحديد سلوك التمرير بواسطة المَعلمة lineLimits. يتم ضبط TextField للتمرير أفقيًا في سطر واحد، بينما يتم التمرير عموديًا في TextField المتعدّدة الأسطر.

استخدِم TextFieldLineLimits لاختيار إعدادات السطر المناسبة لملف TextField:

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine
)
StateBasedText.kt

تتسم إعدادات SingleLine بالسمات التالية:

• لا يتم أبدًا اقتطاع النص ولا يسمح بإضافة أسطر جديدة.
• يكون ارتفاع TextField ثابتًا دائمًا.
• إذا كان النص يتدفق، يتم التمرير أفقيًا.

TextField(
    state = rememberTextFieldState("Hello\nWorld\nHello\nWorld"),
    lineLimits = TextFieldLineLimits.MultiLine(1, 4)
)
StateBasedText.kt

تتسم إعدادات MultiLine بالسمات التالية:

• تقبل مَعلمتَين: minHeightInLines وmaxHeightInLines.
• يبلغ ارتفاع الحقل النصي minHeightInLines على الأقل.
• إذا كان النص يتدفق خارج المساحة، سيتم عرضه على عدة أسطر.
• إذا كان النص يتطلّب المزيد من الأسطر، يكبر الحقل إلى أن يصل إلى maxHeightInLines ارتفاعًا، ويتم التمرير عموديًا.

إدخال الأنماط باستخدام Brush API

يمكنك استخدام Brush API للحصول على تنسيق أكثر تقدّمًا في TextField. يوضّح القسم التالي كيفية استخدام فرشاة لإضافة منحدر لانهائي ملوّن إلى إدخال TextField.

لمزيد من المعلومات عن استخدام Brush API لتنسيق النص، يُرجى الاطّلاع على مقالة تفعيل التنسيق المتقدّم باستخدام Brush API.

تطبيق تدرّجات ألوان باستخدام TextStyle

لتنفيذ انتقال لوني أثناء الكتابة في TextField، اضبط الفرشاة التي تختارها على أنّها TextStyle لـ TextField. في هذا المثال، نستخدم فرشاة مدمجة مع linearGradient لعرض تأثير التدرج اللوني للألوان الكاملة أثناء كتابة النص في TextField.

val brush = remember {
    Brush.linearGradient(
        colors = listOf(Color.Red, Color.Yellow, Color.Green, Color.Blue, Color.Magenta)
    )
}
TextField(
    state = rememberTextFieldState(), textStyle = TextStyle(brush = brush)
)
StateBasedText.kt

إدارة حالة حقل النص

يستخدم TextField فئة مخصّصة لصاحب الحالة تُسمى TextFieldState لتحديد المحتوى والاختيار الحالي. تم تصميم TextFieldState ليتم رفعه أينما كان ذلك مناسبًا في البنية. هناك سمتان رئيسيتان يوفّرهماTextFieldState:

• ‫initialText: محتوى TextField
• initialSelection: يشير إلى موضع المؤشر أو الجزء المحدّد حاليًا.

ما يميز TextFieldState عن الأساليب الأخرى، مثل callback onValueChange، هو أنّ TextFieldState يحوي بالكامل مسار الإدخال. ويشمل ذلك استخدام هياكل البيانات الأساسية الصحيحة، ودمج الفلاتر وأدوات التنسيق، بالإضافة إلى مزامنة جميع التعديلات الواردة من مصادر مختلفة.

يمكنك استخدام TextFieldState() لرفع الحالة في TextField. لهذا الغرض، ننصح باستخدام الدالة rememberTextFieldState(). تنشئ rememberTextFieldState() مثيل TextFieldState في العنصر القابل للتجميع، وتؤكّد على تذكُّر عنصر الحالة، وتوفر وظيفة مضمّنة لحفظ البيانات واستعادتها:

val usernameState = rememberTextFieldState()
TextField(
    state = usernameState,
    lineLimits = TextFieldLineLimits.SingleLine,
    placeholder = { Text("Enter Username") }
)
StateBasedText.kt

يمكن أن تحتوي rememberTextFieldState على مَعلمة فارغة أو قيمة أولية يتم تمريرها لتمثيل قيمة النص عند بدء التشغيل. في حال تمّ ضبط قيمة مختلفة في عملية إعادة تركيب لاحقة، لن يتم تعديل قيمة الحالة. لتعديل الحالة بعد بدء تشغيلها، يمكنك استدعاء طرق التعديل في TextFieldState.

TextField(
    state = rememberTextFieldState(initialText = "Username"),
    lineLimits = TextFieldLineLimits.SingleLine,
)
StateBasedText.kt

تعديل النص باستخدام TextFieldBuffer

يعمل العنصر TextFieldBuffer كحاوية نص قابلة للتعديل، وهو مشابه في وظيفته لStringBuilder. ويحتوي على محتوى النص ومعلومات عن الاختيار الحالي.

غالبًا ما يظهر الرمز TextFieldBuffer كنطاق مستلِم في دوال مثل TextFieldState.edit أو InputTransformation.transformInput أو OutputTransformation.transformOutput. في هذه الدوالّ، يمكنك قراءة TextFieldBuffer أو تعديلها حسب الحاجة. بعد ذلك، يتم إما تثبيت هذه التغييرات في TextFieldState أو تمريرها إلى مسار المعالجة في حالة OutputTransformation.

يمكنك استخدام دوال التعديل العادية مثل append أو insert أو replace أو delete لتعديل محتوى المخزن المؤقت. لتغيير حالة الاختيار، إما عليك ضبط المتغيّر selection: TextRange مباشرةً، أو استخدام دوالّ مساعدة مثل placeCursorAtEnd أو selectAll. يتم تمثيل الاختيار نفسه باستخدام رمز TextRange، حيث يكون فهرس البدء شاملاً وفهرس النهاية حصريًا. يشير الرمز TextRange الذي تكون قيمتَي البدء والنهاية متطابقتَين فيه، مثل (3, 3)، إلى موضع المؤشر بدون اختيار أي أحرف في الوقت الحالي.

val phoneNumberState = rememberTextFieldState()

LaunchedEffect(phoneNumberState) {
    phoneNumberState.edit { // TextFieldBuffer scope
        append("123456789")
    }
}

TextField(
    state = phoneNumberState,
    inputTransformation = InputTransformation { // TextFieldBuffer scope
        if (asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    },
    outputTransformation = OutputTransformation {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
)
StateBasedText.kt

تعديل النص في TextFieldState

هناك عدة طرق تتيح لك تعديل الحالة مباشرةً من خلال متغيّر الحالة:

• edit: يتيح لك تعديل محتوى الحالة ويمنحك TextFieldBuffer وظائف حتى تتمكّن من استخدام طُرق مثل insert وreplace وappend والمزيد.

  val usernameState = rememberTextFieldState("I love Android")
  // textFieldState.text : I love Android
  // textFieldState.selection: TextRange(14, 14)
  usernameState.edit { insert(14, "!") }
  // textFieldState.text : I love Android!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { replace(7, 14, "Compose") }
  // textFieldState.text : I love Compose!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { append("!!!") }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(18, 18)
  usernameState.edit { selectAll() }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(0, 18)
  StateBasedText.kt

• setTextAndPlaceCursorAtEnd: لمحو النص الحالي واستبداله بالنص المُعطى وضبط المؤشر في النهاية

  usernameState.setTextAndPlaceCursorAtEnd("I really love Android")
  // textFieldState.text : I really love Android
  // textFieldState.selection : TextRange(21, 21)
  StateBasedText.kt

• clearText: لمحو كل النصوص

  usernameState.clearText()
  // textFieldState.text :
  // textFieldState.selection : TextRange(0, 0)
  StateBasedText.kt

لمعرفة المزيد من المعلومات عن دوال TextFieldState الأخرى، يُرجى الاطّلاع على مرجع TextFieldState.

تعديل بيانات أدخلها المستخدم

توضِّح الأقسام التالية كيفية تعديل إدخال المستخدم. تتيح لك تحويل الإدخال فلترة إدخال TextField أثناء كتابة المستخدم، في حين أنّ تحويل المخرجات يُعدّ إدخال المستخدم قبل عرضه على الشاشة.

فلترة إدخال المستخدم من خلال عمليات تحويل الإدخال

يتيح لك تحويل الإدخال فلترة الإدخال من المستخدم. على سبيل المثال، إذا كان TextField يقبل رقم هاتف أمريكيًا، يمكنك قبول 10 أرقام فقط. يتم حفظ نتائج InputTransformation في TextFieldState.

تتوفّر فلاتر مضمّنة لحالات استخدام InputTransformation الشائعة. لتقييد الطول، يُرجى الاتصال بالرقم InputTransformation.maxLength():

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine,
    inputTransformation = InputTransformation.maxLength(10)
)
StateBasedText.kt

عمليات تحويل الإدخال المخصّصة

InputTransformation هي واجهة دالة واحدة. عند تنفيذ InputTransformation المخصّصة، عليك إلغاء أثر TextFieldBuffer.transformInput:

class CustomInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
    }
}
StateBasedText.kt

بالنسبة إلى رقم الهاتف، أضِف عملية تحويل إدخال مخصّصة تسمح فقط بكتابة الأرقام في TextField:

class DigitOnlyInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
        if (!TextUtils.isDigitsOnly(asCharSequence())) {
            revertAllChanges()
        }
    }
}
StateBasedText.kt

عمليات تحويل إدخال السلسلة

لإضافة فلاتر متعددة إلى النص الذي تُدخله، يمكنك ربط رمز InputTransformation باستخدام دالة التوسيع then. يتم تنفيذ الفلاتر بشكل تسلسلي. من بين أفضل الممارسات، تطبيق الفلاتر الأكثر انتقائية أولاً لتجنُّب عمليات التحويل غير الضرورية على البيانات التي ستتم فلترتها في النهاية.

TextField(
    state = rememberTextFieldState(),
    inputTransformation = InputTransformation.maxLength(6)
        .then(CustomInputTransformation()),
)
StateBasedText.kt

بعد إضافة عمليات تحويل الإدخال، يقبل الإدخال TextField 10 أرقام كحد أقصى.

تنسيق الإدخال قبل عرضه

تتيح لك OutputTransformation تنسيق إدخال المستخدم قبل عرضه على الشاشة. على عكس InputTransformation، لا يتم حفظ التنسيق الذي يتم إجراؤه من خلال OutputTransformation في TextFieldState. استنادًا إلى مثال رقم الهاتف السابق، عليك إضافة قوسَين وشرطة في المواضع المناسبة:

هذه هي الطريقة المعدّلة للتعامل مع VisualTransformation في TextField المستندة إلى القيمة، مع الاختلاف الرئيسي في أنّه ليس عليك احتساب عمليات ربط العناصر المرجعية.

OutputTransformation هي واجهة طريقة مجردة واحدة. لتطبيق OutputTransformation مخصّص، عليك إلغاء طريقة transformOutput:

class CustomOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
    }
}
StateBasedText.kt

لتنسيق رقم هاتف، أضِف قوسًا مفتوحًا في الفهرس 0 وقوسًا مغلقًا في الفهرس 4 واصلة في الفهرس 8 إلى OutputTransformation:

class PhoneNumberOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
}
StateBasedText.kt

بعد ذلك، أضِف OutputTransformation إلى TextField:

TextField(
    state = rememberTextFieldState(),
    outputTransformation = PhoneNumberOutputTransformation()
)
StateBasedText.kt

آلية عمل عمليات التحويل معًا

يوضّح المخطّط البياني التالي عملية التحويل من إدخال النص إلى المعالجة ثم إلى المخرجات:

1. يتم استلام الإدخال من مصدر الإدخال.
2. تتم فلترة الإدخال من خلال InputTransformation، ويتم حفظه في TextFieldState.
3. يتم تمرير الإدخال من خلال OutputTransformation لتنسيقه.
4. يتم عرض الإدخال في TextField.

ضبط خيارات لوحة المفاتيح

يتيح لك الخيار TextField ضبط خيارات إعدادات لوحة المفاتيح، مثل TextFieldتنسيق لوحة المفاتيح، أو تفعيل ميزة التصحيح التلقائي إذا كانت لوحة المفاتيح تتيح ذلك. قد لا يكون بالإمكان ضمان بعض الخيارات إذا لم تكن لوحة المفاتيح البرمجية متوافقة مع الخيارات المقدَّمة هنا. في ما يلي قائمة بإعدادات لوحة المفاتيح المتوافقة:

• capitalization
• autoCorrect
• keyboardType
• imeAction

تتضمّن فئة KeyboardOptions الآن مَعلمة منطقية جديدة، showKeyboardOnFocus، يتم استخدامها تحديدًا لمكوّنات TextField المدمجة مع TextFieldState. يحدِّد هذا الخيار سلوك لوحة المفاتيح البرمجية عندما يحصل TextField على التركيز من خلال وسائل أخرى غير التفاعل المباشر مع المستخدم (على سبيل المثال، آليًا).

عند ضبط KeyboardOptions.showKeyboardOnFocus على true، لا تظهر لوحة المفاتيحبرمجيًا تلقائيًا إذا اكتسب TextField التركيز بشكل غير مباشر. في هذه الحالات، على المستخدم النقر صراحةً على TextField نفسه لكشف لوحة المفاتيح.

تحديد منطق التفاعل مع لوحة المفاتيح

يتيح زر الإجراء في لوحة المفاتيح البرمجية لنظام التشغيل Android تقديم ردود تفاعلية داخل تطبيقك. لمزيد من المعلومات عن ضبط زر الإجراء، اطّلِع على القسم ضبط خيارات لوحة المفاتيح.

لتحديد ما يحدث عندما ينقر المستخدم على زر الإجراء هذا، استخدِم المَعلمة onKeyboardAction. تقبل هذه المَعلمة واجهة وظيفية اختيارية باسم KeyboardActionHandler. تحتوي واجهة KeyboardActionHandler على طريقة واحدة، وهي onKeyboardAction(performDefaultAction: () -> Unit). من خلال توفير طريقة تنفيذ لهذه الطريقة onKeyboardAction، يمكنك إدخال منطق مخصّص يتم تنفيذه عندما يضغط المستخدم على زر الإجراء في لوحة المفاتيح.

تتضمّن العديد من أنواع إجراءات لوحة المفاتيح العادية سلوكيات تلقائية مدمجة. على سبيل المثال، سيؤدي اختيار ImeAction.Next أو ImeAction.Previous كنوع الإجراء إلى نقل التركيز تلقائيًا إلى حقل الإدخال التالي أو السابق، على التوالي. وبالمثل، يؤدي زر الإجراء الذي تم ضبطه على ImeAction.Done عادةً إلى إغلاق لوحة المفاتيح البرمجية. يتم تنفيذ هذه الوظائف التلقائية تلقائيًا ولا تتطلّب منك تقديم KeyboardActionHandler.

يمكنك أيضًا تنفيذ سلوك مخصّص بالإضافة إلى هذه الإجراءات التلقائية. عند تقديم KeyboardActionHandler، تتلقّى طريقة onKeyboardAction دالة performDefaultAction. يمكنك استدعاء دالة performDefaultAction() هذه في أيّ وقت ضمن منطقك المخصّص لبدء السلوك التلقائي العادي المرتبط بإجراء IME الحالي أيضًا.

TextField(
    state = textFieldViewModel.usernameState,
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
    onKeyboardAction = { performDefaultAction ->
        textFieldViewModel.validateUsername()
        performDefaultAction()
    }
)
StateBasedText.kt

يوضّح هذا المقتطف حالة استخدام شائعة على شاشة تسجيل تتضمّن حقل اسم مستخدم. بالنسبة إلى هذا الحقل، تم اختيار ImeAction.Next لزرّ إجراء لوحة المفاتيح. يتيح هذا الخيار التنقّل بسرعة وسلاسة إلى حقل كلمة المرور التالي.

بالإضافة إلى عملية التنقّل العادية هذه، يجب بدء عملية تحقّق في الخلفية لاسم المستخدم أثناء تقدّم المستخدم لإدخال كلمة المرور. لضمان الاحتفاظ بالسلوك التلقائي للتبديل بين عناصر التركيز المضمّن في ImeAction.Next إلى جانب منطق التحقّق المخصّص هذا، يتمّ استدعاء الدالة performDefaultAction(). يؤدي استدعاء performDefaultAction() بشكل ضمني إلى تنشيط نظام إدارة التركيز الأساسي لنقل التركيز إلى عنصر واجهة المستخدم المناسب التالي، مع الحفاظ على تدفق التنقّل المتوقّع.

إنشاء حقل كلمة مرور آمن

SecureTextField هو عنصر قابل للتجميع تم إنشاؤه على أساس حقول النصوص المستندة إلى الحالة لكتابة حقل كلمة مرور. ننصحك باستخدام SecureTextField لإنشاء حقول نصية لكلمات المرور، لأنّه يخفي إدخال الأحرف تلقائيًا ويوقف إجراءات القص والنسخ.

يحتوي SecureTextField على textObfuscationMode، الذي يتحكّم في كيفية ظهور إدخال الشخصيات للمستخدم. تتوفّر لـ textObfuscationMode الخيارات التالية:

• Hidden: لإخفاء كل البيانات التي أدخلتها السلوك التلقائي على منصات أجهزة الكمبيوتر المكتبي

  

• Visible: تعرِض كل الإدخالات.

  

• RevealLastTyped: لإخفاء كل الإدخالات باستثناء الحرف الأخير السلوك التلقائي على الأجهزة الجوّالة

  

مراجع إضافية

• تنسيق رقم هاتف تلقائيًا في حقل نصي
• إظهار كلمة المرور أو إخفاؤها استنادًا إلى خيار تفعيل/إيقاف لدى المستخدم
• التحقّق من صحة الإدخال أثناء كتابته