یک مرحله هدایت شده اضافه کنید

با Compose بهتر بسازید

با استفاده از Jetpack Compose برای سیستم عامل Android TV، رابط‌های کاربری زیبایی با حداقل کد ایجاد کنید.

آهنگسازی برای تلویزیون →

هشدار: کتابخانه Leanback منسوخ شده است. به جای آن از Jetpack Compose برای سیستم عامل Android TV استفاده کنید.

ممکن است برنامه شما وظایف چند مرحله‌ای برای کاربران داشته باشد. برای مثال، ممکن است برنامه شما نیاز داشته باشد کاربران را در خرید محتوای اضافی، تنظیم یک تنظیمات پیکربندی پیچیده یا تأیید یک تصمیم راهنمایی کند. همه این وظایف نیاز به راهنمایی کاربران در یک یا چند مرحله یا تصمیم مرتب دارند.

کتابخانه منسوخ‌شده androidx.leanback کلاس‌هایی را برای پیاده‌سازی وظایف چند مرحله‌ای کاربر ارائه می‌دهد. این صفحه نحوه استفاده از کلاس GuidedStepSupportFragment را برای راهنمایی کاربر در طی مجموعه‌ای از تصمیمات برای انجام یک کار با استفاده از GuidedStepSupportFragment مورد بحث قرار می‌دهد.

ارائه جزئیات برای یک مرحله

یک GuidedStepSupportFragment یک مرحله از یک سری مراحل را نشان می‌دهد. از نظر بصری، یک نمای راهنما با لیستی از اقدامات یا تصمیمات ممکن برای آن مرحله ارائه می‌دهد.

شکل ۱. یک نمونه گام هدایت‌شده.

برای هر مرحله در وظیفه چند مرحله‌ای خود، GuidedStepSupportFragment بسط دهید و اطلاعات زمینه‌ای در مورد مرحله و اقداماتی که کاربر می‌تواند انجام دهد، ارائه دهید. تابع onCreateGuidance() را بازنویسی کنید و یک GuidanceStylist.Guidance جدید را که شامل اطلاعات زمینه‌ای، مانند عنوان مرحله، توضیحات و آیکون است، همانطور که در مثال زیر نشان داده شده است، برگردانید:

کاتلین

override fun onCreateGuidance(savedInstanceState: Bundle?): GuidanceStylist.Guidance {
    return GuidanceStylist.Guidance(
            getString(R.string.guidedstep_first_title),
            getString(R.string.guidedstep_first_description),
            getString(R.string.guidedstep_first_breadcrumb),
            activity.getDrawable(R.drawable.guidedstep_main_icon_1)
    )
}

جاوا

@Override
public GuidanceStylist.Guidance onCreateGuidance(Bundle savedInstanceState) {
    String title = getString(R.string.guidedstep_first_title);
    String breadcrumb = getString(R.string.guidedstep_first_breadcrumb);
    String description = getString(R.string.guidedstep_first_description);
    Drawable icon = getActivity().getDrawable(R.drawable.guidedstep_main_icon_1);
    return new GuidanceStylist.Guidance(title, description, breadcrumb, icon);
}

با فراخوانی GuidedStepSupportFragment.add() در متد onCreate() مربوط به activity خود، زیرکلاس GuidedStepSupportFragment خود را به activity مورد نظر خود اضافه کنید.

اگر activity شما فقط شامل اشیاء GuidedStepSupportFragment است، به جای add() از GuidedStepSupportFragment.addAsRoot() ) برای اضافه کردن اولین GuidedStepSupportFragment استفاده کنید. استفاده از addAsRoot() تضمین می‌کند که اگر کاربر هنگام مشاهده اولین GuidedStepSupportFragment دکمه Back را روی کنترل تلویزیون فشار دهد، هم GuidedStepSupportFragment و هم activity والد بسته شوند.

نکته: اشیاء GuidedStepSupportFragment را به صورت برنامه‌نویسی اضافه کنید، نه در فایل‌های XML طرح‌بندی خود.

ایجاد و مدیریت اقدامات کاربر

