إضافة خطوة إرشادية

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

توفّر مكتبة androidx Leanback صفوفًا لتنفيذ مهام المستخدمين متعددة الخطوات. توضّح هذه الصفحة طريقة استخدام الفئة GuidedStepSupportFragment لإرشاد المستخدم من خلال سلسلة من القرارات المتعلقة بتنفيذ مهمة. GuidedStepSupportFragment يستخدم أفضل ممارسات واجهة مستخدم التلفزيون لتسهيل فهم المهام المتعدّدة الخطوات والتنقّل بينها على أجهزة التلفزيون.

تقديم تفاصيل للخطوة

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

الشكل 1. مثال على خطوة إرشادية.

بالنسبة إلى كل خطوة في المهمة المتعددة الخطوات، عليك تمديد GuidedStepSupportFragment وتقديم معلومات سياقية حول الخطوة والإجراءات التي يمكن للمستخدم اتخاذها. تجاهُل onCreateGuidance() وعرض عنصر GuidanceStylist.Guidance جديد يحتوي على معلومات السياق، مثل عنوان الخطوة ووصفها ورمزها، كما هو موضَّح في المثال التالي:

Kotlin

override fun onCreateGuidance(savedInstanceState: Bundle?): GuidanceStylist.Guidance {
    return GuidanceStylist.Guidance(
            getString(R.string.guidedstep_first_title),
            getString(R.string.guidedstep_first_description),
            getString(R.string.guidedstep_first_breadcrumb),
            activity.getDrawable(R.drawable.guidedstep_main_icon_1)
    )
}

Java

@Override
public GuidanceStylist.Guidance onCreateGuidance(Bundle savedInstanceState) {
    String title = getString(R.string.guidedstep_first_title);
    String breadcrumb = getString(R.string.guidedstep_first_breadcrumb);
    String description = getString(R.string.guidedstep_first_description);
    Drawable icon = getActivity().getDrawable(R.drawable.guidedstep_main_icon_1);
    return new GuidanceStylist.Guidance(title, description, breadcrumb, icon);
}

أضف الفئة الفرعية GuidedStepSupportFragment إلى النشاط المطلوب عن طريق استدعاء GuidedStepSupportFragment.add() في طريقة onCreate() في نشاطك.

إذا كان نشاطك يحتوي على كائنات GuidedStepSupportFragment فقط، يمكنك استخدام GuidedStepSupportFragment.addAsRoot() بدلاً من add() لإضافة أول GuidedStepSupportFragment. يساعد استخدام addAsRoot() في ضمان أنّه إذا ضغط المستخدم على زر الرجوع على جهاز التحكّم عن بُعد في التلفزيون عند مشاهدة أول GuidedStepSupportFragment، سيتم إغلاق كل من GuidedStepSupportFragment والنشاط الرئيسي.

ملاحظة: يمكنك إضافة كائنات GuidedStepSupportFragment آليًا، وليس في ملفات XML ذات التنسيق.

إنشاء إجراءات المستخدم والتعامل معها

يمكنك إضافة إجراءات المستخدم عن طريق إلغاء onCreateActions(). في عملية الإلغاء، أضِف سمة GuidedAction جديدة لكل بند إجراء، وأدخِل سلسلة الإجراء ووصفها ورقم تعريفها. استخدِم GuidedAction.Builder لإضافة إجراءات جديدة.

Kotlin

