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

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

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

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

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

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

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

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

تقديم نصائح حول الملء التلقائي

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

يمكنك ضبط نصائح الملء التلقائي باستخدام سمة 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 وAndroidX HintConstants على قوائم بثوابت التلميح المتوافقة رسميًا.

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

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

في نموذج تسجيل الدخول، يمكنك تضمين تلميحات حول بيانات اعتماد الحساب، مثل 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() لإنشاء تلميحات لكل حرف.

وضع علامة على الحقول كحقول مهمة لملء البيانات تلقائيًا

يمكنك تضمين الحقول الفردية في تطبيقك في هيكل عرض لأغراض الملء التلقائي. تستخدم طرق العرض تلقائيًا وضع IMPORTANT_FOR_AUTOFILL_AUTO الذي يتيح لنظام التشغيل Android استخدام الأساليب الاستقرائية لتحديد ما إذا كانت طريقة العرض مهمة لميزة preenchimento automático (الملء التلقائي).

ومع ذلك، هناك حالات تكون فيها طريقة العرض أو بنية العرض أو النشاط بأكمله غير مهمة للملء التلقائي:

• حقل CAPTCHA في نشاط تسجيل دخول
• طريقة عرض ينشئ فيها المستخدم المحتوى، مثل أداة تعديل النصوص أو جداول البيانات
• المشاهدات في بعض الأنشطة داخل الألعاب، مثل تلك التي تعرض أسلوب اللعب

يمكنك ضبط أهمية عرض للملء التلقائي باستخدام السمة android:importantForAutofill:

<TextView
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:importantForAutofill="no" />

يمكن أن تكون قيمة importantForAutofill أيًّا ممّا يلي:

auto

يمكنك السماح لنظام Android باستخدام استدلالاته لتحديد ما إذا كانت طريقة العرض مهمة للملء التلقائي.

no

هذه الطريقة غير مهمة لميزة الملء التلقائي.

noExcludeDescendants

هذه طريقة العرض وعناصرها الثانوية ليست مهمة لملء البيانات تلقائيًا.

yes

هذه الطريقة مهمة لملء البيانات تلقائيًا.

yesExcludeDescendants

هذه طريقة العرض مهمة لملء البيانات تلقائيًا، ولكن عناصرها الفرعية ليست مهمة لملء البيانات تلقائيًا.

يمكنك أيضًا استخدام الرمز التالي: setImportantForAutofill() :

val captcha = findViewById<TextView>(R.id.captcha)
captcha.setImportantForAutofill(View.IMPORTANT_FOR_AUTOFILL_NO)

TextView captcha = findViewById(R.id.captcha);
captcha.setImportantForAutofill(View.IMPORTANT_FOR_AUTOFILL_NO);

يمكنك تحديد أنّ أمثلة حالات الاستخدام السابقة غير مهمة لملء البيانات تلقائيًا على النحو التالي:

• حقل CAPTCHA في نشاط تسجيل الدخول: استخدِم android:importantForAutofill="no" أو IMPORTANT_FOR_AUTOFILL_NO لوضع علامة "غير مهم" على هذا العرض.
• عرض ينشئ فيه المستخدم المحتوى: استخدِم رمز android:importantForAutofill="noExcludeDescendants" أو IMPORTANT_FOR_AUTOFILL_NO_EXCLUDE_DESCENDANTS لوضع علامة "غير مهم" على بنية العرض بأكملها.
• المشاهدات في بعض الأنشطة ضمن الألعاب: استخدِم android:importantForAutofill="noExcludeDescendants" أو IMPORTANT_FOR_AUTOFILL_NO_EXCLUDE_DESCENDANTS لوضع علامة "غير مهم" على بنية العرض بالكامل.

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

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

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

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

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

تحديد ما إذا كان الملء التلقائي مفعّلاً

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

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

للتأكّد من تحسين تجربة الاشتراك وتسجيل الدخول للمستخدمين الذين لا يستخدمون ميزة preenchimento automático (الملء التلقائي)، يمكنك استخدام ميزة تسجيل الدخول بنقرة واحدة.

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

تحتاج أحيانًا إلى فرض حدوث طلب الملء التلقائي استجابةً لإجراء المستخدم. على سبيل المثال، يوفّر 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)، مثل عناوين البريد الإلكتروني وأرقام بطاقات الائتمان وكلمات المرور، يجب وضع علامة عليه بأنّه حسّاس.

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

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

لتحديد ما إذا كان العرض يحتوي على بيانات حسّاسة، نفِّذ 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() لضبط معرّف الملء التلقائي المنطقي والفريد لهذا العرض في النشاط.

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

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

تتسبب ميزة الملء التلقائي في تعطُّل التطبيقات على Android 8.0، 8.1

في نظام التشغيل Android 8.0 (المستوى 26 من واجهة برمجة التطبيقات) وAndroid 8.1 (المستوى 27 من واجهة برمجة التطبيقات)، يمكن أن يؤدي الملء التلقائي إلى تعطُّل تطبيقك في سيناريوهات معيّنة. لحلّ المشاكل المحتمَلة، يمكنك الإشارة إلى أي مشاهدات لم يتم ملؤها تلقائيًا باستخدام 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 في طريقة العرض أو أحد عناصرها الرئيسية.