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

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

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

إنشاء رسالة للتلفزيون →

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

توفر مكتبة 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 على true، يمكن للمستخدم إدخال نص في إجراء محدّد باستخدام عن بُعد أو لوحة مفاتيح متصلة. تجاهُل 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