تحسين تطبيقك للتوافق مع ميزة "الملء التلقائي"

تعمل التطبيقات التي تستخدم طرق العرض العادية مع إطار عمل الملء التلقائي بدون الحاجة إلى إعدادات خاصة. يمكنك أيضًا تحسين طريقة عمل تطبيقك مع إطار العمل.

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

يوضّح هذا القسم كيفية إعداد وظيفة الملء التلقائي الأساسية لتطبيقك.

ضبط خدمة ملء تلقائي

يجب ضبط خدمة ملء تلقائي على جهازك لكي يتمكّن تطبيقك من استخدام إطار عمل الملء التلقائي. على الرغم من أنّ معظم الهواتف والأجهزة اللوحية التي تعمل بنظام التشغيل Android 8.0 (مستوى واجهة برمجة التطبيقات 26) والإصدارات الأحدث تتضمّن خدمة ملء تلقائي، ننصحك باستخدام خدمة اختبار عند اختبار تطبيقك، مثل خدمة الملء التلقائي في نموذج إطار عمل الملء التلقائي في Android. عند استخدام محاكي، عليك ضبط خدمة ملء تلقائي بشكل صريح، لأنّ المحاكي قد لا يتضمّن خدمة تلقائية.

بعد تثبيت خدمة الملء التلقائي التجريبية من نموذج التطبيق، يمكنك تفعيل خدمة الملء التلقائي من خلال الانتقال إلى الإعدادات > النظام > اللغات والإدخال > الإعدادات المتقدّمة > المساعدة في الإدخال > خدمة الملء التلقائي.

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

استخدام سياق النشاط في طرق العرض

تتطلّب خدمة الملء التلقائي سياق النشاط لتعمل بشكل صحيح. عند إنشاء مثيل لطريقة عرض، استخدِم Activity كسياق لملئها تلقائيًا بشكل صحيح.

تقديم تلميحات للملء التلقائي

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

يمكنك ضبط تلميحات الملء التلقائي باستخدام السمة android:autofillHints. يضبط المثال التالي تلميح "password" على EditText:

<EditText
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:autofillHints="password" />

يمكنك أيضًا ضبط التلميحات آليًا باستخدام الإجراء setAutofillHints() ، كما هو موضّح في المثال التالي:

val password = findViewById<EditText>(R.id.password)
password.setAutofillHints(View.AUTOFILL_HINT_PASSWORD)

EditText password = findViewById(R.id.password);
password.setAutofillHints(View.AUTOFILL_HINT_PASSWORD);

تضمين ثوابت التلميحات المحدّدة مسبقًا

لا يتحقّق إطار عمل الملء التلقائي من صحة التلميحات، بل يتم تمريرها بدون تغيير أو تحقّق إلى خدمة الملء التلقائي. على الرغم من إمكانية استخدام أي قيمة، تحتوي فئتا View وHintConstants في AndroidX على قوائم بثوابت التلميحات المتوافقة رسميًا.

باستخدام مجموعة من هذه الثوابت، يمكنك إنشاء تنسيقات لسيناريوهات الملء التلقائي الشائعة:

بيانات اعتماد الحساب

في نموذج تسجيل الدخول، يمكنك تضمين تلميحات لبيانات اعتماد الحساب، مثل AUTOFILL_HINT_USERNAME و AUTOFILL_HINT_PASSWORD.

لإنشاء حساب جديد أو عندما يغيّر المستخدمون اسم المستخدم وكلمة المرور، يمكنك استخدام AUTOFILL_HINT_NEW_USERNAME وAUTOFILL_HINT_NEW_PASSWORD.

إنشاء معلومات بطاقة الائتمان

عند طلب معلومات بطاقة الائتمان، يمكنك استخدام تلميحات مثل AUTOFILL_HINT_CREDIT_CARD_NUMBER و AUTOFILL_HINT_CREDIT_CARD_SECURITY_CODE.

بالنسبة إلى تواريخ انتهاء صلاحية بطاقات الائتمان، نفِّذ أحد الإجراءات التالية:

