您的應用程式可能會為使用者提供多步驟工作。舉例來說,您的應用程式可能需要引導使用者購買額外內容、進行複雜的配置設定,或單純確認決策。所有這些工作都需要引導使用者完成一或多個已排序的步驟或決策。
Leanback Androidx 程式庫提供可實作多步驟使用者工作的類別。本頁說明如何使用 GuidedStepSupportFragment
類別,引導使用者完成一系列決策來完成工作。GuidedStepSupportFragment
採用電視使用者介面的最佳做法,讓使用者能輕鬆理解及瀏覽電視裝置上的多步驟工作。
提供步驟詳細資料
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()
而非 add()
新增第一個 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()
,將動作組合成一組動作,新增一組運作方式與可勾選圓形按鈕類似的動作。系統會將相同清單內具有相同檢查集 ID 的所有動作視為已連結。當使用者選取該組合中的其中一個動作時,系統會檢查該動作,並取消勾選所有其他動作。 -
新增日期挑選器動作,使用
GuidedDatePickerAction.Builder
在onCreateActions()
中而不是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
的說明文件。