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

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

يمكنك إنشاء واجهات مستخدم رائعة بأقل قدر من الرموز البرمجية باستخدام Jetpack Compose لنظام التشغيل Android 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 صحيحة، لا يمكن للمستخدمين اختيار الإجراء.
• أضِف إجراء نص قابل للتعديل من خلال ضبط editable(true). عندما تكون قيمة editable هي "صحيح"، يمكن للمستخدم إدخال نص في إجراء محدّد باستخدام جهاز التحكّم عن بُعد أو لوحة مفاتيح متصلة. يمكنك إلغاء 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.