您的应用可能具有多步骤用户任务。例如,您的应用可能需要 购买其他内容、设置复杂的配置设置或 只是确认决定。所有这些任务都需要引导用户完成一个或多个已排序的 步骤或决策。
androidx.leanback 库提供了用于实现多步骤用户任务的类。当前页面
我们将探讨如何使用
GuidedStepSupportFragment
类
来引导用户做出一系列决定,以便完成一项任务。GuidedStepSupportFragment
使用 TV 界面最佳实践,让多步骤任务易于理解并在 TV 设备上导航。
提供步骤详情
GuidedStepSupportFragment
表示系列中的单个步骤
步数。从直观上看,它提供了一个指导视图,其中包含
针对相应步骤可能执行的操作或决策的列表。
![](https://developer.android.google.cn/static/images/training/tv/playback/guided-step-screen.png?authuser=7&hl=sr)
图 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()
(位于 activity 的 onCreate()
方法中)。
如果您的活动记录仅包含 GuidedStepSupportFragment
对象,请使用 GuidedStepSupportFragment.addAsRoot()
而不是 add()
来添加第一个 GuidedStepSupportFragment
。使用
addAsRoot()
有助于确保用户在观看时按电视遥控器上的返回按钮
第一个 GuidedStepSupportFragment
,
GuidedStepSupportFragment
,并且父 activity 会关闭。
注意:请将
以编程方式创建 GuidedStepSupportFragment
对象,
不包含在布局 XML 文件中
创建和处理用户操作
通过覆盖来添加用户操作
onCreateActions()
。
在替换项中,为每个项添加新的 GuidedAction
操作项,并提供操作字符串、说明和 ID。使用
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
为 true 时,用户无法选择操作。 -
通过设置添加可修改的文本操作
editable(true)
。 当editable
为 true 时,用户可以使用 遥控器或连接的键盘。替换onGuidedActionEditedAndProceed()
:用于获取用户输入的修改后的文本。您还可以替换onGuidedActionEditCanceled()
以了解用户何时取消输入。 -
使用
checkSetId()
使用通用 ID 值将操作划分为一组。同一列表中所有具有相同属性的操作 将被视为已关联。如果用户选择了该组中的某个操作 操作将变为选中状态,所有其他操作均会处于未选中状态。 -
使用以下代码添加日期选择器操作:
GuidedDatePickerAction.Builder
而非 “onCreateActions()
”中的“GuidedAction.Builder
”。替换onGuidedActionEditedAndProceed()
:用于获取用户输入的修改后的日期值。 - 添加使用子操作的操作,让用户可以从扩展的 选择。添加子操作部分介绍了子操作。
- 添加显示在操作列表右侧的按钮操作,操作起来非常简单 可访问性。“添加”按钮 操作部分。
你还可以添加视觉指示符,指示你选择某项操作
又推出了一个新步骤
hasNext(true)
。
有关您可以设置的所有不同属性,请参阅
GuidedAction
。
如需响应操作,请覆盖
onGuidedActionClicked()
,并处理传入的
GuidedAction
。通过以下方式标识所选操作:
正在检查“GuidedAction.getId()
”。
添加子操作
有些操作可能会要求您为用户提供一组额外的选项。答
GuidedAction
可以指定
以子操作菜单的形式显示的子操作。
![](https://developer.android.google.cn/static/images/training/tv/playback/guided-step-subaction.png?authuser=7&hl=sr)
图 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.google.cn/static/images/training/tv/playback/guided-step-buttonaction.png?authuser=7&hl=sr)
图 3. 引导步骤按钮操作。
按钮操作的创建和处理方式与常规操作一样,只不过你创建
按钮操作
onCreateButtonActions()
而非 onCreateActions()
。响应以下按钮中的按钮操作:
onGuidedActionClicked()
。
将按钮操作用于简单操作,例如步骤之间的导航操作。 请勿将日期选择器操作或其他可修改操作用作按钮操作。 此外,按钮操作不能包含子操作。
将引导步骤分组到引导序列中
GuidedStepSupportFragment
代表一个步骤。要创建有序的步骤序列,请将多个
GuidedStepSupportFragment
对象使用
GuidedStepSupportFragment.add()
项待添加
序列中的下一步到 fragment 堆栈。
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()); } ...
如果用户按电视遥控器上的返回按钮,设备会显示上一个
针对 fragment 堆栈的 GuidedStepSupportFragment
。如果您
提供自己的 GuidedAction
,
即可实现“返回”行为,只需调用
getFragmentManager().popBackStack()
。
如果您需要让用户返回到序列中更早的步骤,请使用
popBackStackToGuidedStepSupportFragment()
即可返回 fragment 堆栈中的特定 GuidedStepSupportFragment
。
当用户完成序列中的最后一步时,使用
finishGuidedStepSupportFragments()
即可全部移除
GuidedStepSupportFragment
个实例
从当前堆栈返回并返回到原始父 activity。如果
添加了前 GuidedStepSupportFragment
使用 addAsRoot()
,调用
finishGuidedStepSupportFragments()
还会关闭父 activity。
自定义步骤呈现
GuidedStepSupportFragment
类可以使用自定义
可控制演示文稿各个方面(例如标题文本格式或步骤转换)的主题
动画。自定义主题必须继承自
Theme_Leanback_GuidedStep
,并可提供
覆盖在
GuidanceStylist
和
GuidedActionsStylist
。
如需将自定义主题应用于 GuidedStepSupportFragment
,请执行以下操作:
执行以下任一操作:
-
通过将
android:theme
属性设置为 activity 元素。设置此属性会将主题应用于所有子元素 视图,如果父 activity 仅包含GuidedStepSupportFragment
对象。 -
如果您的 activity 已使用自定义主题,但不想应用
GuidedStepSupportFragment
样式应用于 activity 中的其他视图, 添加LeanbackGuidedStepTheme_guidedStepTheme
属性添加到现有的自定义活动主题。此属性指向 只有GuidedStepSupportFragment
对象 活动使用。 -
如果您在不同的位置使用
GuidedStepSupportFragment
对象, 属于同一个整体多步骤任务的一部分,并且希望使用一致的 所有步骤的视觉主题,替换GuidedStepSupportFragment.onProvideTheme()
并返回您的自定义主题。
如需详细了解如何添加样式和主题,请参阅 样式和主题。
GuidedStepSupportFragment
类使用特殊的
stylist 类,用于访问和应用主题属性。
GuidanceStylist
类使用主题信息
来控制左侧导航视图的显示,而
GuidedActionsStylist
类使用主题信息
来控制正确操作视图的显示。
如需在主题自定义功能之外自定义步骤的视觉样式,请创建子类
GuidanceStylist
或
GuidedActionsStylist
,并在
GuidedStepSupportFragment.onCreateGuidanceStylist()
或
GuidedStepSupportFragment.onCreateActionsStylist()
。
如需详细了解您可以在这些子类中自定义的内容,请参阅
GuidanceStylist
和
GuidedActionsStylist
。