• إذا كنت تستخدم طريقة عرض واحدة لتاريخ انتهاء الصلاحية، استخدِم AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DATE.
• إذا كنت تستخدم طريقة عرض مختلفة لكل جزء من تاريخ انتهاء الصلاحية، يمكنك استخدام AUTOFILL_HINT_CREDIT_CARD_EXPIRATION_DAY وAUTOFILL_HINT_CREDIT_CARD_EXPIRATION_MONTH وAUTOFILL_HINT_CREDIT_CARD_EXPIRATION_YEAR لكل طريقة عرض على حدة.

العنوان الجغرافي

بالنسبة إلى حقول نماذج العناوين الجغرافية، يمكنك استخدام تلميحات مثل ما يلي:

• للحصول على عنوان في عرض واحد، استخدِم AUTOFILL_HINT_POSTAL_ADDRESS.
• عند استخدام طرق عرض منفصلة لأجزاء مختلفة من العنوان، يمكنك استخدام ما يلي:
  • AUTOFILL_HINT_POSTAL_ADDRESS_STREET_ADDRESS
  • AUTOFILL_HINT_POSTAL_ADDRESS_EXTENDED_ADDRESS
  • AUTOFILL_HINT_POSTAL_ADDRESS_LOCALITY
  • AUTOFILL_HINT_POSTAL_ADDRESS_REGION
  • AUTOFILL_HINT_POSTAL_ADDRESS_COUNTRY
  • AUTOFILL_HINT_POSTAL_CODE
  • AUTOFILL_HINT_POSTAL_ADDRESS_EXTENDED_POSTAL_CODE

أسماء الأشخاص

عند طلب أسماء الأشخاص، يمكنك استخدام تلميحات مثل ما يلي:

• لملء الاسم الكامل لشخص تلقائيًا في طريقة عرض واحدة، استخدِم AUTOFILL_HINT_PERSON_NAME.
• إذا كنت تستخدم طرق عرض منفصلة لأجزاء مختلفة من الاسم، يمكنك استخدام أي مما يلي:
  • AUTOFILL_HINT_PERSON_NAME_PREFIX
  • AUTOFILL_HINT_PERSON_NAME_GIVEN
  • AUTOFILL_HINT_PERSON_NAME_MIDDLE
  • AUTOFILL_HINT_PERSON_NAME_MIDDLE_INITIAL
  • AUTOFILL_HINT_PERSON_NAME_FAMILY
  • AUTOFILL_HINT_PERSON_NAME_SUFFIX

أرقام الهواتف

بالنسبة إلى أرقام الهواتف، يمكنك استخدام ما يلي:

• عند طلب رقم هاتف كامل في طريقة عرض واحدة، استخدِم AUTOFILL_HINT_PHONE_NUMBER.
• إذا كنت تستخدم طرق عرض منفصلة لأجزاء مختلفة من رقم الهاتف، يمكنك استخدام أي مما يلي:
  • AUTOFILL_HINT_PHONE_COUNTRY_CODE
  • AUTOFILL_HINT_PHONE_NATIONAL
  • AUTOFILL_HINT_PHONE_NUMBER_DEVICE

كلمة المرور الصالحة لمرة واحدة (OTP)

للحصول على كلمة مرور صالحة لمرة واحدة في طريقة عرض واحدة، يمكنك استخدام AUTOFILL_HINT_SMS_OTP.

بالنسبة إلى طرق العرض المتعدّدة التي يتم فيها ربط كل طريقة عرض برقم واحد من كلمة المرور الصالحة لمرة واحدة، يمكنك استخدام طريقة generateSmsOtpHintForCharacterPosition() لإنشاء تلميحات لكل حرف.

ربط بيانات الموقع الإلكتروني وبيانات التطبيق المتوافق مع الأجهزة الجوّالة

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

لربط تطبيق Android بموقعك الإلكتروني، يمكنك استضافة رابط ينقل إلى مواد عرض رقمية باستخدام علاقة delegate_permission/common.get_login_creds في موقعك الإلكتروني. بعد ذلك، يجب الإعلان عن الربط في ملف AndroidManifest.xml الخاص بتطبيقك. للحصول على تعليمات مفصّلة حول كيفية ربط موقعك الإلكتروني بتطبيق Android، يُرجى الاطّلاع على تفعيل ميزة "تسجيل الدخول تلقائيًا" في التطبيقات والمواقع الإلكترونية.

إكمال سير عمل الملء التلقائي

