應用程式可能會為使用者處理多個步驟的工作。舉例來說,您的應用程式可能需要 使用者購買額外內容、建立複雜的設定,或是 直接確認決策這些工作都必須引導使用者逐步完成一或多條訂單 步驟或決策
androidx.leanback 程式庫提供實作多步驟使用者工作的類別。這個頁面
則討論如何使用
GuidedStepSupportFragment
門課程
以引導使用者完成一系列決定,以完成某個工作。GuidedStepSupportFragment
使用 TV UI 最佳做法,讓多步驟工作能在電視裝置上輕鬆理解及瀏覽。
提供步驟的詳細資料
GuidedStepSupportFragment
代表系列中的單一步驟
步驟。以視覺方式呈現,並提供
列出步驟中可能採取的動作或決策。
![](https://developer.android.com/static/images/training/tv/playback/guided-step-screen.png?authuser=0&hl=zh-tw)
圖 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); }
將 GuidedStepSupportFragment
子類別新增至需要
呼叫
GuidedStepSupportFragment.add()
呼叫活動的 onCreate()
方法中。
如果您的活動僅包含「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()
,瞭解使用者何時取消輸入。 -
使用
checkSetId()
,以便將動作分類為一組動作。同一份清單中所有動作皆相同 系統會將檢查集 ID 視為已連結。當使用者選取該組合中的任一動作時, 動作會處於勾選狀態,所有其他動作皆會取消勾選。 -
如要新增日期挑選器動作,請使用
GuidedDatePickerAction.Builder
而不是 「onCreateActions()
」的「GuidedAction.Builder
」。覆寫onGuidedActionEditedAndProceed()
可取得使用者輸入的修改日期值。 - 新增含有子動作的動作,讓使用者從更多清單中選擇 如要瞭解訂閱的功能,請參閱「新增子動作」一節。
- 新增會顯示在動作清單右側的按鈕動作,十分方便 方便存取如要瞭解按鈕動作,請參閱「新增按鈕」 動作一節。
你也可以新增視覺指標,用於選取動作
引導出新的步驟
hasNext(true)
。
如要瞭解您可設定的所有屬性,請參閱:
GuidedAction
。
如要回應動作,請覆寫
onGuidedActionClicked()
,並處理傳入的
GuidedAction
。依下列條件識別所選動作:
正在檢查 GuidedAction.getId()
,
新增子動作
有些動作可能會要求您提供多一組選擇。A 罩杯
GuidedAction
可指定
顯示為子項動作選單的子動作。
![](https://developer.android.com/static/images/training/tv/playback/guided-step-subaction.png?authuser=0&hl=zh-tw)
圖 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; }
新增按鈕動作
如果引導步驟包含大量動作清單,使用者可能需要捲動瀏覽清單 即可存取最常用的動作。使用按鈕動作區分 動作清單中的常用動作。按鈕動作會顯示在 以及易於瀏覽的動作
![](https://developer.android.com/static/images/training/tv/playback/guided-step-buttonaction.png?authuser=0&hl=zh-tw)
圖 3. 引導式步驟按鈕動作。
按鈕動作的建立及處理方式和一般動作相同,不過需要
按鈕動作
onCreateButtonActions()
而不是 onCreateActions()
。在以下應用程式中回應按鈕動作:
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
個執行個體
,並返回原始父項活動。如果
已新增前 GuidedStepSupportFragment
使用addAsRoot()
及撥號
finishGuidedStepSupportFragments()
也會關閉父項活動。
自訂步驟簡報
GuidedStepSupportFragment
類別可以使用自訂
控制簡報元素 (例如標題文字格式或步驟轉換)
動畫。自訂主題必須沿用自
Theme_Leanback_GuidedStep
,可提供
取代先前在 YAML 檔案中
「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
。