الملء التلقائي في Compose

يمكن لبعض التطبيقات، مثل مديري كلمات المرور، ملء المكوّنات في تطبيقات أخرى بالبيانات التي يقدّمها المستخدم. تُعرف التطبيقات التي تملأ مكوّنات تطبيقات أخرى باسم خدمات الملء التلقائي. يدير إطار الملء التلقائي عملية التواصل بين التطبيق وخدمة الملء التلقائي.

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

يمكنك تنفيذ ميزة "الملء التلقائي" في Compose باستخدام بضعة أسطر فقط من الرموز. تقدّم هذه الميزة المزايا التالية للمستخدمين:

ملء بيانات الاعتماد

تسمح ميزة "الملء التلقائي" للمستخدمين بملء بيانات اعتمادهم بالطُرق التالية:

• يعرض النظام اقتراحات "الملء التلقائي" للمستخدم عندما ينقر على حقل تم ضبط دلالات "الملء التلقائي" فيه.
• يعرض النظام اقتراحات "الملء التلقائي" للمستخدم ويصفّيها استنادًا إلى ما يكتبه المستخدم.

حفظ بيانات الاعتماد

يمكن للمستخدمين حفظ بيانات الاعتماد من خلال ميزة "الملء التلقائي" بالطُرق التالية:

• يعرض النظام مربّع حوار للحفظ يطلب من المستخدم حفظ المعلومات عندما يُدخل معلومات جديدة أو معدَّلة في حقل مفعَّلة فيه ميزة "الملء التلقائي". يمكن إجراء عملية الحفظ بطريقتَين:
  • صراحةً، من خلال إرسال المعلومات (على سبيل المثال، من خلال النقر على زر)
  • ضمنيًا، عندما ينتقل المستخدم بعيدًا عن الصفحة
• استنادًا إلى مقدّم بيانات الاعتماد، قد يقترح النظام كلمة مرور قوية على المستخدم عندما يتم ضبط ContentType.NewPassword لحقل معيّن.

يمكنك استخدام ميزة "الملء التلقائي" في تطبيقك لتبسيط عملية استرداد البيانات المحفوظة للمستخدمين. تتوافق ميزة "الملء التلقائي" مع مكوّنات النص من خلال BasicTextField وجميع حقول نص التصميم المتعدد الأبعاد التي تستند إلى هذا المكوّن.

إعداد الملء التلقائي

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

إضافة ميزة "الملء التلقائي" إلى حقل النص باستخدام نوع المحتوى

للإشارة إلى أنّ TextField مفعَّلة فيه ميزة "الملء التلقائي"، اضبط دلالات ContentType باستخدام الأنواع التي يمكن أن يقبلها الحقل. يشير ذلك إلى خدمات "الملء التلقائي" إلى نوع بيانات المستخدم التي قد تكون ذات صلة بهذا الحقل تحديدًا. استخدِم ContentType.Username لضبط TextField يمكن للمستخدمين ملؤه باسم المستخدم.

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

حقل نص مستند إلى القيمة

TextField(
    value = textFieldValue.value,
    onValueChange = { textFieldValue.value = it },
    modifier = Modifier.semantics { contentType = ContentType.Username }
)
AutofillSnippets.kt

حقل نص مستند إلى الحالة

TextField(
    state = rememberTextFieldState(),
    modifier = Modifier.semantics { contentType = ContentType.Username }
)
AutofillSnippets.kt

إضافة حقول "الملء التلقائي" بأنواع متعددة

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

للاطّلاع على جميع أنواع البيانات المتاحة للحفظ باستخدام ميزة "الملء التلقائي"، يُرجى الرجوع إلى مرجع ContentType .

حقل نص مستند إلى القيمة

TextField(
    value = textFieldValue.value,
    onValueChange = { textFieldValue.value = it },
    modifier = Modifier.semantics {
        contentType = ContentType.Username + ContentType.EmailAddress
    }
)
AutofillSnippets.kt

حقل نص مستند إلى الحالة

TextField(
    state = rememberTextFieldState(),
    modifier = Modifier.semantics {
        contentType = ContentType.Username + ContentType.EmailAddress
    }
)
AutofillSnippets.kt

ملء البيانات باستخدام ميزة "الملء التلقائي"

عند إضافة ContentType في TextField، لن تحتاج إلى اتخاذ أي إجراء آخر ليتمكّن المستخدمون من ملء بيانات الاعتماد.

عندما ينقر المستخدم على حقل مفعَّلة فيه ميزة "الملء التلقائي"، إذا كانت هناك بيانات ذات صلة مخزّنة، ستظهر له شريحة في شريط الأدوات أعلى لوحة المفاتيح تطلب منه ملء بيانات الاعتماد.

حفظ البيانات باستخدام ميزة "الملء التلقائي" من خلال التنقّل

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

حفظ البيانات صراحةً باستخدام ميزة "الملء التلقائي"

لحفظ بيانات اعتماد جديدة صراحةً من خلال حقول النص باستخدام ميزة "الملء التلقائي"، يجب إرسال سياق "الملء التلقائي" (أو إلغاؤه) من قِبل مدير "الملء التلقائي". بعد ذلك، يتواصل مدير "الملء التلقائي" المحلي مع إطار "الملء التلقائي" عند الضرورة. إذا أردت إزالة بيانات الاعتماد التي أدخلها المستخدم، استخدِم AutofillManager.cancel لحذف أي بيانات معلّقة بدون حفظها.

