新增逐步指南

您的應用程式可能會對使用者執行多步驟工作。舉例來說，您的應用程式可能需要引導使用者購買額外內容、進行複雜的設定，或單純確認決定。上述所有工作都會要求使用者進行一或多個排序的步驟或決策。

Leanback androidx 程式庫提供實作多步驟使用者工作的類別。本頁面說明如何使用 GuidedStepSupportFragment 類別，引導使用者完成一系列決策，以完成工作。GuidedStepSupportFragment採用 TV UI 最佳做法，讓使用者更容易在 TV 裝置上理解及瀏覽多步驟工作。

提供步驟詳細資料

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() (而非 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 值，新增一組行為類似可勾選的圓形按鈕，將動作歸入一組集合。同一清單中具有相同檢查集 ID 的所有動作都會視為已連結。當使用者選取該組合中的其中一項動作時，該動作會處於勾選狀態，且所有其他動作都不勾選。
  • 使用 GuidedDatePickerAction.Builder (而非 onCreateActions() 中的 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 的說明文件。