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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

val customHighlightColor = Color.Red

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