تسمح TextField
للمستخدمين بإدخال النص وتعديله. هناك نوعان من حقول النص التي يمكنك استخدامها: حقول النص المستندة إلى الحالة وحقول النص المستندة إلى القيمة. اختَر النوع الذي تريد عرض المحتوى الخاص به:
ننصحك باستخدام حقول نصية مستندة إلى الحالة، لأنّها توفّر طريقة أكثر اكتمالاً وموثوقية لإدارة حالة TextField
. يوضّح الجدول التالي الاختلافات بين هذه الأنواع من حقول النصوص، ويتضمّن المزايا الرئيسية التي توفّرها حقول النصوص المستندة إلى الحالة:
الميزة |
الحقول النصية المستندة إلى القيمة |
الحقول النصية المستندة إلى الولاية |
المزايا المستندة إلى الولاية |
---|---|---|---|
إدارة الحالة |
تعدّل هذه السمة حالة الحقل النصي باستخدام دالة معاودة الاتصال |
يستخدم صراحةً عنصر |
|
التحويل المرئي |
يستخدم |
يستخدم |
|
الحدود القصوى للأسطر |
يقبل |
يتم استخدام |
|
حقل نص آمن |
لا ينطبق |
|
|
توضّح هذه الصفحة كيفية تنفيذ TextField
وتنسيق إدخال TextField
وضبط خيارات TextField
الأخرى، مثل خيارات لوحة المفاتيح وتحويل إدخال المستخدم بشكل مرئي.
اختيار تنفيذ TextField
هناك مستويان لتنفيذ TextField
:
TextField
هو تنفيذ Material Design. ننصحك باختيار هذا التنفيذ لأنّه يتّبع إرشادات Material Design:- تتيح السمة
BasicTextField
للمستخدمين تعديل النص باستخدام لوحة مفاتيح خارجية أو لوحة مفاتيح على الشاشة، ولكنّها لا توفّر أي عناصر زخرفية، مثل تلميح أو عنصر نائب.
TextField( state = rememberTextFieldState(initialText = "Hello"), label = { Text("Label") } )
OutlinedTextField( state = rememberTextFieldState(), label = { Text("Label") } )
النمط 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) )
ننصحك باستخدام TextField
بدلاً من BasicTextField
عندما يتطلّب تصميمك استخدام TextField
أو OutlinedTextField
من Material. ومع ذلك، يجب استخدام BasicTextField
عند إنشاء تصاميم لا تحتاج إلى الزخارف من مواصفات Material Design.
ضبط حدود الأسطر
تتيح عناصر TextField
القابلة للإنشاء إمكانية التمرير على طول محور واحد. يتم تحديد سلوك التمرير من خلال المَعلمة lineLimits
. يتم ضبط TextField
s للتمرير الأفقي لسطر واحد، بينما يتم ضبط TextField
s المتعددة الأسطر للتمرير العمودي.
استخدِم TextFieldLineLimits
لاختيار إعدادات الخط المناسبة TextField
:
TextField( state = rememberTextFieldState(), lineLimits = TextFieldLineLimits.SingleLine )
يتضمّن إعداد SingleLine
الخصائص التالية:
- لا يتم تضمين النص أبدًا، ولا يسمح بإضافة أسطر جديدة.
- يتميّز عنصر
TextField
دائمًا بارتفاع ثابت. - إذا كان النص يتجاوز المساحة المخصّصة له، سيتم تمريره أفقيًا.
TextField( state = rememberTextFieldState("Hello\nWorld\nHello\nWorld"), lineLimits = TextFieldLineLimits.MultiLine(1, 4) )
يتضمّن إعداد 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) )

TextField
إدارة حالة حقل النص
تستخدم TextField
فئة مخصّصة لتخزين الحالة تُسمى TextFieldState
من أجل المحتوى والاختيار الحالي. تم تصميم TextFieldState
ليتم رفعه
أينما كان ذلك مناسبًا في بنية تطبيقك. هناك سمتان رئيسيتان يوفّرهما TextFieldState
:
initialText
: محتوىTextField
initialSelection
: يشير إلى مكان وجود المؤشر أو التحديد حاليًا.
ما يميّز TextFieldState
عن الطرق الأخرى، مثل
onValueChange
، هو أنّ TextFieldState
يغلف بالكامل تدفق الإدخال بأكمله. ويشمل ذلك استخدام هياكل البيانات الأساسية الصحيحة، وتضمين الفلاتر وعناصر التنسيق، ومزامنة جميع التعديلات الواردة من مصادر مختلفة.
يمكنك استخدام TextFieldState()
لنقل الحالة إلى أعلى في TextField
. لهذا الغرض، ننصحك باستخدام الدالة rememberTextFieldState()
.
تنشئ rememberTextFieldState()
مثيل TextFieldState
في العنصر القابل للإنشاء، وتضمن تذكُّر عنصر الحالة، وتوفّر وظائف مدمجة للحفظ والاستعادة:
val usernameState = rememberTextFieldState() TextField( state = usernameState, lineLimits = TextFieldLineLimits.SingleLine, placeholder = { Text("Enter Username") } )
يمكن أن يحتوي rememberTextFieldState
على مَعلمة فارغة أو قيمة أولية تم تمريرها
لتمثيل قيمة النص عند التهيئة. إذا تم تمرير قيمة مختلفة
في عملية إعادة إنشاء لاحقة، لن يتم تعديل قيمة الحالة. لتعديل الحالة بعد تهيئتها، استخدِم طرق التعديل في TextFieldState
.
TextField( state = rememberTextFieldState(initialText = "Username"), lineLimits = TextFieldLineLimits.SingleLine, )

