本頁面由 Cloud Translation API 翻譯而成。

為初次接觸的使用者介紹您的應用程式

如果想讓首次使用的使用者瞭解如何充分發揮應用程式的功用，請分享螢幕畫面應用程式啟動時的新手上路資訊以下是一些新手上路的例子每個 ACL 都由一或多個項目組成而這些項目包含兩項資訊

向使用者顯示各種可用管道的詳細資訊會先存取頻道應用程式
吸引使用者註意應用程式中的重要功能。
說明任何必要或建議步驟，讓使用者初次使用應用程式時

androidx.leanback 程式庫提供以下課程的 OnboardingSupportFragment 類別：首次提供使用者資訊本指南說明如何使用要展示的 OnboardingSupportFragment 個類別應用程式首次啟動時會顯示的簡介資訊讓應用程式從可以最快做出回應的位置回應使用者要求

OnboardingSupportFragment 使用 TV UI 以符合電視 UI 樣式的方式呈現資訊的最佳做法電視裝置也易於瀏覽

圖 1. 範例 OnboardingSupportFragment。

OnboardingSupportFragment 不適合所有用途。需要納入時，請勿使用 OnboardingSupportFragment 需要使用者輸入內容的 UI 元素，例如按鈕和欄位。此外，請勿在使用者會執行的工作中使用 OnboardingSupportFragment 定期更新資料最後，如果您需要呈現的多頁 UI 不妨考慮使用 GuidedStepSupportFragment。

新增 OnboardingSupportFragment

如何新增 OnboardingSupportFragment 實作一個 OnboardingSupportFragment 類別。新增將片段傳送至活動，方法為使用活動的版面配置 XML 或編寫程式請確認活動或片段使用的主題衍生自 Theme_Leanback_Onboarding, 詳情請見「自訂主題」一節。

在應用程式的 onCreate() 方法中應用程式的主要活動，呼叫 startActivity() 其中 Intent 指向「OnboardingSupportFragment」的父項活動。這可以確保 OnboardingSupportFragment 顯示為應用程式啟動時。

為了確保 OnboardingSupportFragment 只會在初次啟動應用程式時，請使用 SharedPreferences 個物件追蹤使用者是否已經看過 OnboardingSupportFragment。定義布林值在使用者觀看完畢時，值會變更為 true OnboardingSupportFragment。確認將此值列在主要活動的 onCreate() 方法，且只能在 OnboardingSupportFragment 父項活動 (如果符合以下條件) 值為 false

以下範例顯示檢查 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 物件傳遞資訊方法是覆寫 onFinishFragment() 在您的 OnboardingSupportFragment 中設定 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 設為您的標誌畫面，呼叫 setLogoResourceId() 為您的 Drawable ID onCreate()內您 OnboardingSupportFragment 的方法。系統會逐漸淡入並短暫顯示 Drawable，然後淡出 Drawable ，才能顯示 OnboardingSupportFragment 的第一頁。

如果您想為標誌畫面提供自訂動畫，而非呼叫 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; }

使用傳輸控制項

新增逐步指南