アプリには、ユーザーが実行するマルチステップ タスクが含まれる場合があります。たとえば、追加コンテンツの購入や、複雑な構成設定のセットアップ、選択の確定など、アプリ内でユーザーに手順のガイドを示すことが必要となる場合があります。このようなタスクの場合、1 つまたは複数のステップや決定を順序どおりに進めるよう、必ずユーザーに説明する必要があります。
非推奨の androidx.leanback ライブラリには、マルチステップ ユーザータスクを実装するクラスが用意されています。このページでは、GuidedStepSupportFragment クラスを使用して、GuidedStepSupportFragment を使用してタスクが完了するまでの一連の決定ステップをユーザーにガイドする方法について説明します。
ステップの詳細な説明を提供する
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()をオーバーライドして、ユーザーがいつ入力をキャンセルしたかを知ることもできます。 -
checkSetId()を使用して共通の ID 値を指定し、複数のアクションを 1 つのセットにグループ化すると、チェック可能なラジオボタンとして動作するアクション セットを追加できます。同じリスト内で同じチェックセット ID を持つアクションは、すべてリンクしているものと見なされます。ユーザーがセット内のアクションを 1 つ選択すると、そのアクションがチェックされ、他のすべてのアクションのチェックが解除されます。 -
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; }
ボタン アクションを追加する
1 つのガイド付きステップ内に多数のアクションのリストが含まれていると、ユーザーが最も頻繁に使用するアクションを表示するためにリストをスクロールしなければならなくなることがあります。ボタン アクションを利用すると、頻繁に使用されるアクションをアクション リストから分離できます。ボタン アクションは、アクション リストの横に表示され、簡単にアクセスできます。
図 3. ガイド付きステップのボタン アクション
ボタン アクションは通常のアクションと同様に作成および処理されますが、ボタン アクションの作成は onCreateActions() ではなく onCreateButtonActions() で行います。ボタン アクションへの応答は onGuidedActionClicked() で行います。
ボタン アクションは、ステップ間の移動などのシンプルなアクションに使用してください。日付選択アクションやその他の編集可能アクションは、ボタン アクションとして使用しないでください。また、ボタン アクションにサブアクションを組み込むことはできません。
複数のガイド付きステップをガイド付きシーケンスにグループ化する
GuidedStepSupportFragment は 1 つのステップを表します。順序付けられたステップのシーケンスを作成するには、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 に関するドキュメントをご覧ください。