新增逐步指南

使用 Compose 建構更優質的內容
使用 Jetpack Compose for Android TV OS 以最少的程式碼建立精美的 UI。
Compose for TV →

應用程式可能會為使用者處理多個步驟的工作。例如，應用程式可能需要引導使用者購買其他內容、進行複雜的設定，或單純確認使用者的決定。這些工作都需要引導使用者完成一或多個排序的步驟或決策。

androidx.leanback 程式庫提供實作多步驟使用者工作的類別。本頁面說明如何使用 GuidedStepSupportFragment 類別，引導使用者完成一系列決策以完成任務。GuidedStepSupportFragment 運用 TV UI 最佳做法，讓多步驟工作能在電視裝置上輕鬆理解及瀏覽。

提供步驟的詳細資料

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 物件，請使用 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 可以指定以子動作選單形式顯示的子動作清單。

圖 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. 引導式步驟按鈕動作。

按鈕動作的建立及處理方式與一般動作相同，但您會在 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 的說明文件。