新增逐步指南

使用 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);
}

將 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 可指定 顯示為子項動作選單的子動作。

圖 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 物件 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。

上一頁
為初次接觸的使用者介紹您的應用程式
下一頁
微光效果