應用程式可能會為使用者處理多個步驟的工作。例如,應用程式可能需要引導使用者購買其他內容、進行複雜的設定,或單純確認使用者的決定。這些工作都需要引導使用者完成一或多個排序的步驟或決策。
androidx.leanback 程式庫提供實作多步驟使用者工作的類別。本頁面說明如何使用 GuidedStepSupportFragment
類別,引導使用者完成一系列決策以完成任務。GuidedStepSupportFragment
運用 TV UI 最佳做法,讓多步驟工作能在電視裝置上輕鬆理解及瀏覽。
提供步驟的詳細資料
GuidedStepSupportFragment
代表一系列步驟中的一個步驟。以視覺方式呈現,會提供步驟的指引檢視畫面,其中會列出該步驟可採取的動作或決策。
針對多步驟工作中的每個步驟,擴充 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
物件,請使用 GuidedStepSupportFragment.addAsRoot()
新增第一個 GuidedStepSupportFragment
,不要使用 add()
。使用 addAsRoot()
可確保使用者在查看第一個 GuidedStepSupportFragment
時按下電視遙控器上的返回按鈕,這樣 GuidedStepSupportFragment
和父項活動都會關閉。
注意:請透過程式輔助方式 (而非版面配置 XML 檔案) 新增 GuidedStepSupportFragment
物件。
建立及處理使用者動作
覆寫 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()
,將一組動作歸類為一組動作,藉此新增一組動作,此按鈕的行為類似於可勾選的圓形按鈕。系統會將同個清單中具有相同檢查集 ID 的所有動作視為連結。當使用者選取該組合中的任一動作時,該動作會處於勾選狀態,所有其他動作皆會取消勾選。 -
如要新增日期挑選工具動作,請使用
onCreateActions()
中的GuidedDatePickerAction.Builder
,而非GuidedAction.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; }
新增按鈕動作
如果引導步驟包含大量動作清單,使用者可能需要捲動清單才能存取最常用的動作。使用按鈕動作可將常用的動作與動作清單分開。按鈕動作會顯示在動作清單旁邊,方便使用者瀏覽。
按鈕動作的建立及處理方式與一般動作相同,但您會在 onCreateButtonActions()
(而非 onCreateActions()
) 中建立按鈕動作。回應 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:theme
屬性設為 Android 資訊清單中的活動元素,將主題套用至父項活動。設定這項屬性會將主題套用至所有子項檢視畫面,如果父項活動僅包含GuidedStepSupportFragment
物件,則套用自訂主題最簡單。 -
如果活動已使用自訂主題,而您不想對活動中的其他檢視畫面套用
GuidedStepSupportFragment
樣式,請將LeanbackGuidedStepTheme_guidedStepTheme
屬性加入現有的自訂活動主題。這個屬性指向的活動中只包含GuidedStepSupportFragment
物件的自訂主題。 -
如果您在同一個整體多步驟工作中的不同活動中使用
GuidedStepSupportFragment
物件,並想在所有步驟中使用一致的視覺主題,請覆寫GuidedStepSupportFragment.onProvideTheme()
並傳回您的自訂主題。
如要進一步瞭解如何新增樣式和主題,請參閱「樣式與主題」。
GuidedStepSupportFragment
類別會使用特殊的樣式清單類別來存取及套用主題屬性。GuidanceStylist
類別使用主題資訊控制左側指引檢視畫面的呈現方式,GuidedActionsStylist
類別則會使用主題資訊控制適當動作檢視畫面的呈現方式。
除了主題自訂功能外,如要自訂步驟的視覺樣式,請將 GuidanceStylist
或 GuidedActionsStylist
子類別,並在 GuidedStepSupportFragment.onCreateGuidanceStylist()
或 GuidedStepSupportFragment.onCreateActionsStylist()
中傳回子類別。如要進一步瞭解這些子類別中可自訂的內容,請參閱 GuidanceStylist
和 GuidedActionsStylist
的說明文件。