يوضّح هذا القسم سيناريوهات محدّدة يمكنك فيها اتّخاذ خطوات لتحسين وظيفة الملء التلقائي لمستخدمي تطبيقك.

تحديد ما إذا كانت ميزة "الملء التلقائي" مفعَّلة

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

على سبيل المثال، يعرض TextView إدخال ملء تلقائي في قائمة الكاملة إذا كان الملء التلقائي مفعَّلاً للمستخدم. للتحقّق مما إذا كانت ميزة الملء التلقائي مفعَّلة للمستخدم، يمكنك استدعاء طريقة isEnabled() لكائن AutofillManager.

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

فرض طلب ملء تلقائي

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

fun eventHandler(view: View) {
    val afm = requireContext().getSystemService(AutofillManager::class.java)
    afm?.requestAutofill(view)
}

public void eventHandler(View view) {
    AutofillManager afm = context.getSystemService(AutofillManager.class);
    if (afm != null) {
        afm.requestAutofill(view);
    }
}

يمكنك أيضًا استخدام طريقة cancel() لإلغاء سياق الملء التلقائي الحالي. يمكن أن يكون هذا مفيدًا إذا كان لديك زر يمسح الحقول في صفحة تسجيل الدخول.

استخدام نوع الملء التلقائي الصحيح للبيانات في عناصر التحكّم في أداة الاختيار

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

يتوقّع عنصر EditText بشكلٍ أصلي بيانات الملء التلقائي من النوع AUTOFILL_TYPE_TEXT. إذا كنت تستخدم نوعًا مختلفًا من البيانات، أنشئ طريقة عرض مخصّصة تكتسب من EditText وتنفّذ الطرق المطلوبة للتعامل مع نوع البيانات المقابل. على سبيل المثال، إذا كان لديك حقل تاريخ، يمكنك تنفيذ الطرق باستخدام منطق يعالج قيم النوع AUTOFILL_TYPE_DATE بشكل صحيح.

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

إكمال سياق الملء التلقائي

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

إتاحة طرق العرض المخصّصة

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

إذا كان تطبيقك يستخدم طرق عرض مخصّصة، يُرجى مراعاة السيناريوهات التالية:

• توفّر طريقة العرض المخصّصة بنية عرض عادية أو بنية عرض تلقائية.
• يحتوي العرض المخصّص على بنية افتراضية أو بنية عرض غير متاحة لإطار عمل الملء التلقائي.

طرق العرض المخصّصة مع بنية طريقة العرض العادية

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

• تعامَل مع قيمة الملء التلقائي التي يرسلها إطار العمل إلى تطبيقك.
• قدِّم نوع الملء التلقائي وقيمته إلى إطار العمل.

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

يجب أن يحدّد العرض نوع الملء التلقائي وقيمته من خلال إلغاء الطريقتَين getAutofillType() و getAutofillValue() على التوالي.

أخيرًا، يجب ألا تملأ ميزة "الملء التلقائي" العرض إذا لم يتمكّن المستخدم من تقديم قيمة للعرض في حالته الحالية، على سبيل المثال، إذا كان العرض غير مفعَّل. في هذه الحالات، يجب أن يعرض getAutofillType() AUTOFILL_TYPE_NONE، ويجب أن يعرض getAutofillValue() null، ويجب ألا ينفّذ autofill() أي إجراء.

تتطلّب الحالات التالية خطوات إضافية لتعمل بشكل صحيح ضمن إطار العمل:

• يمكن تعديل طريقة العرض المخصّصة.
• يحتوي العرض المخصّص على بيانات حسّاسة.

طريقة العرض المخصّصة قابلة للتعديل

إذا كان العرض قابلاً للتعديل، يمكنك إرسال إشعار إلى إطار عمل الملء التلقائي بشأن التغييرات من خلال استدعاء notifyValueChanged() في العنصر AutofillManager.

يحتوي العرض المخصّص على بيانات حسّاسة

إذا كان العرض يحتوي على معلومات تكشف الهوية الشخصية (PII)، مثل عناوين البريد الإلكتروني وأرقام بطاقات الائتمان وكلمات المرور، يجب وضع علامة "حسّاسة" عليه.

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

