添加引导步骤

使用 Compose 构建更出色的应用
使用适用于 Android TV OS 的 Jetpack Compose，只需极少的代码即可创建精美的界面。
<ph type="x-smartling-placeholder"></ph> Compose for TV →

您的应用可能具有多步骤用户任务。例如，您的应用可能需要 购买其他内容、设置复杂的配置设置或 只是确认决定。所有这些任务都需要引导用户完成一个或多个已排序的 步骤或决策。

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);
}

将 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 可以指定 以子操作菜单的形式显示的子操作。

图 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 对象使用 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。

上一页
向初次使用的用户介绍您的应用
下一页
环境音模式