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

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

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

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

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

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

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

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

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

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

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

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

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

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

للإشارة إلى أنّ 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، لن تحتاج إلى اتّخاذ أي إجراء آخر ليتمكّن المستخدمون من ملء بيانات الاعتماد.

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

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

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

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

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

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

     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

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

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

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

استنادًا إلى موفّر بيانات الاعتماد، عندما تستخدم نوعَي المحتوى 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