يفترض إطار عمل الملء التلقائي أنّ جميع البيانات حسّاسة تلقائيًا. يمكنك وضع علامة على البيانات غير الحسّاسة.

لتحديد ما إذا كان العرض يحتوي على بيانات حسّاسة، نفِّذ onProvideAutofillStructure() واستخدِم setDataIsSensitive() في العنصر ViewStructure.

يوضّح مثال الرمز التالي كيفية وضع علامة على البيانات في بنية العرض على أنّها غير حساسة:

override fun onProvideAutofillStructure(structure: ViewStructure, flags: Int) {
    super.onProvideAutofillStructure(structure, flags)

    structure.setDataIsSensitive(false)
}

@Override
public void onProvideAutofillStructure(ViewStructure structure, int flags) {
    super.onProvideAutofillStructure(structure, flags);

    structure.setDataIsSensitive(false);
}

إذا كان العرض يقبل القيم المحدّدة مسبقًا فقط، يمكنك استخدام طريقة setAutofillOptions() لضبط الخيارات التي يمكن استخدامها لملء العرض تلقائيًا. على وجه الخصوص، يجب أن تستخدم طرق العرض التي يكون نوع الملء التلقائي لها AUTOFILL_TYPE_LIST هذه الطريقة، لأنّ خدمة الملء التلقائي يمكنها القيام بعمل أفضل إذا كانت تعرف الخيارات المتاحة لملء العرض.

وينطبق ذلك أيضًا على طرق العرض التي تستخدم محوّلاً، مثل Spinner. على سبيل المثال، يمكن لمؤشر التحميل الذي يوفّر سنوات تم إنشاؤها ديناميكيًا، استنادًا إلى السنة الحالية، لاستخدامها في حقول انتهاء صلاحية بطاقة الائتمان، تنفيذ طريقة getAutofillOptions() لواجهة Adapter لتوفير قائمة بالسنوات.

يمكن أيضًا أن توفّر طرق العرض التي تستخدم ArrayAdapter قوائم بالقيم. يضبط ArrayAdapter خيارات الملء التلقائي للموارد الثابتة تلقائيًا. إذا كنت تقدّم القيم بشكل ديناميكي، يمكنك تجاهل getAutofillOptions().

طرق عرض مخصّصة مع بنية افتراضية

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

• يستخدم التطبيق محرّك عرض منخفض المستوى، مثل OpenGL، لعرض واجهة المستخدم.
• يستخدم التطبيق مثيلاً من Canvas لرسم واجهة المستخدم.

في هذه الحالات، يمكنك تحديد بنية عرض من خلال تنفيذ onProvideAutofillVirtualStructure() واتّباع الخطوات التالية:

1. يمكنك زيادة عدد العناصر الفرعية لبنية العرض من خلال استدعاء addChildCount().
2. يمكنك إضافة طفل من خلال الاتصال بالرقم newChild().
3. اضبط رقم تعريف الملء التلقائي للعنصر الفرعي من خلال استدعاء setAutofillId().
4. اضبط السمات ذات الصلة، مثل قيمة الملء التلقائي ونوعه.
5. إذا كانت البيانات في العنصر الفرعي الافتراضي حساسة، مرِّر true إلى setDataIsSensitive()، وإلا مرِّر false.

يوضّح مقتطف الرمز التالي كيفية إنشاء عنصر فرعي جديد في البنية الافتراضية:

override fun onProvideAutofillVirtualStructure(structure: ViewStructure, flags: Int) {

    super.onProvideAutofillVirtualStructure(structure, flags)

    // Create a new child in the virtual structure.
    structure.addChildCount(1)
    val child = structure.newChild(childIndex)

    // Set the autofill ID for the child.
    child.setAutofillId(structure.autofillId!!, childVirtualId)

    // Populate the child by providing properties such as value and type.
    child.setAutofillValue(childAutofillValue)
    child.setAutofillType(childAutofillType)

    // Some children can provide a list of values, such as when the child is
    // a spinner.
    val childAutofillOptions = arrayOf<CharSequence>("option1", "option2")
    child.setAutofillOptions(childAutofillOptions)

    // Just like other types of views, mark the data as sensitive when
    // appropriate.
    val sensitive = !contentIsSetFromResources()
    child.setDataIsSensitive(sensitive)
}

