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

الإنشاء بشكل أفضل باستخدام 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 الخاصة بك للعودة إلى الخطوة السابقة، يمكنك تنفيذ السلوك "رجوع" (Back) من خلال طلب الرقم 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.