如果想讓首次使用的使用者瞭解如何充分利用應用程式，請在應用程式啟動時顯示新手上路資訊。以下列舉幾個新手上路資訊的範例：
- 顯示使用者首次存取頻道應用程式時，可用的管道詳細資訊。
- 吸引使用者註意應用程式中的重要功能。
- 說明使用者首次使用應用程式時，所有必要或建議的步驟。
androidx.leanback 程式庫提供用於顯示首次使用者資訊的 OnboardingSupportFragment 類別。本指南說明如何使用 OnboardingSupportFragment 類別，在應用程式首次啟動時顯示簡介資訊。
OnboardingSupportFragment 採用 TV UI 最佳做法，以符合電視 UI 樣式的方式呈現資訊，並在電視裝置上輕鬆瀏覽。
圖 1 OnboardingSupportFragment 範例。
OnboardingSupportFragment 不適合所有用途。當您需要加入需要使用者輸入內容的 UI 元素 (例如按鈕和欄位) 時，請勿使用 OnboardingSupportFragment。此外，切勿使用 OnboardingSupportFragment 處理使用者會定期執行的工作。最後，如果您需要呈現需要使用者輸入內容的多頁面 UI，請考慮使用 GuidedStepSupportFragment。
新增 OnboardingSupportFragment
如要在應用程式中新增 OnboardingSupportFragment，請實作擴充 OnboardingSupportFragment 類別的類別。使用活動的版面配置 XML 或程式輔助方式，將此片段新增至活動。請確保活動或片段使用從 Theme_Leanback_Onboarding 衍生的主題，如「自訂主題」一節所述。
在應用程式主要活動的 onCreate() 方法中，使用指向 OnboardingSupportFragment 父項活動的 Intent 呼叫 startActivity()。這可確保 OnboardingSupportFragment 在應用程式啟動時立即顯示。
為確保 OnboardingSupportFragment 只會在使用者首次啟動應用程式時顯示，請使用 SharedPreferences 物件追蹤使用者是否已查看 OnboardingSupportFragment。定義布林值，在使用者查看完 OnboardingSupportFragment 後變更為 true。請在主要活動的 onCreate() 方法中檢查這個值，只在其值為 false 時啟動 OnboardingSupportFragment 父項活動。
以下範例顯示了 onCreate() 的覆寫值，該覆寫值會檢查 SharedPreferences 值；如未設為 true，請呼叫 startActivity() 來顯示 OnboardingSupportFragment：
Kotlin
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
PreferenceManager.getDefaultSharedPreferences(this).apply {
// Check if we need to display our OnboardingSupportFragment
if (!getBoolean(MyOnboardingSupportFragment.COMPLETED_ONBOARDING_PREF_NAME, false)) {
// The user hasn't seen the OnboardingSupportFragment yet, so show it
startActivity(Intent(this@OnboardingActivity, OnboardingActivity::class.java))
}
}
}
Java
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
SharedPreferences sharedPreferences =
PreferenceManager.getDefaultSharedPreferences(this);
// Check if we need to display our OnboardingSupportFragment
if (!sharedPreferences.getBoolean(
MyOnboardingSupportFragment.COMPLETED_ONBOARDING_PREF_NAME, false)) {
// The user hasn't seen the OnboardingSupportFragment yet, so show it
startActivity(new Intent(this, OnboardingActivity.class));
}
}
使用者查看 OnboardingSupportFragment 後，請使用 SharedPreferences 物件將其標示為已檢視。方法是覆寫 OnboardingSupportFragment 中的 onFinishFragment()，並將 SharedPreferences 值設為 true，如以下範例所示：
Kotlin
override fun onFinishFragment() {
super.onFinishFragment()
// User has seen OnboardingSupportFragment, so mark our SharedPreferences
// flag as completed so that we don't show our OnboardingSupportFragment
// the next time the user launches the app
PreferenceManager.getDefaultSharedPreferences(context).edit().apply {
putBoolean(COMPLETED_ONBOARDING_PREF_NAME, true)
apply()
}
}
Java
@Override
protected void onFinishFragment() {
super.onFinishFragment();
// User has seen OnboardingSupportFragment, so mark our SharedPreferences
// flag as completed so that we don't show our OnboardingSupportFragment
// the next time the user launches the app
SharedPreferences.Editor sharedPreferencesEditor =
PreferenceManager.getDefaultSharedPreferences(getContext()).edit();
sharedPreferencesEditor.putBoolean(
COMPLETED_ONBOARDING_PREF_NAME, true);
sharedPreferencesEditor.apply();
}
新增 OnboardingSupportFragment 頁面
OnboardingSupportFragment 會在一系列經過排序的頁面中顯示內容。新增 OnboardingSupportFragment 後，您需要定義新手上路頁面。每個頁面都可以設定標題、說明和多種內含圖片或動畫的子檢視畫面。
圖 2. OnboardingSupportFragment
網頁元素。
圖 2 顯示一個範例頁面，其中顯示的摘要會標示 OnboardingSupportFragment 可提供的可自訂網頁元素。網頁元素如下：
- 網頁標題。
- 網頁說明。
- 網頁內容檢視畫面 (在本例中為灰色方塊中的綠色勾號)。 這個檢視畫面為選用項目。請使用這個畫面來說明網頁的詳細資料。例如，您可以附上強調頁面說明的應用程式功能的螢幕截圖。
- 頁面背景檢視畫面 (本例中為簡單的藍色漸層)。此檢視畫面一律會在頁面上其他檢視畫面的後方轉譯。這個檢視畫面為選用項目。
- 頁面前景檢視畫面，本例中為標誌。此檢視畫面一律會在頁面上所有其他檢視畫面的前面顯示。這個檢視畫面為選用項目。
首次建立 OnboardingSupportFragment 或附加至父項活動時，請初始化頁面資訊，因為系統會在建立片段的檢視畫面時要求頁面資訊。您可以在類別建構函式或 onAttach() 的覆寫中初始化頁面資訊。
覆寫下列所有方法，這些方法會提供系統資訊：
getPageCount()會傳回OnboardingSupportFragment中的頁面數量。getPageTitle()會傳回所要求頁碼的標題。getPageDescription()會傳回所要求頁面編號的說明。
覆寫下列每個方法，提供用來顯示圖片或動畫的選用子檢視畫面：
onCreateBackgroundView()會傳回您建立的View來做為背景檢視畫面，如果不需要背景檢視畫面，則傳回空值。onCreateContentView()會傳回您建立的View做為內容檢視畫面；如果不需要內容檢視，則傳回空值。onCreateForegroundView()會傳回您建立的View做為前景檢視畫面，如果不需要前景檢視畫面，則傳回空值。
系統會將您建立的 View 新增至網頁版面配置中。以下範例會覆寫 onCreateContentView() 並傳回 ImageView：
Kotlin
private lateinit var contentView: ImageView
...
override fun onCreateContentView(inflater: LayoutInflater?, container: ViewGroup?): View? {
return ImageView(context).apply {
scaleType = ImageView.ScaleType.CENTER_INSIDE
setImageResource(R.drawable.onboarding_content_view)
setPadding(0, 32, 0, 32)
contentView = this
}
}
Java
private ImageView contentView;
...
@Override
protected View onCreateContentView(LayoutInflater inflater, ViewGroup container) {
contentView = new ImageView(getContext());
contentView.setScaleType(ImageView.ScaleType.CENTER_INSIDE);
contentView.setImageResource(R.drawable.onboarding_content_view);
contentView.setPadding(0, 32, 0, 32);
return contentView;
}
新增初始標誌畫面
OnboardingSupportFragment 可以從介紹應用程式的選用標誌畫面開始。如果要將 Drawable 顯示為標誌畫面，請在 OnboardingSupportFragment 的 onCreate() 方法中使用 Drawable 的 ID 呼叫 setLogoResourceId()。系統會淡入並短暫顯示 Drawable，然後在顯示 OnboardingSupportFragment 的第一頁之前淡出 Drawable。
如果您想為標誌畫面提供自訂動畫，而非呼叫 setLogoResourceId()，請覆寫 onCreateLogoAnimation()，並傳回可顯示自訂動畫的 Animator 物件，如以下範例所示：
Kotlin
public override fun onCreateLogoAnimation(): Animator =
AnimatorInflater.loadAnimator(context, R.animator.onboarding_logo_screen_animation)
Java
@Override
public Animator onCreateLogoAnimation() {
return AnimatorInflater.loadAnimator(getContext(),
R.animator.onboarding_logo_screen_animation);
}
自訂網頁動畫
當使用者瀏覽 OnboardingSupportFragment 的第一頁時，以及使用者前往不同頁面時，系統會使用預設動畫。如要自訂這些動畫，您可以覆寫 OnboardingSupportFragment 中的方法。
如要自訂第一頁顯示的動畫，請覆寫 onCreateEnterAnimation() 並傳回 Animator。以下範例會建立 Animator，可水平縮放內容檢視畫面：
Kotlin
override fun onCreateEnterAnimation(): Animator =
ObjectAnimator.ofFloat(contentView, View.SCALE_X, 0.2f, 1.0f)
.setDuration(ANIMATION_DURATION)
Java
@Override
protected Animator onCreateEnterAnimation() {
Animator startAnimator = ObjectAnimator.ofFloat(contentView,
View.SCALE_X, 0.2f, 1.0f).setDuration(ANIMATION_DURATION);
return startAnimator;
}
如要自訂使用者前往其他頁面時使用的動畫，請覆寫 onPageChanged()。在 onPageChanged() 方法中，建立 Animator 物件來移除上一頁並顯示下一頁，將這些物件新增至 AnimatorSet，然後播放組合。下例使用淡出動畫移除上一頁、更新內容檢視圖片，並使用淡入效果動畫來顯示下一頁：
Kotlin
override fun onPageChanged(newPage: Int, previousPage: Int) {
// Create a fade-out animation for previousPage and, once
// done, swap the contentView image with the next page's image
val fadeOut = ObjectAnimator.ofFloat(mContentView, View.ALPHA, 1.0f, 0.0f)
.setDuration(ANIMATION_DURATION)
.apply {
addListener(object : AnimatorListenerAdapter() {
override fun onAnimationEnd(animation: Animator) {
mContentView.setImageResource(pageImages[newPage])
}
})
}
// Create a fade-in animation for nextPage
val fadeIn = ObjectAnimator.ofFloat(mContentView, View.ALPHA, 0.0f, 1.0f)
.setDuration(ANIMATION_DURATION)
// Create AnimatorSet with fade-out and fade-in animators and start it
AnimatorSet().apply {
playSequentially(fadeOut, fadeIn)
start()
}
}
Java
@Override
protected void onPageChanged(final int newPage, int previousPage) {
// Create a fade-out animation for previousPage and, once
// done, swap the contentView image with the next page's image
Animator fadeOut = ObjectAnimator.ofFloat(mContentView,
View.ALPHA, 1.0f, 0.0f).setDuration(ANIMATION_DURATION);
fadeOut.addListener(new AnimatorListenerAdapter() {
@Override
public void onAnimationEnd(Animator animation) {
mContentView.setImageResource(pageImages[newPage]);
}
});
// Create a fade-in animation for nextPage
Animator fadeIn = ObjectAnimator.ofFloat(mContentView,
View.ALPHA, 0.0f, 1.0f).setDuration(ANIMATION_DURATION);
// Create AnimatorSet with fade-out and fade-in animators and start it
AnimatorSet set = new AnimatorSet();
set.playSequentially(fadeOut, fadeIn);
set.start();
}
如要進一步瞭解如何建立 Animator 物件和 AnimatorSet 物件，請參閱
屬性動畫總覽。
自訂主題
所有 OnboardingSupportFragment 實作都必須使用 Theme_Leanback_Onboarding 主題，或是沿用自 Theme_Leanback_Onboarding 的主題。透過下列其中一種方式為您的 OnboardingSupportFragment 設定主題：
- 設定
OnboardingSupportFragment的父項活動以使用所需主題。以下範例說明如何在應用程式資訊清單中設定使用Theme_Leanback_Onboarding的活動：<activity android:name=".OnboardingActivity" android:enabled="true" android:exported="true" android:theme="@style/Theme.Leanback.Onboarding"> </activity>
-
使用自訂活動主題中的
LeanbackOnboardingTheme_onboardingTheme屬性，在父項活動中設定主題。將這項屬性指向活動中只有OnboardingSupportFragment物件的其他自訂主題。如果您的活動已使用自訂主題，且您不想將OnboardingSupportFragment樣式套用至活動中的其他檢視畫面，請使用這個方法。 - 覆寫
onProvideTheme()並傳回所需的主題。如有多個活動使用OnboardingSupportFragment，或是父項活動無法使用所需主題，請使用這個方法。以下範例會覆寫onProvideTheme()並傳回Theme_Leanback_Onboarding：Kotlin
override fun onProvideTheme(): Int = R.style.Theme_Leanback_Onboarding
Java
@Override public int onProvideTheme() { return R.style.Theme_Leanback_Onboarding; }