アプリには、ユーザーが実行するマルチステップ タスクが含まれる場合があります。たとえば、追加コンテンツの購入や、複雑な構成設定のセットアップ、シンプルな選択の確定など、アプリ内でユーザーに手順のガイドを示すことが必要となる場合があります。この種のすべてのタスクでは、ユーザーが 1 つまたは複数の手順または決定を順序どおりに進められるようにガイドする必要があります。
Leanback AndroidX ライブラリには、マルチステップ ユーザータスクを実装するクラスが用意されています。このレッスンでは、GuidedStepSupportFragment クラスを使用して、タスクが完了するまでの一連の決定ステップをユーザーにガイドする方法を説明します。GuidedStepSupportFragment は、TV UI に関するベスト プラクティスを使用して、マルチステップ タスクを TV デバイス上で簡単に理解して実行できるようにします。
ステップの詳細な説明を提供する
GuidedStepSupportFragment は、一連のステップ内の 1 つのステップを表します。左側には、ステップの情報を示すガイダンス ビューがわかりやすく表示されます。右側には、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()をオーバーライドして、ユーザーがいつ入力をキャンセルしたかを知ることもできます。 -
checkSetId()を使用して共通の ID 値を指定し、複数のアクションを 1 つのセットにグループ化すると、チェック可能なラジオボタンとして動作するアクション セットを追加できます。同じリスト内で同じチェックセット ID を持つアクションは、すべてリンクしているものと見なされます。ユーザーがセット内のアクションを 1 つ選択すると、そのアクションがチェックされ、他のすべてのアクションのチェックが解除されます。 -
onCreateActions()のGuidedAction.Builderに代わりにGuidedDatePickerAction.Builderを使用して、日付選択アクションを追加できます。onGuidedActionEditedAndProceed()をオーバーライドすると、ユーザーが入力した変更済みの日付の値を取得できます。 - サブアクションを使用するアクションを追加すると、ユーザーが選択肢の拡張リストの中から選択することが可能になります。サブアクションについては、サブアクションを追加するをご覧ください。
- ボタン アクションを追加できます。ボタン アクションは、アクション リストの右側に表示され、簡単にアクセスできます。ボタン アクションについては、ボタン アクションを追加するをご覧ください。
また、hasNext(true) を設定すると、わかりやすいインジケーターを追加できます。インジケーターは、アクションを選択すると新しいステップに進むことを示します。設定できるすべての属性については、GuidedAction をご覧ください。
アクションに応答するには、onGuidedActionClicked() をオーバーライドして、渡された GuidedAction を処理します。選択されたアクションを識別するには、GuidedAction.getId() を調べます。
サブアクションを追加する
アクションによっては、ユーザーに追加の選択肢のセットを提供する必要があります。GuidedAction を使用すると、サブアクションのリストを指定し、子アクションのプルダウン リストとして表示できます。
図 2. ガイド付きステップのサブアクション
サブアクション リストには、通常のアクションやラジオボタン アクションを含めることはできますが、日付選択アクションまたは編集可能テキスト アクションを含めることはできません。また、複数のレベルを持つサブアクションはサポートされておらず、サブアクションの中にさらにサブアクションのセットを組み込むことはできません。 アクション セットのネストを深くすると、ユーザー エクスペリエンスが低下します。
サブアクションを追加するには、まず、サブアクションとして機能する GuidedActions のリストを作成し、その内容を指定します。
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 drop-down list, or
// false to keep the drop-down list 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 drop-down list, or
// false to keep the drop-down list expanded.
return true;
}
ボタン アクションを追加する
1 つのガイド付きステップ内に多数のアクションのリストが含まれていると、ユーザーが最も頻繁に使用するアクションを表示するためにリストをスクロールしなければならなくなることがあります。ボタン アクションを利用すると、頻繁に使用されるアクションをアクション リストから分離できます。ボタン アクションは、アクション リストの右側に表示され、簡単にアクセスできます。
図 3. ガイド付きステップのボタン アクション
ボタン アクションは通常のアクションと同様に作成および処理されますが、ボタン アクションの作成は onCreateActions() ではなく onCreateButtonActions() で行います。ボタン アクションへの応答は onGuidedActionClicked() で行います。
ボタン アクションは、ステップ間の移動などのシンプルなアクションに使用してください。日付選択アクションやその他の編集可能アクションは、ボタン アクションとして使用しないでください。 また、ボタン アクションにサブアクションを組み込むことはできません。
複数のガイド付きステップをガイド付きシーケンスにグループ化する
GuidedStepSupportFragment は単一のステップを表しますが、複数のステップを順序付きシーケンスにまとめたい場合があります。複数の GuidedStepSupportFragment オブジェクトをグループ化するには、GuidedStepSupportFragment.add() を使用して、シーケンス内の次のステップをフラグメント スタックに追加します。
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 に関するドキュメントをご覧ください。