Android Academy · درس

TextField وإدخال المستخدم

التقط نصًا من المستخدم في Compose

TextField وإدخال المستخدم درس مجاني في Android Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Android Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Android Academy 4 دروس في المجموع.

التقاط إدخال المستخدم

يحتاج كل تطبيق فعلي تقريبًا إلى أن يطلب من المستخدم إدخال شيء ما: اسمًا أو بريدًا إلكترونيًا أو استعلام بحث. وفي Jetpack Compose، فإن اللبنة الأساسية لإدخال النص هي TextField.

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

أول TextField لك

يحتاج TextField إلى أمرين: value (النص الحالي المطلوب عرضه) واستدعاء onValueChange (الإجراء المطلوب عند كتابة المستخدم).

بما أن Compose تصريحي، فلا يخزّن الحقل نصه بنفسه. بل تحتفظ أنت بالنص في الحالة وتعيد تمريره إليه. يُسمّى هذا النمط رفع الحالة.

@Composable
fun NameField() {
    var name by remember { mutableStateOf("") }

    TextField(
        value = name,
        onValueChange = { name = it }
    )
}

آلية حلقة القيمة

الفكرة الأهم على الإطلاق هي أن TextField يعرض تمامًا ما تمرّره إلى value. وعندما يضغط المستخدم مفتاحًا، تستدعي Compose onValueChange مع النص الجديد.

تحفظ النص الجديد في الحالة.
تؤدي تغييرات الحالة إلى إعادة التركيب.
يُعاد رسم الحقل باستخدام value المحدّثة.

إذا نسيت تحديث الحالة داخل onValueChange، فسيبدو الحقل متجمّدًا لأن value لن تتغير أبدًا.

var name by remember { mutableStateOf("") }

TextField(
    value = name,
    onValueChange = { newText -> name = newText }
)

إضافة تسمية ونص نائب

لا يوضح حقل النص المجرد للمستخدم ما الذي ينبغي كتابته. أضف label (تطفو أعلى الحقل) وplaceholder (تلميح يظهر عندما يكون الحقل فارغًا).

تجعل هذه اللمسات الصغيرة فهم النماذج أسهل بكثير.

var email by remember { mutableStateOf("") }

TextField(
    value = email,
    onValueChange = { email = it },
    label = { Text("Email") },
    placeholder = { Text("you@example.com") }
)

OutlinedTextField

يوفّر Material Design نمطين رئيسيين. يحتوي TextField على خلفية ممتلئة، بينما يرسم OutlinedTextField حدًا حول الحقل. ويشترك الاثنان في واجهة برمجة التطبيقات نفسها، لذا فإن التبديل بينهما سهل جدًا.

تحظى الحقول ذات الحدود بشعبية في النماذج لأنها تبدو واضحة عند ترتيبها عموديًا.

var username by remember { mutableStateOf("") }

OutlinedTextField(
    value = username,
    onValueChange = { username = it },
    label = { Text("Username") },
    singleLine = true
)

أيقونات البداية والنهاية

يمكنك تزيين الحقل بالأيقونات. تظهر leadingIcon في البداية (وهي مناسبة لأيقونة البحث أو البريد الإلكتروني)، وتظهر trailingIcon في النهاية (وغالبًا ما تكون زر مسح).

توضح الأيقونات الغرض من الحقل بلمحة واحدة.

var query by remember { mutableStateOf("") }

OutlinedTextField(
    value = query,
    onValueChange = { query = it },
    label = { Text("Search") },
    leadingIcon = {
        Icon(Icons.Default.Search, contentDescription = null)
    }
)

زر مسح

من أنماط تجربة المستخدم الشائعة عرض رمز صغير على شكل "x" لمسح الحقل. اعرضه فقط عند وجود نص، باستخدام موضع trailingIcon وIconButton.

لاحظ أن المسح لا يتطلب سوى إعادة الحالة إلى سلسلة نصية فارغة.

var text by remember { mutableStateOf("") }

