تعريف المستخدمين لأول مرة على تطبيقك

الإنشاء بشكل أفضل باستخدام Compose

يمكنك إنشاء واجهات مستخدم رائعة باستخدام أقل عدد ممكن من الرموز باستخدام Jetpack Compose لنظام التشغيل Android TV.

إنشاء رسالة للتلفزيون →

ولإطلاع المستخدم لأول مرة على كيفية الاستفادة إلى أقصى حد من تطبيقك، يُرجى تقديم الإعداد عند بدء تشغيل التطبيق. في ما يلي بعض الأمثلة على خطوات إعداد الموظفين المعلومات:

• تقديم معلومات تفصيلية حول القنوات المتاحة عندما يكون المستخدم يدخل أولاً إلى تطبيق القناة.
• يمكنك لفت انتباه المستخدمين إلى الميزات البارزة في تطبيقك.
• توضيح أي خطوات مطلوبة أو يُنصح بها يجب أن يتّخذها المستخدمون عند استخدام التطبيق لأول مرة.

وتوفر مكتبة androidx.leanback صف واحد (OnboardingSupportFragment) لمدة تقديم معلومات المستخدم لأول مرة. يصف هذا الدليل طريقة استخدام يمكن مشاركة العرض في صف واحد (OnboardingSupportFragment). المعلومات التمهيدية التي يتم عرضها عند تشغيل التطبيق لأول مرة الوقت.

يستخدم "OnboardingSupportFragment" واجهة مستخدم التلفزيون. أفضل الممارسات لتقديم المعلومات بطريقة تتوافق مع أنماط واجهة مستخدم التلفزيون ويسهل التنقل فيها على أجهزة التلفزيون.

الشكل 1. مثال OnboardingSupportFragment

لا تُعدّ السمة OnboardingSupportFragment مناسبة لجميع حالات الاستخدام. عدم استخدام OnboardingSupportFragment عند الحاجة إلى تضمين عناصر واجهة المستخدم التي تتطلب من المستخدم البيانات، مثل الأزرار والحقول يجب أيضًا عدم استخدام OnboardingSupportFragment في المهام التي يؤدّيها المستخدم. بانتظام. أخيرًا، إذا كنت بحاجة إلى تقديم واجهة مستخدم متعددة الصفحات تتطلب إدخال المستخدم، ففكر في استخدام GuidedStepSupportFragment

إضافة OnboardingSupportFragment

لإضافة OnboardingSupportFragment في تطبيقك، وتنفيذ فئة تمتد للفئة OnboardingSupportFragment. إضافة هذا الجزء إلى نشاط، إما باستخدام تنسيق XML الخاص بتنسيق النشاط أو برمجيًا. تأكد من أن النشاط أو الجزء يستخدم موضوعًا مشتقًا من Theme_Leanback_Onboarding, كما هو موضَّح في قسم تخصيص المظاهر.

في طريقة onCreate() من النشاط الرئيسي للتطبيق، الاتصال startActivity() مع Intent الذي يشير إلى النشاط الرئيسي على "OnboardingSupportFragment" يساعد هذا في ضمان معرفة يظهر OnboardingSupportFragment كـ فور بدء تشغيل تطبيقك.

للمساعدة في ضمان يظهر OnboardingSupportFragment فقط عندما يبدأ المستخدم تشغيل تطبيقك لأول مرة، عنصر واحد (SharedPreferences) لتتبُّع ما إذا كان المستخدم قد شاهد OnboardingSupportFragment تعريف قيمة منطقية تتغيّر إلى "صحيح" عند انتهاء المستخدم من مشاهدة OnboardingSupportFragment التحقُّق من الإجابة لهذه القيمة في نشاط onCreate() وابدأ النشاط الوالدي OnboardingSupportFragment إذا تكون القيمة false.

يوضّح المثال التالي إلغاء onCreate() الذي يتحقّق من وجود قيمة SharedPreferences، وإذا لم يتم ضبطها على "صحيح"، ستطلب startActivity() لعرض OnboardingSupportFragment:

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))
        }
    }
}

