如需向初次使用的用户展示如何充分利用您的应用,请在应用启动时显示新手入门信息。以下是新手入门信息的一些示例:
- 当用户首次访问频道应用时,显示有关哪些频道可用的详细信息。
- 提醒用户关注您的应用中值得注意的功能。
- 说明用户在首次使用应用时需要执行的任何必需或建议的步骤。
androidx.leanback 库提供用于呈现初次使用的用户信息的 OnboardingSupportFragment
类。本指南介绍了如何使用 OnboardingSupportFragment
类来显示应用首次启动时显示的说明信息。
OnboardingSupportFragment
使用电视界面最佳做法来呈现信息,这种方式不仅适合电视界面风格,而且易于在电视设备上导航。
![](https://developer.android.google.cn/static/images/training/tv/playback/onboarding-fragment.png?authuser=6&hl=th)
图 1. OnboardingSupportFragment
示例。
OnboardingSupportFragment
并不适用于所有用例。如果您需要添加需要用户输入的界面元素(如按钮和字段),请不要使用 OnboardingSupportFragment
。此外,不要将 OnboardingSupportFragment
用于用户会定期执行的任务。最后,如果您需要显示需要用户输入的多页面界面,请考虑使用 GuidedStepSupportFragment
。
添加 OnboardingSupportFragment
如需向应用添加 OnboardingSupportFragment
,请实现一个扩展 OnboardingSupportFragment
类的类。使用 activity 的布局 XML 或以编程方式将此 fragment 添加到 activity。确保 activity 或 fragment 使用派生自 Theme_Leanback_Onboarding
的主题背景,如自定义主题背景部分中所述。
在应用的主 activity 的 onCreate()
方法中,使用指向 OnboardingSupportFragment
的父 activity 的 Intent
调用 startActivity()
。这有助于确保您的 OnboardingSupportFragment
在应用启动时立即显示。
为了确保 OnboardingSupportFragment
仅在用户首次启动您的应用时显示,请使用 SharedPreferences
对象跟踪用户是否已经查看过 OnboardingSupportFragment
。定义一个在用户查看完 OnboardingSupportFragment
时变为 true 的布尔值。请在主 activity 的 onCreate()
方法中检查此值,并且仅在值为 false 时才启动 OnboardingSupportFragment
父 activity。
以下示例展示了 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
后,您需要定义初始配置页面。每个页面可以包含标题、说明和多个可包含图片或动画的子视图。
![](https://developer.android.google.cn/static/images/training/tv/playback/onboarding-fragment-diagram.png?authuser=6&hl=th)
图 2. OnboardingSupportFragment
页面元素。
图 2 展示了一个示例页面,其中包含用于标记 OnboardingSupportFragment
可以提供的自定义页面元素的标注。页面元素包括:
- 页面标题。
- 页面说明。
- 页面内容视图,本例中是一个简单的绿色对勾标记(位于一个灰色方框中)。 此视图是可选的。此视图可用于展示网页详细信息。例如,您可以添加一张屏幕截图,突出显示该页面所描述的应用功能。
- 页面背景视图,本例中为一个简单的蓝色渐变背景。此视图始终呈现在页面上其他视图的后面。此视图是可选的。
- 页面前景视图,本例中为一个徽标。此视图始终呈现在页面上所有其他视图的前面。此视图是可选的。
请在首次创建 OnboardingSupportFragment
或将其附加到父 activity 时初始化页面信息,因为系统会在创建 fragment 的视图时请求页面信息。您可以在类构造函数或 onAttach()
替换中初始化页面信息。
替换以下每种方法,这些方法会向系统提供页面信息:
getPageCount()
会返回OnboardingSupportFragment
中的页面数。getPageTitle()
会返回所请求页码的标题。getPageDescription()
返回所请求页码的说明。
替换以下每种方法,以提供用于显示图片或动画的可选子视图:
onCreateBackgroundView()
会返回您创建的用作背景视图的View
,如果不需要背景视图,则返回 null。onCreateContentView()
会返回您创建的用作内容视图的View
;如果不需要内容视图,则返回 null。onCreateForegroundView()
会返回您创建的用作前景视图的View
,如果不需要前景视图,则返回 null。
系统会将您创建的 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
的父 activity 以使用所需主题。以下示例展示了如何在应用清单中设置 activity 以使用Theme_Leanback_Onboarding
:<activity android:name=".OnboardingActivity" android:enabled="true" android:exported="true" android:theme="@style/Theme.Leanback.Onboarding"> </activity>
-
通过在自定义 activity 主题中使用
LeanbackOnboardingTheme_onboardingTheme
属性,在父 activity 中设置主题。将此属性指向只有您的 activity 中的OnboardingSupportFragment
对象使用的另一个自定义主题。如果您的 activity 已在使用自定义主题,并且您不想将OnboardingSupportFragment
样式应用于 activity 中的其他视图,请采用这种方法。 - 替换
onProvideTheme()
并返回所需的主题背景。如果有多个 activity 使用您的OnboardingSupportFragment
,或者父 activity 无法使用所需的主题背景,请使用此方法。 以下示例会替换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; }