OutlinedTextField(
    value = text,
    onValueChange = { text = it },
    label = { Text("Note") },
    trailingIcon = {
        if (text.isNotEmpty()) {
            IconButton(onClick = { text = "" }) {
                Icon(Icons.Default.Clear, contentDescription = "Clear")
            }
        }
    }
)

سطر واحد مقابل عدة أسطر

يمكن أن يمتد TextField افتراضيًا إلى عدة أسطر. وبالنسبة إلى أشياء مثل الاسم أو البريد الإلكتروني، عيّن singleLine = true حتى لا يتمكن المستخدم من إدراج سطر جديد.

أما بالنسبة إلى الملاحظات الأطول، فاتركه متعدد الأسطر، ويمكنك اختياريًا تحديد الارتفاع باستخدام maxLines.

var bio by remember { mutableStateOf("") }

OutlinedTextField(
    value = bio,
    onValueChange = { bio = it },
    label = { Text("Bio") },
    maxLines = 4
)

الاستجابة للإدخال مباشرةً

بما أنك تملك حالة النص، يمكنك الاستجابة لها فورًا. ومن الأمثلة الشائعة عرض عدد الأحرف مباشرةً أسفل الحقل.

يحدّث كل ضغط على مفتاح text، مما يعيد تركيب الحقل والعدد الموجود أسفله.

var text by remember { mutableStateOf("") }

Column {
    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Tweet") }
    )
    Text("${text.length} / 280")
}

تحويل الإدخال

قد ترغب أحيانًا في تسوية ما يكتبه المستخدم قبل تخزينه. ويمكنك داخل onValueChange تحويل القيمة الجديدة أولًا.

نحوّل اسم المستخدم هنا إلى أحرف صغيرة ونزيل المسافات. وبما أنك تتحكم في الحلقة، يعرض الحقل دائمًا النسخة المنظّفة.

var handle by remember { mutableStateOf("") }

OutlinedTextField(
    value = handle,
    onValueChange = { input ->
        handle = input.lowercase().filterNot { it.isWhitespace() }
    },
    label = { Text("Handle") },
    singleLine = true
)

Kotlin خالصة: تنظيف المعرّف

منطق التحويل الوارد أعلاه عبارة عن Kotlin عادية تمامًا. ويمكنك اختباره بمعزل عن التطبيق، من دون الحاجة إلى Android. إليك قاعدة التنظيف نفسها وهي تعمل بشكل مستقل.

يسهّل إبقاء منطق كهذا داخل دوال خالصة إجراء اختبارات الوحدات.

fun cleanHandle(input: String): String =
    input.lowercase().filterNot { it.isWhitespace() }

fun main() {
    println(cleanHandle("  John Doe "))
    println(cleanHandle("ADA Lovelace"))
}

اختبار سريع

ماذا يحدث إذا لم يحدّث استدعاء onValueChange الخاص بـ TextField الحالة التي مرّرتها إلى value؟

مراجعة

أصبحت تعرف الآن أساسيات إدخال النص في Compose:

يستقبل TextField وOutlinedTextField قيمة value واستدعاء onValueChange.
تحتفظ بالنص في remember { mutableStateOf(...) } وتحدّثه عند كل تغيير (رفع الحالة).
تحدد label وplaceholder وأيقونات البداية والنهاية وsingleLine المظهر والسلوك.
وبما أنك تملك الحالة، يمكنك الاستجابة مباشرةً أو تحويل الإدخال أثناء كتابة المستخدم.

التالي: إدارة حالة نموذج كامل، وليس حقلًا واحدًا فقط.

الأسئلة الشائعة

هل درس «TextField وإدخال المستخدم» مجاني؟

نعم — نص درس «TextField وإدخال المستخدم» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Android Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Android Academy 4 دروس في المجموع.

ماذا ستتعلم في «TextField وإدخال المستخدم»؟

التقط نصًا من المستخدم في Compose تتمرن على Android Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Android Academy؟

لا تُشترط خبرة سابقة. Android Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «TextField وإدخال المستخدم»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Android Academy هذا؟

نعم. كل درس في Android Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Android Academy