TextField
مع "اسم المستخدم" كنص أوليتعديل النص باستخدام 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, "-") } )
تعديل النص في 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)
setTextAndPlaceCursorAtEnd
: يمحو النص الحالي ويستبدله بالنص المحدّد، ثم يضع المؤشر في النهاية.usernameState.setTextAndPlaceCursorAtEnd("I really love Android") // textFieldState.text : I really love Android // textFieldState.selection : TextRange(21, 21)
clearText
: لمحو كل النصusernameState.clearText() // textFieldState.text : // textFieldState.selection : TextRange(0, 0)
للاطّلاع على دوال TextFieldState
الأخرى، يُرجى الرجوع إلى مرجع TextFieldState
.
تعديل بيانات أدخلها المستخدم
توضّح الأقسام التالية كيفية تعديل إدخال المستخدم.
تتيح لك عملية تحويل الإدخال فلترة TextField
الإدخال أثناء الكتابة، بينما تعمل عملية تحويل الإخراج على تنسيق إدخال المستخدم قبل عرضه على الشاشة.
فلترة إدخال المستخدم باستخدام عمليات تحويل الإدخال
يتيح لك تحويل الإدخال فلترة الإدخال من المستخدم. على سبيل المثال، إذا كان TextField
يقبل رقم هاتف أمريكيًا، عليك قبول 10 أرقام فقط. يتم حفظ نتائج InputTransformation
في TextFieldState
.
تتوفّر فلاتر مضمّنة لحالات الاستخدام الشائعة في InputTransformation
. لضبط حد أقصى للطول، يُرجى الاتصال بالرقم InputTransformation.maxLength()
:
TextField( state = rememberTextFieldState(), lineLimits = TextFieldLineLimits.SingleLine, inputTransformation = InputTransformation.maxLength(10) )
عمليات تحويل الإدخال المخصّص
InputTransformation
هي واجهة وظيفة واحدة. عند تنفيذ InputTransformation
المخصّص، عليك إلغاء TextFieldBuffer.transformInput
:
class CustomInputTransformation : InputTransformation { override fun TextFieldBuffer.transformInput() { } }
بالنسبة إلى رقم الهاتف، أضِف عملية تحويل مخصّصة للإدخال لا تسمح إلا بإدخال الأرقام في TextField
:
class DigitOnlyInputTransformation : InputTransformation { override fun TextFieldBuffer.transformInput() { if (!TextUtils.isDigitsOnly(asCharSequence())) { revertAllChanges() } } }
عمليات تحويل إدخال السلسلة
لإضافة فلاتر متعددة على إدخال النص، اربط InputTransformation
s باستخدام دالة إضافة then
. يتم تنفيذ الفلاتر بالتسلسل. من أفضل الممارسات، تطبيق الفلاتر الأكثر تحديدًا أولاً لتجنُّب عمليات التحويل غير الضرورية على البيانات التي سيتم استبعادها في النهاية.
TextField( state = rememberTextFieldState(), inputTransformation = InputTransformation.maxLength(6) .then(CustomInputTransformation()), )
بعد إضافة عمليات تحويل الإدخال، يقبل الإدخال TextField
10 أرقام
كحد أقصى.
تنسيق الإدخال قبل عرضه
تتيح لك OutputTransformation
s تنسيق إدخال المستخدم قبل عرضه على الشاشة. على عكس InputTransformation
، لا يتم حفظ التنسيق الذي يتم إجراؤه من خلال OutputTransformation
في TextFieldState
. استنادًا إلى مثال رقم الهاتف السابق، عليك إضافة أقواس وشرطات في المواضع المناسبة:

