アプリには、ユーザーが実行するマルチステップ タスクが含まれる場合があります。たとえば、追加コンテンツの購入、複雑な構成設定、または単に決定を確認する手順をユーザーに案内する必要がある場合があります。これらのタスクでは、1 つ以上の順序付けされたステップや決定についてユーザーに説明する必要があります。
androidx.leanback ライブラリは、マルチステップ ユーザータスクを実装するクラスを提供します。このページでは、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()をオーバーライドして、ユーザーが入力をキャンセルしたタイミングを把握することもできます。 -
checkSetId()に共通の ID 値を指定して、チェック可能なラジオボタンのように動作するアクション セットを追加して、アクションをセットにグループ化します。同じチェックセット 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 は 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 のドキュメントをご覧ください。