با بازنویسی (override onCreateActions() ، اقدامات کاربر را اضافه کنید. در بازنویسی خود، برای هر مورد اقدام، یک GuidedAction جدید اضافه کنید و رشته اقدام، توضیحات و شناسه آن را ارائه دهید. GuidedAction.Builder برای افزودن اقدامات جدید استفاده کنید.

کاتلین

override fun onCreateActions(actions: MutableList<GuidedAction>, savedInstanceState: Bundle?) {
    super.onCreateActions(actions, savedInstanceState)

    // Add "Continue" user action for this step
    actions.add(GuidedAction.Builder()
            .id(CONTINUE)
            .title(getString(R.string.guidedstep_continue))
            .description(getString(R.string.guidedstep_letsdoit))
            .hasNext(true)
            .build())
    ...

جاوا

@Override
public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {
    // Add "Continue" user action for this step
    actions.add(new GuidedAction.Builder()
           .id(CONTINUE)
           .title(getString(R.string.guidedstep_continue))
           .description(getString(R.string.guidedstep_letsdoit))
           .hasNext(true)
           .build());
...

اکشن‌ها محدود به انتخاب‌های تک‌خطی نیستند. در اینجا انواع دیگری از اکشن‌ها را که می‌توانید ایجاد کنید، آورده‌ایم:

• با تنظیم infoOnly(true) یک اکشن برچسب اطلاعات اضافه کنید تا اطلاعات بیشتری در مورد انتخاب‌های کاربر ارائه دهد. وقتی infoOnly روی true تنظیم شده باشد، کاربران نمی‌توانند اکشن را انتخاب کنند.
• با تنظیم editable(true) یک اکشن متن قابل ویرایش اضافه کنید. وقتی editable روی true باشد، کاربر می‌تواند با استفاده از ریموت یا صفحه‌کلید متصل، متن را در یک اکشن انتخاب شده وارد کند. برای دریافت متن اصلاح‌شده‌ای که کاربر وارد کرده است، onGuidedActionEditedAndProceed() را نادیده بگیرید. همچنین می‌توانید onGuidedActionEditCanceled() را نادیده بگیرید تا بدانید کاربر چه زمانی ورودی را لغو می‌کند.
• با استفاده از checkSetId() و یک مقدار شناسه مشترک، مجموعه‌ای از اکشن‌ها را که مانند دکمه‌های رادیویی قابل تیک خوردن رفتار می‌کنند، اضافه کنید تا اکشن‌ها را در یک مجموعه گروه‌بندی کنید. همه اکشن‌های موجود در یک لیست با شناسه مجموعه چک یکسان، مرتبط در نظر گرفته می‌شوند. وقتی کاربر یکی از اکشن‌های درون آن مجموعه را انتخاب می‌کند، آن اکشن تیک می‌خورد و همه اکشن‌های دیگر تیک نمی‌خورند.
• با استفاده از GuidedDatePickerAction.Builder به جای GuidedAction.Builder در onCreateActions() ، یک اکشن انتخاب تاریخ (date-picker) اضافه کنید. تابع onGuidedActionEditedAndProceed() را برای دریافت مقدار تاریخ اصلاح‌شده‌ای که کاربر وارد کرده است، بازنویسی کنید.
• عملی اضافه کنید که با استفاده از زیرعملیات‌ها به کاربر اجازه دهد از میان فهرست گسترده‌ای از گزینه‌ها انتخاب کند. زیرعملیات‌ها در بخش افزودن زیرعملیات توضیح داده شده‌اند.
• یک دکمه‌ی عملیاتی اضافه کنید که در سمت راست لیست عملیات ظاهر شود و به راحتی قابل دسترسی باشد. عملیات‌های دکمه در بخش «افزودن عملیات دکمه» توضیح داده شده‌اند.

همچنین می‌توانید با تنظیم hasNext(true) یک نشانگر بصری اضافه کنید که انتخاب یک عمل منجر به یک مرحله جدید می‌شود.

برای مشاهده‌ی تمام ویژگی‌های مختلفی که می‌توانید تنظیم کنید، به GuidedAction مراجعه کنید.

برای پاسخ به اقدامات، متد onGuidedActionClicked() را بازنویسی کرده و GuidedAction ارسالی را پردازش کنید. با بررسی GuidedAction.getId() اقدام انتخاب شده را شناسایی کنید.

اضافه کردن زیرعملیات‌ها

برخی از اقدامات ممکن است از شما بخواهند که به کاربر مجموعه‌ای از انتخاب‌های اضافی بدهید. یک GuidedAction می‌تواند لیستی از زیرعملیات‌ها را مشخص کند که به عنوان منویی از اقدامات فرزند نمایش داده می‌شوند.

شکل ۲. زیرفعالیت‌های مرحله‌ای هدایت‌شده.

لیست زیرکنش‌ها می‌تواند شامل اکشن‌های معمولی یا اکشن‌های دکمه رادیویی باشد، اما اکشن‌های انتخاب تاریخ یا متن قابل ویرایش را شامل نمی‌شود. همچنین، یک زیرکنش نمی‌تواند مجموعه‌ای از زیرکنش‌های مخصوص به خود را داشته باشد، زیرا سیستم بیش از یک سطح از زیرکنش‌ها را پشتیبانی نمی‌کند.

برای افزودن زیرعملیات، ابتدا لیستی از اشیاء GuidedAction که به عنوان زیرعملیات عمل می‌کنند را ایجاد و پر کنید، همانطور که در مثال زیر نشان داده شده است:

کاتلین

subActions.add(GuidedAction.Builder()
        .id(SUBACTION1)
        .title(getString(R.string.guidedstep_subaction1_title))
        .description(getString(R.string.guidedstep_subaction1_desc))
        .build())
...

جاوا

List<GuidedAction> subActions = new ArrayList<GuidedAction>();
subActions.add(new GuidedAction.Builder()
       .id(SUBACTION1)
       .title(getString(R.string.guidedstep_subaction1_title))
       .description(getString(R.string.guidedstep_subaction1_desc))
       .build());
...

در onCreateActions() ، یک GuidedAction سطح بالا ایجاد کنید که لیست زیرعملیات‌ها را هنگام انتخاب نمایش دهد:

کاتلین

    ...
    actions.add(GuidedAction.Builder()
            .id(SUBACTIONS)
            .title(getString(R.string.guidedstep_subactions_title))
            .description(getString(R.string.guidedstep_subactions_desc))
            .subActions(subActions)
            .build())
    ...

جاوا

@Override
public void onCreateActions(List<GuidedAction> actions, Bundle savedInstanceState) {
...
    actions.add(new GuidedAction.Builder()
           .id(SUBACTIONS)
           .title(getString(R.string.guidedstep_subactions_title))
           .description(getString(R.string.guidedstep_subactions_desc))
           .subActions(subActions)
           .build());
...
}

در نهایت، با بازنویسی (override) متد onSubGuidedActionClicked() به انتخاب‌های زیرعملیات پاسخ دهید:

کاتلین

override fun onSubGuidedActionClicked(action: GuidedAction): Boolean {
    // Check for which action was clicked and handle as needed
    when(action.id) {
        SUBACTION1 -> {
            // Subaction 1 selected
        }
    }
    // Return true to collapse the subactions menu or
    // false to keep the menu expanded
    return true
}

جاوا

@Override
public boolean onSubGuidedActionClicked(GuidedAction action) {
   // Check for which action was clicked and handle as needed
   if (action.getId() == SUBACTION1) {
       // Subaction 1 selected
   }
   // Return true to collapse the subactions menu or
   // false to keep the menu expanded
   return true;
}

اضافه کردن اکشن‌های دکمه

اگر مرحله هدایت‌شده شما شامل فهرست بزرگی از اقدامات است، ممکن است کاربران مجبور شوند برای دسترسی به اقدامات پرکاربرد، در فهرست پیمایش کنند. از اقدامات دکمه‌ای برای جدا کردن اقدامات پرکاربرد از فهرست اقدامات استفاده کنید. اقدامات دکمه‌ای در کنار فهرست اقدامات ظاهر می‌شوند و پیمایش آنها آسان است.

شکل ۳. عملکردهای دکمه گام هدایت‌شده.

اکشن‌های دکمه درست مانند اکشن‌های معمولی ایجاد و مدیریت می‌شوند، اما شما اکشن‌های دکمه را به جای onCreateActions onCreateButtonActions() onCreateActions() ایجاد می‌کنید. به اکشن‌های دکمه در onGuidedActionClicked() پاسخ دهید.

از اکشن‌های دکمه برای اکشن‌های ساده، مانند اکشن‌های ناوبری بین مراحل، استفاده کنید. از اکشن انتخاب تاریخ یا سایر اکشن‌های قابل ویرایش به عنوان اکشن‌های دکمه استفاده نکنید. همچنین، اکشن‌های دکمه نمی‌توانند زیر اکشن داشته باشند.

مراحل هدایت‌شده را در یک توالی هدایت‌شده گروه‌بندی کنید

یک GuidedStepSupportFragment نشان دهنده یک مرحله است. برای ایجاد یک توالی مرتب از مراحل، چندین شیء GuidedStepSupportFragment را با استفاده از GuidedStepSupportFragment.add() با هم گروه بندی کنید تا مرحله بعدی در دنباله به پشته قطعه اضافه شود.

کاتلین

override fun onGuidedActionClicked(action: GuidedAction) {
    val fm = fragmentManager
    when(action.id) {
        CONTINUE -> GuidedStepSupportFragment.add(fm, SecondStepFragment())
    }
}

جاوا

@Override
public void onGuidedActionClicked(GuidedAction action) {
    FragmentManager fm = getFragmentManager();
    if (action.getId() == CONTINUE) {
       GuidedStepSupportFragment.add(fm, new SecondStepFragment());
    }
...

اگر کاربر دکمه‌ی Back روی کنترل تلویزیون را فشار دهد، دستگاه GuidedStepSupportFragment قبلی را روی پشته‌ی قطعه نمایش می‌دهد. اگر GuidedAction خودتان را که به مرحله‌ی قبل برمی‌گردد، ارائه دهید، می‌توانید با فراخوانی getFragmentManager().popBackStack() رفتار Back را پیاده‌سازی کنید. اگر نیاز دارید که کاربر را به مرحله‌ی حتی قبل‌تری در این توالی برگردانید، از popBackStackToGuidedStepSupportFragment() برای بازگشت به یک GuidedStepSupportFragment خاص در پشته‌ی قطعه استفاده کنید.

وقتی کاربر آخرین مرحله را در دنباله به پایان رساند، از finishGuidedStepSupportFragments() برای حذف تمام نمونه‌های GuidedStepSupportFragment از پشته فعلی و بازگشت به اکتیویتی والد اصلی استفاده کنید. اگر اولین GuidedStepSupportFragment با استفاده از addAsRoot() اضافه شود، فراخوانی finishGuidedStepSupportFragments() نیز اکتیویتی والد را می‌بندد.

سفارشی سازی ارائه مرحله

کلاس GuidedStepSupportFragment می‌تواند از تم‌های سفارشی استفاده کند که جنبه‌های ارائه مانند قالب‌بندی متن عنوان یا انیمیشن‌های انتقال مرحله را کنترل می‌کنند. تم‌های سفارشی باید از Theme_Leanback_GuidedStep ارث‌بری کنند و می‌توانند مقادیر overriding را برای ویژگی‌های تعریف شده در GuidanceStylist و GuidedActionsStylist ارائه دهند.

برای اعمال یک تم سفارشی به GuidedStepSupportFragment خود، یکی از موارد زیر را انجام دهید:

• با تنظیم ویژگی android:theme به عنصر activity در مانیفست اندروید، تم را به activity والد اعمال کنید. تنظیم این ویژگی، تم را به تمام view های فرزند اعمال می‌کند و اگر activity والد فقط شامل اشیاء GuidedStepSupportFragment باشد، ساده‌ترین راه برای اعمال یک تم سفارشی است.
• اگر activity شما از قبل از یک تم سفارشی استفاده می‌کند و نمی‌خواهید استایل‌های GuidedStepSupportFragment را به سایر viewهای activity اعمال کنید، ویژگی LeanbackGuidedStepTheme_guidedStepTheme را به تم activity سفارشی موجود خود اضافه کنید. این ویژگی به تم سفارشی اشاره می‌کند که فقط اشیاء GuidedStepSupportFragment در activity شما از آن استفاده می‌کنند.
• اگر از اشیاء GuidedStepSupportFragment در فعالیت‌های مختلفی که بخشی از یک وظیفه چند مرحله‌ای کلی هستند استفاده می‌کنید و می‌خواهید از یک تم بصری ثابت در تمام مراحل استفاده کنید، GuidedStepSupportFragment.onProvideTheme() را بازنویسی کنید و تم سفارشی خود را برگردانید.

برای اطلاعات بیشتر در مورد نحوه اضافه کردن سبک‌ها و تم‌ها، به بخش سبک‌ها و تم‌ها مراجعه کنید.

کلاس GuidedStepSupportFragment از کلاس‌های استایلیست ویژه برای دسترسی و اعمال ویژگی‌های تم استفاده می‌کند. کلاس GuidanceStylist از اطلاعات تم برای کنترل نمایش نمای راهنمای سمت چپ استفاده می‌کند، در حالی که کلاس GuidedActionsStylist از اطلاعات تم برای کنترل نمایش نمای اکشن‌های سمت راست استفاده می‌کند.

برای سفارشی‌سازی سبک بصری مراحل خود، فراتر از آنچه سفارشی‌سازی قالب ارائه می‌دهد، GuidanceStylist یا GuidedActionsStylist زیرکلاس بسازید و زیرکلاس خود را در GuidedStepSupportFragment.onCreateGuidanceStylist() یا GuidedStepSupportFragment.onCreateActionsStylist() برگردانید. برای جزئیات بیشتر در مورد آنچه می‌توانید در این زیرکلاس‌ها سفارشی‌سازی کنید، به مستندات GuidanceStylist و GuidedActionsStylist مراجعه کنید.