@Override
public void onProvideAutofillVirtualStructure(ViewStructure structure, int flags) {

    super.onProvideAutofillVirtualStructure(structure, flags);

    // Create a new child in the virtual structure.
    structure.addChildCount(1);
    ViewStructure child =
            structure.newChild(childIndex);

    // Set the autofill ID for the child.
    child.setAutofillId(structure.getAutofillId(), childVirtualId);

    // Populate the child by providing properties such as value and type.
    child.setAutofillValue(childAutofillValue);
    child.setAutofillType(childAutofillType);

    // Some children can provide a list of values, such as when the child is
    // a spinner.
    CharSequence childAutofillOptions[] = { "option1", "option2" };
    child.setAutofillOptions(childAutofillOptions);

    // Just like other types of views, mark the data as sensitive when
    // appropriate.
    boolean sensitive = !contentIsSetFromResources();
    child.setDataIsSensitive(sensitive);
}

عندما تتغيّر العناصر في بنية افتراضية، يجب إعلام إطار العمل من خلال تنفيذ المهام التالية:

• إذا تغيّر التركيز داخل العناصر الفرعية، يمكنك استدعاء notifyViewEntered() و notifyViewExited() على الكائن AutofillManager.
• إذا تغيّرت قيمة عنصر فرعي، يمكنك استدعاء notifyValueChanged() في العنصر AutofillManager.
• إذا لم تعُد هيكلية طرق العرض متاحة لأنّ المستخدم أكمل خطوة في سير العمل، مثل تسجيل الدخول باستخدام نموذج تسجيل الدخول، يمكنك استدعاء commit() في الكائن AutofillManager.
• إذا كانت هيكلية طرق العرض غير صالحة بسبب إلغاء المستخدم خطوة في سير العمل، مثلاً عندما ينقر المستخدم على زر يمحو نموذج تسجيل الدخول، يمكنك استدعاء cancel() في الكائن AutofillManager.

استخدام عمليات الاستدعاء في أحداث الملء التلقائي

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

توفّر هذه الفئة الطريقة onAutofillEvent(View, int) التي يستدعيها التطبيق بعد تغيير حالة الملء التلقائي المرتبطة بطريقة عرض. هناك أيضًا إصدار زائد من هذه الطريقة يتضمّن مَعلمة childId يمكن لتطبيقك استخدامها مع طرق العرض الافتراضية. يتم تحديد الحالات المتاحة على أنّها ثوابت في دالة الاستدعاء.

يمكنك تسجيل معاودة الاتصال باستخدام طريقة registerCallback() من فئة AutofillManager. يوضّح مثال الرمز البرمجي التالي كيفية الإعلان عن دالة استدعاء لأحداث الملء التلقائي:

val afm = context.getSystemService(AutofillManager::class.java)

afm?.registerCallback(object : AutofillManager.AutofillCallback() {
    // For virtual structures, override
    // onAutofillEvent(View view, int childId, int event) instead.
    override fun onAutofillEvent(view: View, event: Int) {
        super.onAutofillEvent(view, event)
        when (event) {
            EVENT_INPUT_HIDDEN -> {
                // The autofill affordance associated with the view was hidden.
            }
            EVENT_INPUT_SHOWN -> {
                // The autofill affordance associated with the view was shown.
            }
            EVENT_INPUT_UNAVAILABLE -> {
                // Autofill isn't available.
            }
        }

    }
})

AutofillManager afm = getContext().getSystemService(AutofillManager.class);

afm.registerCallback(new AutofillManager.AutofillCallback() {
    // For virtual structures, override
    // onAutofillEvent(View view, int childId, int event) instead.
    @Override
    public void onAutofillEvent(@NonNull View view, int event) {
        super.onAutofillEvent(view, event);
        switch (event) {
            case EVENT_INPUT_HIDDEN:
                // The autofill affordance associated with the view was hidden.
                break;
            case EVENT_INPUT_SHOWN:
                // The autofill affordance associated with the view was shown.
                break;
            case EVENT_INPUT_UNAVAILABLE:
                // Autofill isn't available.
                break;
        }
    }
});

عندما يحين وقت إزالة دالة الاستدعاء، استخدِم الطريقة unregisterCallback().

تخصيص العنصر القابل للرسم المميّز في الملء التلقائي

