如果想讓首次使用的使用者瞭解如何充分利用應用程式,請在應用程式啟動時顯示新手上路資訊。以下列舉幾個新手上路資訊的範例:
- 顯示使用者首次存取頻道應用程式時,可用的管道詳細資訊。
- 吸引使用者註意應用程式中的重要功能。
- 說明使用者首次使用應用程式時,所有必要或建議的步驟。
androidx.leanback 程式庫提供用於顯示首次使用者資訊的 OnboardingSupportFragment
類別。本指南說明如何使用 OnboardingSupportFragment
類別,在應用程式首次啟動時顯示簡介資訊。
OnboardingSupportFragment
採用 TV UI 最佳做法,以符合電視 UI 樣式的方式呈現資訊,並在電視裝置上輕鬆瀏覽。
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
可提供的可自訂網頁元素。網頁元素如下:
- 網頁標題。
- 網頁說明。
- 網頁內容檢視畫面 (在本例中為灰色方塊中的綠色勾號)。 這個檢視畫面為選用項目。請使用這個畫面來說明網頁的詳細資料。例如,您可以附上強調頁面說明的應用程式功能的螢幕截圖。
- 頁面背景檢視畫面 (本例中為簡單的藍色漸層)。此檢視畫面一律會在頁面上其他檢視畫面的後方轉譯。這個檢視畫面為選用項目。
- 頁面前景檢視畫面,本例中為標誌。此檢視畫面一律會在頁面上所有其他檢視畫面的前面顯示。這個檢視畫面為選用項目。
首次建立 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; }