@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 إلى صواب، كما هو موضح في المثال التالي:

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()
    }
}

@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. تمثّل هذه السمة عرض واجهة الصفحة، وهي في هذه الحالة شعار. تقدم طريقة العرض هذه دائمًا قبل كل طرق العرض الأخرى في الصفحة طريقة العرض هذه اختيارية.

قم بتهيئة معلومات الصفحة عندما تم إنشاء OnboardingSupportFragment لأول مرة أو مرفقًا بالنشاط الرئيسي، حيث إن صفحة طلبات النظام المعلومات عند إنشاء عرض الجزء. يمكنك تهيئة صفحة المعلومات الموجودة في الدالة الإنشائية للفئة أو في حالة تجاوز onAttach()

تجاهُل كل طريقة من الطرق التالية، والتي توفّر معلومات عن الصفحة إلى النظام:

• تعرض الدالة getPageCount() عدد الصفحات في OnboardingSupportFragment
• تعرض الدالة getPageTitle() العنوان لرقم الصفحة المطلوب.
• تعرض الدالة getPageDescription() وصف الصفحة المطلوبة الصف.

تجاهَل كل طريقة من الطرق التالية لتوفير مشاهدات فرعية اختيارية. لعرض الصور أو الرسوم المتحركة:

• onCreateBackgroundView() بإرجاع View إنشاؤه ليكون عرض الخلفية أو فارغًا إذا لم تكن هناك حاجة لعرض الخلفية.
• onCreateContentView() بإرجاع View إنشاؤه ليكون بمثابة عرض المحتوى أو فارغ إذا لم تكن هناك حاجة لعرض المحتوى.
• onCreateForegroundView() بإرجاع View إنشاء للعرض في المقدمة أو بقيمة فارغة إذا لم تكن هناك حاجة لعرض الواجهة الأمامية.

يضيف النظام View التي تنشئها إلى الصفحة. التصميم. يتجاهل المثال التالي onCreateContentView() وإرجاع ImageView:

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
    }
}

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 في onCreate() طريقة OnboardingSupportFragment. يتلاشى النظام ويعرض Drawable، ثم يتلاشى Drawable قبل عرض الصفحة الأولى من OnboardingSupportFragment.

إذا أردت توفير صورة متحركة مخصّصة لشاشة الشعار، بدلاً من الاتصال بـ setLogoResourceId()، إلغاء onCreateLogoAnimation() وإرجاع Animator كائنًا يعرض الحركة المخصّصة، كما هو موضّح في المثال التالي:

public override fun onCreateLogoAnimation(): Animator =
        AnimatorInflater.loadAnimator(context, R.animator.onboarding_logo_screen_animation)

@Override
public Animator onCreateLogoAnimation() {
    return AnimatorInflater.loadAnimator(getContext(),
            R.animator.onboarding_logo_screen_animation);
}

تخصيص الصور المتحركة في الصفحات

يستخدم النظام الرسوم المتحركة الافتراضية عند عرض الصفحة الأولى من OnboardingSupportFragment ووقت ظهور المستخدم إلى صفحة مختلفة. يمكنك تخصيص هذه الرسوم المتحركة من خلال إلغاء الطرق في OnboardingSupportFragment

لتخصيص الرسوم المتحركة التي تظهر في صفحتك الأولى، إلغاء onCreateEnterAnimation() وإرجاع Animator. ينشئ المثال التالي Animator يضبط حجم مشاهدة المحتوى. أفقيًا:

override fun onCreateEnterAnimation(): Animator =
    ObjectAnimator.ofFloat(contentView, View.SCALE_X, 0.2f, 1.0f)
            .setDuration(ANIMATION_DURATION)

@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، وتشغيل المجموعة. ما يلي: مثال يستخدم رسمًا متحركًا يتلاشى لإزالة الصفحة السابقة، ويحدِّث صورة لعرض المحتوى، واستخدام رسم متحرك يتلاشى لعرض الصفحة التالية:

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()
    }
}

@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;
  }