الملء التلقائي في وضع الإنشاء

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الشكل 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

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

     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

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

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

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

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

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

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

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

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

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

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

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

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

لتخصيص لون التمييز هذا، استخدِم 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