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

إنشاء تطبيقات أفضل باستخدام Compose

يمكنك إنشاء واجهات مستخدم جميلة باستخدام الحد الأدنى من الرموز البرمجية من خلال Jetpack Compose لنظام التشغيل Android TV.

Compose for TV →

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

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

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

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

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

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

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)
    )
}

@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 لإضافة إجراءات جديدة.

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())
    ...

@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 مضبوطة على true، لا يمكن للمستخدمين اختيار الإجراء.
• يمكنك إضافة إجراء نص قابل للتعديل من خلال ضبط editable(true). عندما تكون editable مضبوطة على true، يمكن للمستخدم إدخال نص في إجراء محدّد باستخدام جهاز التحكّم عن بُعد أو لوحة مفاتيح متصلة. يمكنك إلغاء onGuidedActionEditedAndProceed() للحصول على النص المعدَّل الذي أدخله المستخدم. يمكنك أيضًا إلغاء onGuidedActionEditCanceled() لمعرفة متى يلغي المستخدم الإدخال.
• يمكنك إضافة مجموعة من الإجراءات التي تتصرف مثل أزرار الاختيار القابلة للتحديد من خلال استخدام checkSetId() مع قيمة معرّف شائعة لتجميع الإجراءات في مجموعة. تُعدّ جميع الإجراءات في القائمة نفسها التي تتضمّن المعرّف نفسه لمجموعة أزرار الاختيار مرتبطة. عندما يختار المستخدم أحد الإجراءات ضمن هذه المجموعة، يتم وضع علامة في المربّع بجانب هذا الإجراء وإزالة العلامة من المربّع بجانب جميع الإجراءات الأخرى.
• يمكنك إضافة إجراء منتقي التاريخ من خلال استخدام GuidedDatePickerAction.Builder بدلاً من GuidedAction.Builder في onCreateActions(). يمكنك إلغاء onGuidedActionEditedAndProceed() للحصول على قيمة التاريخ المعدَّلة التي أدخلها المستخدم.
• يمكنك إضافة إجراء يستخدم إجراءات فرعية للسماح للمستخدم بالاختيار من قائمة موسّعة من الخيارات. يتم وصف الإجراءات الفرعية في قسم إضافة إجراءات فرعية.
• يمكنك إضافة إجراء زر يظهر على يسار قائمة الإجراءات ويسهل الوصول إليه. يتم وصف إجراءات الأزرار في قسم إضافة إجراءات الأزرار.

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

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

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

إضافة إجراءات فرعية

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

الشكل 2: الإجراءات الفرعية للخطوة الإرشادية

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

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

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

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 على المستوى الأعلى يعرض قائمة الإجراءات الفرعية عند اختياره:

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

@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():

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
}

@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() لإضافة الخطوة التالية في التسلسل إلى مكدس الأجزاء.

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

@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.