هذه هي الطريقة المعدَّلة للتعامل مع VisualTransformation
في TextField
المستندة إلى القيمة، ويتمثّل الاختلاف الرئيسي في أنّك لست بحاجة إلى احتساب عمليات الربط بين الإزاحات.
OutputTransformation
هي واجهة طريقة مجرّدة واحدة. لتنفيذ OutputTransformation
مخصّص، عليك إلغاء طريقة transformOutput
:
class CustomOutputTransformation : OutputTransformation { override fun TextFieldBuffer.transformOutput() { } }
لتنسيق رقم هاتف، أضِف قوسًا مفتوحًا في الفهرس 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, "-") } }
بعد ذلك، أضِف OutputTransformation
إلى TextField
:
TextField( state = rememberTextFieldState(), outputTransformation = PhoneNumberOutputTransformation() )
طريقة عمل عمليات التحويل معًا
يوضّح المخطّط البياني التالي عملية الانتقال من إدخال النص إلى تحويله إلى إخراج:

- يتم تلقّي الإدخال من مصدر الإدخال.
- يتم فلترة الإدخال من خلال
InputTransformation
، ويتم حفظه في TextFieldState. - يتم تمرير الإدخال من خلال
OutputTransformation
للتنسيق. - يتم عرض الإدخال في
TextField
.
ضبط خيارات لوحة المفاتيح
تتيح لك TextField
ضبط خيارات إعدادات لوحة المفاتيح، مثل تخطيط لوحة المفاتيح، أو تفعيل التصحيح التلقائي إذا كانت لوحة المفاتيح تتيح ذلك. قد لا تتوفّر بعض الخيارات إذا لم تتوافق لوحة المفاتيح البرمجية مع الخيارات الموضّحة هنا. في ما يلي قائمة خيارات لوحة المفاتيح المتوافقة:
capitalization
autoCorrect
keyboardType
imeAction
يتضمّن الصف KeyboardOptions
الآن مَعلمة منطقية جديدة،
showKeyboardOnFocus
، يمكنك استخدامها خصيصًا لمكوّنات TextField
المدمجة مع TextFieldState
. يتحكّم هذا الخيار في سلوك لوحة المفاتيح البرمجية عندما يكتسب العنصر TextField
التركيز من خلال وسائل أخرى غير تفاعل المستخدم المباشر (على سبيل المثال، بشكل آلي).
عندما يتم ضبط KeyboardOptions.showKeyboardOnFocus
على "صحيح"، لن تظهر لوحة المفاتيح البرمجية تلقائيًا إذا اكتسبت 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() } )
يوضّح هذا المقتطف حالة استخدام شائعة على شاشة تسجيل تتضمّن حقل اسم مستخدم. بالنسبة إلى هذا الحقل، تم اختيار ImeAction.Next
لزر إجراء لوحة المفاتيح. يتيح هذا الخيار التنقّل بسرعة وسلاسة إلى حقل كلمة المرور التالي.
بالإضافة إلى عملية التنقّل العادية هذه، يجب بدء عملية تحقّق في الخلفية من اسم المستخدم أثناء إدخال المستخدم لكلمة المرور. لضمان الاحتفاظ بسلوك التبديل التلقائي للتركيز المتأصّل في ImeAction.Next
إلى جانب منطق التحقّق المخصّص هذا، يتم استدعاء الدالة performDefaultAction()
. يؤدي استدعاء performDefaultAction()
إلى تشغيل نظام إدارة التركيز الأساسي ضمنيًا لنقل التركيز إلى عنصر واجهة المستخدم المناسب التالي، ما يحافظ على مسار التنقّل المتوقّع.
إنشاء حقل لكلمة مرور آمنة
SecureTextField
هي عنصر قابل للإنشاء مدمج في أعلى حقول النص المستندة إلى الحالة
لكتابة حقل كلمة المرور. ننصحك باستخدام SecureTextField
لإنشاء حقول نصية خاصة بكلمات المرور، لأنّها تخفي إدخال الأحرف تلقائيًا وتوقف إجراءَي القص والنسخ.
يحتوي SecureTextField
على textObfuscationMode
يتحكّم في طريقة عرض
إدخال الأحرف للمستخدم. يتضمّن textObfuscationMode
الخيارات التالية:
Hidden
: لإخفاء جميع المدخلات السلوك التلقائي على منصات أجهزة الكمبيوتر
Visible
: تعرض جميع المدخلات.RevealLastTyped
: يخفي جميع المدخلات باستثناء الحرف الأخير. السلوك التلقائي على الأجهزة الجوّالة
مراجع إضافية
- تنسيق رقم هاتف تلقائيًا في حقل نصي
- إظهار كلمة المرور أو إخفاؤها استنادًا إلى مفتاح تبديل المستخدم
- التحقّق من صحة الإدخال أثناء الكتابة
أفلام مُقترَحة لك
- ملاحظة: يتم عرض نص الرابط عندما تكون JavaScript غير مفعّلة
- تصميم بنية واجهة مستخدم Compose
- الحالة وJetpack Compose
- حفظ حالة واجهة المستخدم في Compose