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