عندما يتم ملء طريقة عرض تلقائيًا، تعرض المنصة Drawable فوق طريقة العرض للإشارة إلى أنّه تم ملء محتوى طريقة العرض تلقائيًا. يكون هذا العنصر القابل للرسم تلقائيًا مستطيلاً بلون واحد شفاف وأغمق قليلاً من لون المظهر المستخدَم لرسم الخلفيات. لا يلزم تغيير العنصر القابل للرسم، ولكن يمكن تخصيصه من خلال إلغاء العنصر android:autofilledHighlight للمظهر الذي يستخدمه التطبيق أو النشاط، كما هو موضّح في هذا المثال:

res/values/styles.xml

<resources>
    <style name="MyAutofilledHighlight" parent="...">
        <item name="android:autofilledHighlight">@drawable/my_drawable</item>
    </style>
</resources>

res/drawable/my_drawable.xml

<shape xmlns:android="http://schemas.android.com/apk/res/android">
    <solid android:color="#4DFF0000" />
</shape>

AndroidManifest.xml

<application ...
    android:theme="@style/MyAutofilledHighlight">
<!-- or -->
<activity ...
    android:theme="@style/MyAutofilledHighlight">

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

يمكن أن تطلب خدمة الملء التلقائي من المستخدم المصادقة قبل أن تتمكّن الخدمة من إكمال الحقول في تطبيقك، وفي هذه الحالة يشغّل نظام Android نشاط مصادقة الخدمة كجزء من حزمة نشاطك.

ليس عليك تحديث تطبيقك لإتاحة المصادقة، لأنّ المصادقة تتم داخل الخدمة. ومع ذلك، يجب التأكّد من الحفاظ على بنية العرض للنشاط عند إعادة تشغيله، مثلاً من خلال إنشاء بنية العرض في onCreate()، وليس في onStart() أو onResume().

يمكنك التحقّق من سلوك تطبيقك عندما تتطلّب خدمة الملء التلقائي المصادقة باستخدام HeuristicsService من نموذج AutofillFramework وضبطه لطلب مصادقة استجابة الملء. يمكنك أيضًا استخدام نموذج BadViewStructureCreationSignInActivity لمحاكاة هذه المشكلة.

تخصيص أرقام تعريف الملء التلقائي لطرق العرض المُعاد تدويرها

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

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

لحلّ هذه المشكلة على الأجهزة التي تعمل بالإصدار 9 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 28) والإصدارات الأحدث، يمكنك إدارة معرّف الملء التلقائي لطرق العرض التي يستخدمها RecyclerView بشكل صريح من خلال الطرق التالية:

• تحصل الطريقة getNextAutofillId() على معرّف ملء تلقائي جديد فريد للنشاط.
• تضبط طريقة setAutofillId() معرّف الملء التلقائي المنطقي والفريد لطريقة العرض هذه في النشاط.

معالجة المشاكل المعروفة

يعرض هذا القسم حلولاً بديلة للمشاكل المعروفة في إطار عمل الملء التلقائي.

تؤدي ميزة "الملء التلقائي" إلى تعطُّل التطبيقات على الإصدارَين 8.0 و8.1 من نظام التشغيل Android

في الإصدارَين 8.0 (المستوى 26 من واجهة برمجة التطبيقات) و8.1 (المستوى 27 من واجهة برمجة التطبيقات) من نظام التشغيل Android، قد يؤدي الملء التلقائي إلى تعطُّل تطبيقك في سيناريوهات معيّنة. لتجنُّب المشاكل المحتملة، ضَع علامة importantForAutofill=no على أي طرق عرض لا يتم ملؤها تلقائيًا. يمكنك أيضًا وضع علامة على النشاط بأكمله باستخدام importantForAutofill=noExcludeDescendants.

لا يتم استخدام مربّعات الحوار التي تم تغيير حجمها في ميزة "الملء التلقائي"

في الإصدار Android 8.1 (المستوى 27 لواجهة برمجة التطبيقات) والإصدارات الأقدم، إذا تم تغيير حجم طريقة عرض في مربّع حوار بعد عرضه، لن يتم أخذ طريقة العرض في الاعتبار عند الملء التلقائي. لا يتم تضمين طرق العرض هذه في عنصر AssistStructure الذي يرسله نظام Android إلى خدمة الملء التلقائي. نتيجةً لذلك، لا يمكن للخدمة ملء طرق العرض.

