添加引导式步骤

使用 Compose 更好地构建
使用 Jetpack Compose for Android TV OS 以最少的代码创建精美的界面。

您的应用可能包含多步任务。例如,您的应用可能需要引导用户购买额外内容、设置复杂的配置,或者仅仅是确认一个决定。所有这些任务都需要引导用户完成一个或多个有序步骤或决策。

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,并且可以为 GuidanceStylistGuidedActionsStylist 中定义的属性提供覆盖值。

要将自定义主题应用于您的 GuidedStepSupportFragment,请执行以下操作之一:

  • 通过在 Android 清单文件中将 android:theme 属性设置为 activity 元素来将主题应用于父 Activity。设置此属性会将主题应用于所有子视图,如果父 Activity 只包含 GuidedStepSupportFragment 对象,这是应用自定义主题最直接的方法。
  • 如果您的 Activity 已经使用自定义主题,并且您不想将 GuidedStepSupportFragment 样式应用于 Activity 中的其他视图,请将 LeanbackGuidedStepTheme_guidedStepTheme 属性添加到您现有的自定义 Activity 主题中。此属性指向您的 Activity 中只有 GuidedStepSupportFragment 对象使用的自定义主题。
  • 如果您在属于同一整体多步任务的不同 Activity 中使用 GuidedStepSupportFragment 对象,并且希望在所有步骤中使用一致的视觉主题,请覆盖 GuidedStepSupportFragment.onProvideTheme() 并返回您的自定义主题。

有关如何添加样式和主题的更多信息,请参阅样式和主题

GuidedStepSupportFragment 类使用特殊的 样式类 来访问和应用主题属性。GuidanceStylist 类使用主题信息控制左侧引导视图的呈现,而 GuidedActionsStylist 类使用主题信息控制右侧操作视图的呈现。

要自定义步骤的视觉样式,使其超出主题自定义所提供的范围,请子类化 GuidanceStylistGuidedActionsStylist,并在 GuidedStepSupportFragment.onCreateGuidanceStylist()GuidedStepSupportFragment.onCreateActionsStylist() 中返回您的子类。有关这些子类中可自定义内容的详细信息,请参阅 GuidanceStylistGuidedActionsStylist 的文档。