override fun onCreateActions(actions: MutableList<GuidedAction>, savedInstanceState: Bundle?) {
    super.onCreateActions(actions, savedInstanceState)

    // Add "Continue" user action for this step
    actions.add(GuidedAction.Builder()
            .id(CONTINUE)
            .title(getString(R.string.guidedstep_continue))
            .description(getString(R.string.guidedstep_letsdoit))
            .hasNext(true)
            .build())
    ...

Java

@Override
public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {
    // Add "Continue" user action for this step
    actions.add(new GuidedAction.Builder()
           .id(CONTINUE)
           .title(getString(R.string.guidedstep_continue))
           .description(getString(R.string.guidedstep_letsdoit))
           .hasNext(true)
           .build());
...

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

• يمكنك إضافة إجراء تصنيف المعلومات لتوفير معلومات إضافية حول خيارات المستخدمين من خلال ضبط infoOnly(true). عندما تكون قيمة infoOnly صحيحة، لا يمكن للمستخدمين اختيار الإجراء.
• أضِف إجراءً نصيًا قابلاً للتعديل من خلال ضبط editable(true). في حال ضبط السياسة editable على "صحيح"، يمكن للمستخدم إدخال نص في إجراء محدّد باستخدام وحدة التحكّم عن بُعد أو لوحة المفاتيح المتصلة. إلغاء onGuidedActionEditedAndProceed() للحصول على النص المعدَّل الذي أدخله المستخدم يمكنك أيضًا إلغاء onGuidedActionEditCanceled() لمعرفة متى يلغي المستخدم الإدخال.
• أضِف مجموعة من الإجراءات التي تشبه أزرار الاختيار القابلة للتحديد باستخدام checkSetId() مع قيمة معرِّف شائعة لتجميع الإجراءات في مجموعة. تعتبر جميع الإجراءات في نفس القائمة ولها نفس معرف مجموعة التحقق مرتبطة. عندما يختار المستخدم أحد الإجراءات ضمن هذه المجموعة، يتم وضع علامة على هذا الإجراء وتصبح جميع الإجراءات الأخرى غير محددة.
• أضِف إجراء منتقي التاريخ باستخدام GuidedDatePickerAction.Builder بدلاً من GuidedAction.Builder في onCreateActions(). يمكنك إلغاء onGuidedActionEditedAndProceed() للحصول على قيمة التاريخ المعدَّلة التي أدخلها المستخدم.
• أضف إجراءً يستخدم الإجراءات الفرعية للسماح للمستخدم بالاختيار من قائمة خيارات ممتدة. يتم توضيح الإجراءات في قسم إضافة إجراءات فرعية.
• يمكنك إضافة إجراء زر يظهر على يسار قائمة الإجراءات ويمكن الوصول إليه بسهولة. يتم توضيح إجراءات الأزرار في قسم إضافة إجراءات الزر.

يمكنك أيضًا إضافة مؤشر مرئي يشير إلى أنّ اختيار إجراء يؤدي إلى خطوة جديدة من خلال ضبط hasNext(true).

وبالنسبة إلى جميع السمات المختلفة التي يمكنك ضبطها، يمكنك الاطّلاع على GuidedAction.

للرد على الإجراءات، يمكنك إلغاء onGuidedActionClicked() ومعالجة البيانات التي تم تمريرها GuidedAction. حدد الإجراء المحدد من خلال فحص GuidedAction.getId().

إضافة اشتراكات

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

الشكل 2. عمليات تنفيذ الخطوات الإرشادية

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

لإضافة عناصر فرعية، عليك أولاً إنشاء قائمة تضم كائنات GuidedAction وملؤها وتعمل كإجراءات فرعية، كما هو موضَّح في المثال التالي:

Kotlin

subActions.add(GuidedAction.Builder()
        .id(SUBACTION1)
        .title(getString(R.string.guidedstep_subaction1_title))
        .description(getString(R.string.guidedstep_subaction1_desc))
        .build())
...

Java

List<GuidedAction> subActions = new ArrayList<GuidedAction>();
subActions.add(new GuidedAction.Builder()
       .id(SUBACTION1)
       .title(getString(R.string.guidedstep_subaction1_title))
       .description(getString(R.string.guidedstep_subaction1_desc))
       .build());
...

في onCreateActions()، أنشئ عنصر GuidedAction عالي المستوى يعرض قائمة الإجراءات الفرعية عند اختيارها:

Kotlin

    ...
    actions.add(GuidedAction.Builder()
            .id(SUBACTIONS)
            .title(getString(R.string.guidedstep_subactions_title))
            .description(getString(R.string.guidedstep_subactions_desc))
            .subActions(subActions)
            .build())
    ...

Java

@Override
public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {
...
    actions.add(new GuidedAction.Builder()
           .id(SUBACTIONS)
           .title(getString(R.string.guidedstep_subactions_title))
           .description(getString(R.string.guidedstep_subactions_desc))
           .subActions(subActions)
           .build());
...
}

أخيرًا، يجب الردّ على اختيارات الاشتراكات من خلال تجاهل onSubGuidedActionClicked():

Kotlin

override fun onSubGuidedActionClicked(action: GuidedAction): Boolean {
    // Check for which action was clicked and handle as needed
    when(action.id) {
        SUBACTION1 -> {
            // Subaction 1 selected
        }
    }
    // Return true to collapse the subactions menu or
    // false to keep the menu expanded
    return true
}

Java

@Override
public boolean onSubGuidedActionClicked(GuidedAction action) {
   // Check for which action was clicked and handle as needed
   if (action.getId() == SUBACTION1) {
       // Subaction 1 selected
   }
   // Return true to collapse the subactions menu or
   // false to keep the menu expanded
   return true;
}

إجراءات إضافة الزر

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

الشكل 3. إجراءات زر الخطوات الإرشادية

يتم إنشاء إجراءات الأزرار ومعالجتها مثل الإجراءات العادية، ويمكنك إنشاء إجراءات للأزرار في onCreateButtonActions() بدلاً من onCreateActions(). يمكنك الردّ على إجراءات الزرّ في onGuidedActionClicked().

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

تجميع الخطوات الإرشادية في تسلسل موجّه

تمثّل السمة GuidedStepSupportFragment خطوة واحدة. لإنشاء تسلسل من الخطوات مرتّبة، يجب تجميع عناصر GuidedStepSupportFragment متعددة باستخدام GuidedStepSupportFragment.add() لإضافة الخطوة التالية في التسلسل إلى حزمة الأجزاء.

Kotlin

override fun onGuidedActionClicked(action: GuidedAction) {
    val fm = fragmentManager
    when(action.id) {
        CONTINUE -> GuidedStepSupportFragment.add(fm, SecondStepFragment())
    }
}

Java

@Override
public void onGuidedActionClicked(GuidedAction action) {
    FragmentManager fm = getFragmentManager();
    if (action.getId() == CONTINUE) {
       GuidedStepSupportFragment.add(fm, new SecondStepFragment());
    }
...

إذا ضغط المستخدم على زر الرجوع في جهاز التحكّم عن بُعد في التلفزيون، سيعرض الجهاز الرمز GuidedStepSupportFragment السابق على حزمة الأجزاء. إذا قدّمت GuidedAction الخاص بك يُرجع إلى الخطوة السابقة، يمكنك تنفيذ سلوك "الرجوع" من خلال طلب الرمز getFragmentManager().popBackStack(). إذا كنت بحاجة إلى إعادة المستخدم إلى خطوة سابقة في التسلسل، استخدِم popBackStackToGuidedStepSupportFragment() للرجوع إلى GuidedStepSupportFragment محدّد في حزمة الأجزاء.

عندما ينهي المستخدم الخطوة الأخيرة في التسلسل، استخدِم finishGuidedStepSupportFragments() لإزالة جميع مثيلات GuidedStepSupportFragment من الحزمة الحالية والعودة إلى النشاط الرئيسي الأصلي. إذا تمت إضافة أول GuidedStepSupportFragment باستخدام addAsRoot()، سيؤدي استدعاء finishGuidedStepSupportFragments() أيضًا إلى إغلاق النشاط الرئيسي.

تخصيص العرض التقديمي للخطوات

يمكن لفئة GuidedStepSupportFragment استخدام مظاهر مخصّصة تتحكّم في جوانب العرض التقديمي، مثل تنسيق نص العنوان أو الرسوم المتحركة التي تنقلك إلى خطوات الانتقال. يجب أن تكتسب السمات المخصّصة من Theme_Leanback_GuidedStep ويمكن أن توفّر قيمًا إلغاء للسمات المحدّدة في GuidanceStylist وGuidedActionsStylist.

لتطبيق مظهر مخصّص على GuidedStepSupportFragment، عليك تنفيذ أحد الإجراءات التالية:

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

لمزيد من المعلومات حول كيفية إضافة الأنماط والمظاهر، يمكنك الاطّلاع على الأنماط والمظاهر.

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

لتخصيص النمط المرئي لخطواتك بما يتجاوز ما يوفّره تخصيص المظهر، يمكنك استخدام الفئة الفرعية GuidanceStylist أو GuidedActionsStylist وعرض الفئة الفرعية في GuidedStepSupportFragment.onCreateGuidanceStylist() أو GuidedStepSupportFragment.onCreateActionsStylist(). للحصول على تفاصيل حول ما يمكنك تخصيصه في هذه الفئات الفرعية، يمكنك الاطّلاع على المستندات حول GuidanceStylist وGuidedActionsStylist.