قد يحتوي تطبيقك على مهام متعددة الخطوات للمستخدمين. على سبيل المثال، قد يحتاج تطبيقك إلى إرشاد المستخدمين خلال شراء محتوى إضافي، أو ضبط إعدادات معقّدة، أو تأكيد القرار ببساطة. تتطلب كل هذه المهام إرشاد المستخدمين خلال خطوة أو قرارات منظمة واحدة أو أكثر.
توفّر مكتبة androidx Leanback صفوفًا لتنفيذ مهام المستخدمين متعددة الخطوات. توضّح هذه الصفحة طريقة استخدام الفئة GuidedStepSupportFragment
لإرشاد المستخدم من خلال سلسلة من القرارات المتعلقة بتنفيذ مهمة. GuidedStepSupportFragment
يستخدم أفضل ممارسات واجهة مستخدم التلفزيون لتسهيل فهم المهام المتعدّدة الخطوات والتنقّل بينها على أجهزة التلفزيون.
تقديم تفاصيل للخطوة
تمثّل السمة GuidedStepSupportFragment
خطوة واحدة ضمن سلسلة من الخطوات. مرئيًا، يوفر عرضًا توجيهيًا مع
قائمة بالإجراءات أو القرارات المحتملة للخطوة.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-screen.png?authuser=5&hl=ar)
الشكل 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
قائمة بالإجراءات التي يتم عرضها كقائمة تضم الإجراءات الفرعية.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-subaction.png?authuser=5&hl=ar)
الشكل 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; }
إجراءات إضافة الزر
إذا كانت خطوتك الإرشادية تحتوي على قائمة كبيرة من الإجراءات، قد يحتاج المستخدمون إلى التمرير عبر القائمة للوصول إلى الإجراءات الأكثر استخدامًا. استخدم إجراءات الأزرار لفصل الإجراءات الشائعة الاستخدام عن قائمة الإجراءات. تظهر إجراءات الأزرار بجوار قائمة الإجراءات ويسهل الانتقال إليها.
![](https://developer.android.com/static/images/training/tv/playback/guided-step-buttonaction.png?authuser=5&hl=ar)
الشكل 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
.