アプリには、ユーザーが実行するマルチステップ タスクが含まれる場合があります。たとえば、ユーザーによる追加のコンテンツの購入、複雑な構成設定、単に決定内容の確認を行う手順をアプリで案内する必要がある場合。これらのタスクでは、1 つ以上の順序や決定事項をユーザーに示す必要があります。
Leanback AndroidX ライブラリには、マルチステップ ユーザータスクを実装するクラスが用意されています。このページでは、GuidedStepSupportFragment
クラスを使用して、タスクを完了するための一連の決定手順をユーザーに示す方法について説明します。GuidedStepSupportFragment
では、TV UI に関するベスト プラクティスを活用し、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); }
アクティビティの 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
を使用すると、子アクションのメニューとして表示されるサブアクションのリストを指定できます。
サブアクション リストには、通常のアクションまたはラジオボタン アクションを含めることができます。日付選択ツールや編集可能なテキスト アクションを含めることはできません。また、システムは複数レベルのサブアクションをサポートしていないため、サブアクションが独自のサブアクション セットを持つことはできません。
サブアクションを追加するには、まず、サブアクションとして機能する 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; }
ボタン アクションを追加する
ガイド付きの手順に多数のアクション リストが含まれる場合、よく使用されるアクションにアクセスするには、リストをスクロールする必要があります。ボタン アクションを使用すると、よく使用されるアクションとアクション リストを分離できます。ボタン アクションはアクション リストの横に表示され、簡単に移動できます。
ボタン アクションは通常のアクションと同様に作成、処理されますが、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
から継承する必要があり、GuidanceStylist
と GuidedActionsStylist
で定義された属性のオーバーライド値を指定できます。
GuidedStepSupportFragment
にカスタムテーマを適用するには、次のいずれかを行います。
-
Android マニフェストで
android:theme
属性をアクティビティ要素に設定することで、テーマを親アクティビティに適用します。この属性を設定すると、すべての子ビューにテーマが適用されます。親アクティビティにGuidedStepSupportFragment
オブジェクトのみが含まれる場合に、カスタムテーマを適用する最も簡単な方法です。 -
アクティビティですでにカスタムテーマを使用していて、アクティビティ内の他のビューに
GuidedStepSupportFragment
スタイルを適用したくない場合は、既存のカスタム アクティビティ テーマにLeanbackGuidedStepTheme_guidedStepTheme
属性を追加します。この属性は、アクティビティ内のGuidedStepSupportFragment
オブジェクトのみが使用するカスタムテーマを指します。 -
同じマルチステップ タスク全体に含まれる複数のアクティビティで
GuidedStepSupportFragment
オブジェクトを使用し、すべてのステップで一貫した視覚的テーマを使用したい場合は、GuidedStepSupportFragment.onProvideTheme()
をオーバーライドしてカスタムテーマを返します。
スタイルとテーマを追加する方法について詳しくは、スタイルとテーマをご覧ください。
GuidedStepSupportFragment
クラスは、特別なスタイリスト クラスを使用して、テーマ属性にアクセスし、適用します。GuidanceStylist
クラスはテーマ情報を使用して左側のガイダンス ビューの表示を制御し、GuidedActionsStylist
クラスはテーマ情報を使用して右側のアクション ビューの表示を制御します。
テーマのカスタマイズの機能の範囲を超えてステップのビジュアル スタイルをカスタマイズするには、GuidanceStylist
または GuidedActionsStylist
をサブクラス化して、GuidedStepSupportFragment.onCreateGuidanceStylist()
または GuidedStepSupportFragment.onCreateActionsStylist()
でサブクラスを返します。これらのサブクラスでカスタマイズできる内容の詳細については、GuidanceStylist
と GuidedActionsStylist
のドキュメントをご覧ください。