您的应用可能包含多步任务。例如,您的应用可能需要引导用户购买额外内容、设置复杂的配置,或者仅仅是确认一个决定。所有这些任务都需要引导用户完成一个或多个有序步骤或决策。
androidx.leanback 库提供了一些类,用于实现多步用户任务。本页面讨论如何使用 GuidedStepSupportFragment
类引导用户完成一系列决策以完成任务。GuidedStepSupportFragment
采用 TV 界面最佳实践,使多步任务在 TV 设备上易于理解和导航。
提供步骤详情
一个 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); }
通过在 Activity 的 onCreate()
方法中调用 GuidedStepSupportFragment.add()
,将您的 GuidedStepSupportFragment
子类添加到所需的 Activity 中。
如果您的 Activity 只包含 GuidedStepSupportFragment
对象,请使用 GuidedStepSupportFragment.addAsRoot()
而不是 add()
来添加第一个 GuidedStepSupportFragment
。使用 addAsRoot()
有助于确保用户在查看第一个 GuidedStepSupportFragment
时按下 TV 遥控器上的返回按钮后,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 值将操作分组,添加一组行为类似于可选中单选按钮的操作。同一列表中所有具有相同 check-set ID 的操作都被视为关联的。当用户选择该集合中的一个操作时,该操作将被选中,而所有其他操作将被取消选中。 - 在
onCreateActions()
中使用GuidedDatePickerAction.Builder
而不是GuidedAction.Builder
来添加日期选择器操作。覆盖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.add()
将多个 GuidedStepSupportFragment
对象组合在一起,以将序列中的下一步添加到片段堆栈中。
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()); } ...
如果用户按下 TV 遥控器上的返回按钮,设备将显示片段堆栈中的上一个 GuidedStepSupportFragment
。如果您提供自己的 GuidedAction
返回上一步,则可以通过调用 getFragmentManager().popBackStack()
来实现返回行为。如果您需要将用户返回到序列中更早的步骤,请使用 popBackStackToGuidedStepSupportFragment()
返回到片段堆栈中的特定 GuidedStepSupportFragment
。
当用户完成序列中的最后一步时,使用 finishGuidedStepSupportFragments()
从当前堆栈中移除所有 GuidedStepSupportFragment
实例并返回到原始父 Activity。如果第一个 GuidedStepSupportFragment
是使用 addAsRoot()
添加的,则调用 finishGuidedStepSupportFragments()
也会关闭父 Activity。
自定义步骤演示
GuidedStepSupportFragment
类可以使用自定义主题,这些主题控制演示方面,例如标题文本格式或步骤过渡动画。自定义主题必须继承自 Theme_Leanback_GuidedStep
,并且可以为 GuidanceStylist
和 GuidedActionsStylist
中定义的属性提供覆盖值。
要将自定义主题应用于您的 GuidedStepSupportFragment
,请执行以下操作之一:
- 通过在 Android 清单文件中将
android:theme
属性设置为 activity 元素来将主题应用于父 Activity。设置此属性会将主题应用于所有子视图,如果父 Activity 只包含GuidedStepSupportFragment
对象,这是应用自定义主题最直接的方法。 - 如果您的 Activity 已经使用自定义主题,并且您不想将
GuidedStepSupportFragment
样式应用于 Activity 中的其他视图,请将LeanbackGuidedStepTheme_guidedStepTheme
属性添加到您现有的自定义 Activity 主题中。此属性指向您的 Activity 中只有GuidedStepSupportFragment
对象使用的自定义主题。 - 如果您在属于同一整体多步任务的不同 Activity 中使用
GuidedStepSupportFragment
对象,并且希望在所有步骤中使用一致的视觉主题,请覆盖GuidedStepSupportFragment.onProvideTheme()
并返回您的自定义主题。
有关如何添加样式和主题的更多信息,请参阅样式和主题。
GuidedStepSupportFragment
类使用特殊的 样式类 来访问和应用主题属性。GuidanceStylist
类使用主题信息控制左侧引导视图的呈现,而 GuidedActionsStylist
类使用主题信息控制右侧操作视图的呈现。
要自定义步骤的视觉样式,使其超出主题自定义所提供的范围,请子类化 GuidanceStylist
或 GuidedActionsStylist
,并在 GuidedStepSupportFragment.onCreateGuidanceStylist()
或 GuidedStepSupportFragment.onCreateActionsStylist()
中返回您的子类。有关这些子类中可自定义内容的详细信息,请参阅 GuidanceStylist
和 GuidedActionsStylist
的文档。