向首次使用应用的用户介绍您的应用

使用 Compose 构建更优秀的应用
使用 Jetpack Compose for Android TV OS 创建美观的 UI，并使用最少的代码。
Compose for TV →

为了向首次使用的用户展示如何充分利用您的应用，请在应用启动时提供入门信息。以下是一些入门信息的示例

  • 在用户首次访问频道应用时，提供有关可用频道的详细信息。
  • 提请用户注意应用中的重要功能。
  • 说明用户在首次使用应用时需要或建议采取的步骤。

该 androidx.leanback 库 提供 OnboardingSupportFragment 类用于呈现首次用户的信息。本指南介绍如何使用 OnboardingSupportFragment 类来呈现首次启动应用时显示的介绍性信息。

OnboardingSupportFragment 使用 TV UI 最佳实践以符合 TV 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可以提供的可自定义页面元素。页面元素包括

  1. 页面标题。
  2. 页面描述。
  3. 页面内容视图，在本例中为灰色框中的绿色勾号。此视图是可选的。使用此视图来说明页面详细信息。例如，您可以包含一个突出显示页面所述应用功能的屏幕截图。
  4. 页面背景视图，在本例中为简单的蓝色渐变。此视图始终呈现于页面上其他视图的后面。此视图是可选的。
  5. 页面前景视图，在本例中为徽标。此视图始终呈现于页面上所有其他视图的前面。此视图是可选的。

在首次创建或附加到父活动时初始化页面信息，因为系统在创建片段的视图时会请求页面信息。您可以在类的构造函数或onAttach()的覆盖中初始化页面信息。

覆盖以下每个方法，这些方法向系统提供页面信息

覆盖以下每个方法以提供可选的子视图来显示图像或动画

系统会将您创建的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;
}
上一步
使用传输控件
下一步
添加引导步骤