لتفادي هذه المشكلة، استبدِل السمة token لمَعلمات نافذة مربّع الحوار بالسمة token للنشاط الذي ينشئ مربّع الحوار. بعد التأكّد من تفعيل ميزة "الملء التلقائي"، احفظ مَعلمات النافذة في طريقة onWindowAttributesChanged() للفئة التي تكتسب من Dialog. بعد ذلك، استبدِل السمة token للمَعلمات المحفوظة بالسمة token للنشاط الرئيسي في الطريقة onAttachedToWindow().

يعرض مقتطف الرمز التالي فئة تنفّذ هذا الحلّ البديل:

class MyDialog(context: Context) : Dialog(context) {

    // Used to store the dialog window parameters.
    private var token: IBinder? = null

    private val isDialogResizedWorkaroundRequired: Boolean
        get() {
            if (Build.VERSION.SDK_INT != Build.VERSION_CODES.O || Build.VERSION.SDK_INT != Build.VERSION_CODES.O_MR1) {
                return false
            }
            val autofillManager = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
                context.getSystemService(AutofillManager::class.java)
            } else {
                null
            }
            return autofillManager?.isEnabled ?: false
        }

    override fun onWindowAttributesChanged(params: WindowManager.LayoutParams) {
        if (params.token == null && token != null) {
            params.token = token
        }

        super.onWindowAttributesChanged(params)
    }

    override fun onAttachedToWindow() {
        if (isDialogResizedWorkaroundRequired) {
            token = ownerActivity!!.window.attributes.token
        }

        super.onAttachedToWindow()
    }

}

public class MyDialog extends Dialog {

    public MyDialog(Context context) {
        super(context);
    }

    // Used to store the dialog window parameters.
    private IBinder token;

    @Override
    public void onWindowAttributesChanged(WindowManager.LayoutParams params) {
        if (params.token == null && token != null) {
            params.token = token;
        }

        super.onWindowAttributesChanged(params);
    }

    @Override
    public void onAttachedToWindow() {
        if (isDialogResizedWorkaroundRequired()) {
            token = getOwnerActivity().getWindow().getAttributes().token;
        }

        super.onAttachedToWindow();
    }

    private boolean isDialogResizedWorkaroundRequired() {
        if (Build.VERSION.SDK_INT != Build.VERSION_CODES.O
                || Build.VERSION.SDK_INT != Build.VERSION_CODES.O_MR1) {
            return false;
        }
        AutofillManager autofillManager =
                null;
        if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.M) {
            autofillManager = getContext().getSystemService(AutofillManager.class);
        }
        return autofillManager != null && autofillManager.isEnabled();
    }

}

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

// AutofillExtensions.kt

fun Context.isDialogResizedWorkaroundRequired(): Boolean {
    // After the issue is resolved on Android, check whether the
    // workaround is still required for the current device.
    return isAutofillAvailable()
}

fun Context.isAutofillAvailable(): Boolean {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
        // The autofill framework is available on Android 8.0
        // or higher.
        return false
    }

    val afm = getSystemService(AutofillManager::class.java)
    // Return true if autofill is supported by the device and enabled
    // for the current user.
    return afm != null && afm.isEnabled
}

public class AutofillHelper {

    public static boolean isDialogResizedWorkaroundRequired(Context context) {
        // After the issue is resolved on Android, check whether the
        // workaround is still required for the current device.
        return isAutofillAvailable(context);
    }

    public static boolean isAutofillAvailable(Context context) {
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
            // The autofill framework is available on Android 8.0
            // or higher.
            return false;
        }

        AutofillManager afm = context.getSystemService(AutofillManager.class);
        // Return true if autofill is supported by the device and enabled
        // for the current user.
        return afm != null && afm.isEnabled();
    }
}

اختبار تطبيقك باستخدام ميزة "الملء التلقائي"

بعد تحسين تطبيقك ليعمل مع خدمات الملء التلقائي، اختبِر ما إذا كان يعمل على النحو المنشود مع خدمات الملء التلقائي.

