الملء التلقائي في ميزة "الإنشاء"

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

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

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

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

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

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

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

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

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

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

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

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

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

الشكل 1. صفحة إعدادات تعرض كيفية تحديد موفِّر بيانات الاعتماد

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

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

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

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

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

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

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

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

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

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

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

الشكل 2. شرائح في شريط أدوات النص تعرِض بيانات اعتماد المحفوظة

توفير البيانات باستخدام ميزة "الملء التلقائي" أثناء التنقّل

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

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

لحفظ بيانات اعتماد جديدة بشكل صريح من خلال حقول نصية باستخدام ميزة "الملء التلقائي"، يجب أن يُجري مدير "الملء التلقائي" عملية إرسال (أو إلغاء) لسياق "الملء التلقائي". بعد ذلك، يتواصل مدير "الملء التلقائي" المحلي مع إطار عمل "الملء التلقائي" متى دعت الحاجة. إذا كنت تريد إزالة بيانات الاعتماد التي أدخلها المستخدم، يمكنك استدعاء ‎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

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

   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 },
       )
   
       // Submit button
       Button(onClick = { autofillManager?.commit() }) { Text("Reset credentials") }
   }
   AutofillSnippets.kt

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

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

الشكل 3. بطاقة سفلية تطلب من المستخدمين حفظ كلمة المرور

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

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

الشكل 4. شريحة "اقتراح كلمة مرور قوية" في شريط أدوات لوحة المفاتيح

الشكل 5. بطاقة سفلية تطلب من المستخدمين استخدام كلمة مرور قوية

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

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

الشكل 6: بطاقة سفلية تطلب من المستخدمين حفظ كلمة المرور

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

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

لتخصيص لون التمييز هذا، استخدِم CompositionLocal وقدِّم أي لون تريده.

val customHighlightColor = Color.Red

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

يتم تحديد اللون التلقائي لتمييز النص في ميزة "الملء التلقائي" على أنّه Color(0x4dffeb3b).