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

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

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

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 إلا إذا كانت القيمة "خطأ".

يعرض المثال التالي عملية إلغاء لطريقة 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 تنشئها لتعمل كطريقة عرض الخلفية أو null إذا لم تكن هناك حاجة إلى طريقة عرض الخلفية
• onCreateContentView() لعرض View تنشئها لتعمل كطريقة عرض المحتوى أو null إذا لم تكن هناك حاجة إلى طريقة عرض المحتوى
• onCreateForegroundView() لعرض View تنشئها لتعمل كطريقة عرض مقدّمة الصفحة أو null إذا لم تكن هناك حاجة إلى طريقة عرض مقدّمة الصفحة

يضيف النظام 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;
  }