استخدِم محاكيًا أو جهازًا فعليًا يعمل بنظام التشغيل Android 8.0 (مستوى واجهة برمجة التطبيقات 26) أو إصدار أحدث لاختبار تطبيقك. لمزيد من المعلومات حول كيفية إنشاء محاكي، يُرجى الاطّلاع على مقالة إنشاء الأجهزة الافتراضية وإدارتها.

تثبيت خدمة ملء تلقائي

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

يمكنك استخدام نموذج إطار عمل الملء التلقائي في Android بلغة Java لاختبار تطبيقك باستخدام خدمات الملء التلقائي. يوفّر نموذج التطبيق خدمة ملء تلقائي وفئات عملاء Activity يمكنك استخدامها لاختبار سير العمل قبل استخدامه مع تطبيقك. تشير هذه الصفحة إلى نموذج تطبيق android-AutofillFramework.

بعد تثبيت التطبيق، فعِّل خدمة الملء التلقائي في إعدادات نظام المحاكي من خلال الانتقال إلى الإعدادات > النظام > اللغات والإدخال > الإعدادات المتقدّمة > المساعدة في الإدخال > خدمة الملء التلقائي.

تحليل متطلبات البيانات

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

أخبِر الخدمة بنوع البيانات المتوقّع في طرق العرض من خلال ضبط السمة android:autofillHints. تستخدم بعض الخدمات أساليب إرشادية متطوّرة لتحديد نوع البيانات، بينما يعتمد البعض الآخر، مثل نموذج التطبيق، على المطوّر لتقديم هذه المعلومات. يعمل تطبيقك بشكل أفضل مع خدمات الملء التلقائي إذا ضبطت السمة android:autofillHints في طرق العرض ذات الصلة بالملء التلقائي.

إجراء الاختبار

بعد تحليل متطلبات البيانات، يمكنك إجراء الاختبار الذي يتضمّن حفظ بيانات الاختبار في خدمة الملء التلقائي وتفعيل الملء التلقائي في تطبيقك.

حفظ البيانات في الخدمة

لحفظ البيانات في خدمة الملء التلقائي النشطة حاليًا، اتّبِع الخطوات التالية:

1. افتح تطبيقًا يحتوي على طريقة عرض تتوقع نوع البيانات التي تريد استخدامها أثناء الاختبار. يوفّر نموذج تطبيق android-AutofillFramework واجهة المستخدم مع طرق عرض تتوقّع عدة أنواع من البيانات، مثل أرقام بطاقات الائتمان وأسماء المستخدمين.
2. انقر على طريقة العرض التي تتضمّن نوع البيانات الذي تريده.
3. أدخِل قيمة في العرض.
4. انقر على زر التأكيد، مثل تسجيل الدخول أو إرسال. وعادةً ما يتعيّن عليك إرسال النموذج قبل أن تحفظ الخدمة البيانات.
5. تحقَّق من طلب الحصول على الإذن من مربّع حوار النظام. يعرض مربّع حوار النظام اسم الخدمة النشطة حاليًا ويسألك عمّا إذا كانت هذه هي الخدمة التي تريد استخدامها في الاختبار. إذا أردت استخدام الخدمة، انقر على حفظ.

إذا لم يعرض Android مربّع حوار الإذن، أو إذا لم تكن الخدمة هي التي تريد استخدامها في الاختبار، فتأكَّد من أنّ الخدمة نشطة حاليًا في إعدادات النظام.

تفعيل ميزة "الملء التلقائي" في تطبيقك

لتفعيل ميزة "الملء التلقائي" في تطبيقك، اتّبِع الخطوات التالية:

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

إذا لم يعرض Android واجهة مستخدم الملء التلقائي، يمكنك تجربة خيارات تحديد المشاكل وحلّها التالية:

• يُرجى التأكّد من أنّ طرق العرض في تطبيقك تستخدم القيمة الصحيحة في السمة android:autofillHints. للحصول على قائمة بالقيم المحتملة للسمة، اطّلِع على الثوابت التي تبدأ بـ AUTOFILL_HINT في الفئة View.
• يُرجى التأكّد من ضبط السمة android:importantForAutofill على قيمة غير no في طريقة العرض التي يجب ملؤها، أو ضبطها على قيمة غير noExcludeDescendants في طريقة العرض أو في أحد العناصر الرئيسية.