توضّح المقتطفات التالية كيفية حفظ البيانات باستخدام ميزة "الملء التلقائي" صراحةً باستخدام زر:

1. أنشئ متغيّرًا محليًا لتخزين مدير "الملء التلقائي"، الذي يمكن استرداده بالطريقة التالية:

   val autofillManager = LocalAutofillManager.current
   AutofillSnippets.kt

2. في TextField(s)، أضِف نوع المحتوى الذي اخترته من خلال Modifier.semantics

   • مع حقول النص المستندة إلى القيمة:

     val autofillManager = LocalAutofillManager.current
     
     Column {
         TextField(
             value = textFieldValue.value,
             onValueChange = { textFieldValue.value = it },
             modifier = Modifier.semantics { contentType = ContentType.NewUsername }
         )
     
         Spacer(modifier = Modifier.height(16.dp))
     
         TextField(
             value = textFieldValue.value,
             onValueChange = { textFieldValue.value = it },
             modifier = Modifier.semantics { contentType = ContentType.NewPassword }
         )
     }
     AutofillSnippets.kt

   • مع حقول النص المستندة إلى الحالة:

     val autofillManager = LocalAutofillManager.current
     
     Column {
         TextField(
             state = rememberTextFieldState(),
             modifier = Modifier.semantics { contentType = ContentType.NewUsername }
         )
     
         Spacer(modifier = Modifier.height(16.dp))
     
         TextField(
             state = rememberTextFieldState(),
             modifier = Modifier.semantics { contentType = ContentType.NewPassword }
         )
     }
     AutofillSnippets.kt

3. أرسِل سياق "الملء التلقائي" حسب الحاجة من خلال النقر على زر:

   • مع حقول النص المستندة إلى القيمة:

     val autofillManager = LocalAutofillManager.current
     
     Column {
         TextField(
             value = usernameTextFieldValue.value,
             onValueChange = { usernameTextFieldValue.value = it },
             modifier = Modifier.semantics { contentType = ContentType.NewUsername },
         )
     
         Spacer(modifier = Modifier.height(16.dp))
     
         TextField(
             value = passwordTextFieldValue.value,
             onValueChange = { passwordTextFieldValue.value = it },
             modifier = Modifier.semantics { contentType = ContentType.NewPassword },
         )
     
         // Submit button
         Button(onClick = { autofillManager?.commit() }) { Text("Reset credentials") }
     }
     AutofillSnippets.kt

   • مع حقول النص المستندة إلى الحالة:

     val autofillManager = LocalAutofillManager.current
     
     Column {
         TextField(
             state = rememberTextFieldState(),
             modifier = Modifier.semantics { contentType = ContentType.NewUsername },
         )
     
         Spacer(modifier = Modifier.height(16.dp))
     
         TextField(
             state = rememberTextFieldState(),
             modifier = Modifier.semantics { contentType = ContentType.NewPassword },
         )
     
         // Submit button
         Button(onClick = { autofillManager?.commit() }) { Text("Reset credentials") }
     }
     AutofillSnippets.kt

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

عندما ينقر المستخدم على الزر، ستظهر له هذه البطاقة السفلية التي تطلب منه حفظ بيانات الاعتماد في مقدّم بيانات الاعتماد المحدّد:

حفظ البيانات باستخدام ميزة "الملء التلقائي" من خلال "اقتراح كلمة مرور قوية"

استنادًا إلى مقدّم بيانات الاعتماد، عند استخدام نوعَي المحتوى NewUsername وNewPassword، قد يظهر للمستخدمين زر في لوحة المفاتيح لاقتراح كلمة مرور قوية. عند النقر على هذا الزر، تظهر بطاقة سفلية تسمح لهم بحفظ بيانات اعتمادهم. لست بحاجة إلى تنفيذ أي إجراء آخر ليتمكّن المستخدمون من الاستفادة من هذه الميزة.

تحديد المشاكل وحلّها

عند استدعاء رحلة المستخدم "الحفظ"، إذا نقرت على "ليس الآن" أكثر من مرة، قد لا يعرض مقدّم بيانات الاعتماد البطاقة السفلية بعد ذلك. لإعادة تفعيلها وظهورها مرة أخرى، عليك إزالة تطبيقات معيّنة حظرت عبارة "هل تريد تذكُّر كلمة المرور هذه؟".

تخصيص ميزة "الملء التلقائي" بشكل أكبر

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

لتخصيص لون التمييز هذا، استخدِم CompositionLocal وقدِّم أي لون تريده. تم تحديد لون التمييز التلقائي لميزة "الملء التلقائي" على أنّه Color(0x4dffeb3b).

حقول النص المستندة إلى القيمة

val customHighlightColor = Color.Red

CompositionLocalProvider(LocalAutofillHighlightColor provides customHighlightColor) {
    TextField(
        value = textFieldValue.value,
        onValueChange = { textFieldValue.value = it },
        modifier = Modifier.semantics { contentType = ContentType.Username }
    )
}
AutofillSnippets.kt

حقول النص المستندة إلى الحالة

val customHighlightColor = Color.Red

CompositionLocalProvider(LocalAutofillHighlightColor provides customHighlightColor) {
    TextField(
        state = rememberTextFieldState(),
        modifier = Modifier.semantics { contentType = ContentType.Username }
    )
}
AutofillSnippets.kt