手順ガイドを追加する

アプリには、ユーザーが実行するマルチステップ タスクが含まれる場合があります。たとえば、ユーザーによる追加のコンテンツの購入、複雑な構成設定、単に決定内容の確認を行う手順をアプリで案内する必要がある場合。これらのタスクでは、1 つ以上の順序や決定事項をユーザーに示す必要があります。

Leanback AndroidX ライブラリには、マルチステップ ユーザータスクを実装するクラスが用意されています。このページでは、GuidedStepSupportFragment クラスを使用して、タスクを完了するための一連の決定手順をユーザーに示す方法について説明します。GuidedStepSupportFragment では、TV UI に関するベスト プラクティスを活用し、TV デバイスでマルチステップのタスクを簡単に理解して操作できるようにします。

ステップの詳細な説明を提供する

GuidedStepSupportFragment は、一連のステップの中の 1 つのステップを表します。このステップで考えられるアクションまたは決定事項のリストが、ガイダンスビューに視覚的に示されます。

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

アクティビティの onCreate() メソッドで GuidedStepSupportFragment.add() を呼び出して、GuidedStepSupportFragment サブクラスを目的のアクティビティに追加します。

アクティビティに GuidedStepSupportFragment オブジェクトのみが含まれている場合は、add() ではなく GuidedStepSupportFragment.addAsRoot() を使用して最初の GuidedStepSupportFragment を追加します。addAsRoot() を使用すると、ユーザーが最初の GuidedStepSupportFragment を表示しているときにテレビのリモコンの [戻る] ボタンを押すと、GuidedStepSupportFragment と親アクティビティの両方が閉じます。

注: 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() をオーバーライドして、ユーザーが入力をキャンセルしたタイミングを把握することもできます。
  • 共通の ID 値を持つ checkSetId() を使用してアクションを 1 つのセットにグループ化し、オンにできるラジオボタンのように動作するアクション セットを追加します。同じチェックセット ID を持つ、同じリスト内のすべてのアクションは、リンクされているとみなされます。ユーザーがそのセット内のアクションのいずれかを選択すると、そのアクションのチェックボックスがオンにされ、他のすべてのアクションのチェックボックスはオフになります。
  • onCreateActions()GuidedAction.Builder ではなく GuidedDatePickerAction.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. ガイド付きステップのボタン アクション

ボタン アクションは通常のアクションと同様に作成、処理されますが、onCreateActions() ではなく onCreateButtonActions() でボタン アクションを作成します。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());
    }
...

ユーザーがテレビのリモコンの戻るボタンを押すと、デバイスのフラグメント スタックに前の GuidedStepSupportFragment が表示されます。前のステップに戻る独自の GuidedAction を用意する場合は、getFragmentManager().popBackStack() を呼び出すことで「戻る」動作を実装できます。ユーザーをシーケンスのさらに前のステップに戻す必要がある場合は、popBackStackToGuidedStepSupportFragment() を使用して、フラグメント スタック内の特定の GuidedStepSupportFragment に戻ります。

ユーザーがシーケンスの最後のステップを完了したら、finishGuidedStepSupportFragments() を使用して、現在のスタックからすべての GuidedStepSupportFragment インスタンスを削除し、元の親アクティビティに戻ります。addAsRoot() を使用して最初の GuidedStepSupportFragment を追加した場合、finishGuidedStepSupportFragments() を呼び出すと親アクティビティも終了します。

ステップの表示をカスタマイズする

GuidedStepSupportFragment クラスでは、タイトル テキストの書式設定やステップ遷移アニメーションなど、表示の側面を制御するカスタムテーマを使用できます。カスタムテーマは Theme_Leanback_GuidedStep から継承する必要があり、GuidanceStylistGuidedActionsStylist で定義された属性のオーバーライド値を指定できます。

GuidedStepSupportFragment にカスタムテーマを適用するには、次のいずれかを行います。

  • Android マニフェストで android:theme 属性をアクティビティ要素に設定することで、テーマを親アクティビティに適用します。この属性を設定すると、すべての子ビューにテーマが適用されます。親アクティビティに GuidedStepSupportFragment オブジェクトのみが含まれる場合に、カスタムテーマを適用する最も簡単な方法です。
  • アクティビティですでにカスタムテーマを使用していて、アクティビティ内の他のビューに GuidedStepSupportFragment スタイルを適用したくない場合は、既存のカスタム アクティビティ テーマに LeanbackGuidedStepTheme_guidedStepTheme 属性を追加します。この属性は、アクティビティ内の GuidedStepSupportFragment オブジェクトのみが使用するカスタムテーマを指します。
  • 同じマルチステップ タスク全体に含まれる複数のアクティビティで GuidedStepSupportFragment オブジェクトを使用し、すべてのステップで一貫した視覚的テーマを使用したい場合は、GuidedStepSupportFragment.onProvideTheme() をオーバーライドしてカスタムテーマを返します。

スタイルとテーマを追加する方法について詳しくは、スタイルとテーマをご覧ください。

GuidedStepSupportFragment クラスは、特別なスタイリスト クラスを使用して、テーマ属性にアクセスし、適用します。GuidanceStylist クラスはテーマ情報を使用して左側のガイダンス ビューの表示を制御し、GuidedActionsStylist クラスはテーマ情報を使用して右側のアクション ビューの表示を制御します。

テーマのカスタマイズの機能の範囲を超えてステップのビジュアル スタイルをカスタマイズするには、GuidanceStylist または GuidedActionsStylist をサブクラス化して、GuidedStepSupportFragment.onCreateGuidanceStylist() または GuidedStepSupportFragment.onCreateActionsStylist() でサブクラスを返します。これらのサブクラスでカスタマイズできる内容の詳細については、GuidanceStylistGuidedActionsStylist のドキュメントをご覧ください。