新增逐步指南

您的應用程式可能會為使用者提供多步驟工作。舉例來說,您的應用程式可能需要引導使用者購買額外內容、進行複雜的配置設定,或單純確認決策。所有這些工作都需要引導使用者完成一或多個已排序的步驟或決策。

Leanback Androidx 程式庫提供可實作多步驟使用者工作的類別。本頁說明如何使用 GuidedStepSupportFragment 類別,引導使用者完成一系列決策來完成工作。GuidedStepSupportFragment 採用電視使用者介面的最佳做法,讓使用者能輕鬆理解及瀏覽電視裝置上的多步驟工作。

提供步驟詳細資料

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(),瞭解使用者何時取消輸入內容。
  • 使用搭配通用 ID 值的 checkSetId(),將動作組合成一組動作,新增一組運作方式與可勾選圓形按鈕類似的動作。系統會將相同清單內具有相同檢查集 ID 的所有動作視為已連結。當使用者選取該組合中的其中一個動作時,系統會檢查該動作,並取消勾選所有其他動作。
  • 新增日期挑選器動作,使用 GuidedDatePickerAction.BuilderonCreateActions() 中而不是 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,可針對 GuidanceStylistGuidedActionsStylist 中定義的屬性提供覆寫值。

如要為 GuidedStepSupportFragment 套用自訂主題,請執行下列任一操作:

  • android:theme 屬性設為 Android 資訊清單中的活動元素,將主題套用至父項活動。設定這項屬性後,系統會將主題套用至所有子項檢視畫面,而如果父項活動只包含 GuidedStepSupportFragment 物件,則套用自訂主題是最直接的方式。
  • 如果活動已使用自訂主題,且您不想將 GuidedStepSupportFragment 樣式套用至活動中的其他檢視畫面,請將 LeanbackGuidedStepTheme_guidedStepTheme 屬性新增至現有的自訂活動主題。這個屬性會指向只有活動中使用的 GuidedStepSupportFragment 物件的自訂主題。
  • 如果您在整體多步驟任務中的不同活動中使用 GuidedStepSupportFragment 物件,且想在所有步驟中使用一致的視覺主題,請覆寫 GuidedStepSupportFragment.onProvideTheme() 並傳回您的自訂主題。

如要進一步瞭解如何新增樣式和主題,請參閱「樣式與主題」。

GuidedStepSupportFragment 類別會使用特殊的樣式清單類別存取及套用主題屬性。GuidanceStylist 類別會使用主題資訊,控制左側導覽檢視畫面的呈現方式,GuidedActionsStylist 類別則會使用主題資訊,控制右側動作檢視畫面的呈現方式。

除了主題自訂提供的功能外,如要自訂步驟的視覺樣式,請將 GuidanceStylistGuidedActionsStylist 設為子類別,並在 GuidedStepSupportFragment.onCreateGuidanceStylist()GuidedStepSupportFragment.onCreateActionsStylist() 中傳回子類別。如要進一步瞭解您可在這些子類別中自訂的內容,請參閱 GuidanceStylistGuidedActionsStylist 的說明文件。