Добавить пошаговый инструкции

Создавайте более эффективные проекты с помощью Compose.
Создавайте красивые пользовательские интерфейсы с минимальным количеством кода, используя Jetpack Compose для Android TV OS.
Композиторство для телевидения →

В вашем приложении могут быть многоэтапные задачи для пользователей. Например, приложение может нуждаться в том, чтобы помочь пользователям приобрести дополнительный контент, настроить сложные параметры конфигурации или подтвердить принятое решение. Все эти задачи требуют от пользователей прохождения одного или нескольких последовательных шагов или принятия решений.

Устаревшая библиотека androidx.leanback предоставляет классы для реализации многошаговых задач пользователя. На этой странице обсуждается, как использовать класс GuidedStepSupportFragment GuidedStepSupportFragment чтобы направлять пользователя через ряд решений для выполнения задачи.

Предоставьте подробную информацию о шаге.

Компонент GuidedStepSupportFragment представляет собой отдельный шаг в серии шагов. Визуально он предоставляет пошаговое руководство со списком возможных действий или решений для данного шага.

Рисунок 1. Пример пошагового руководства.

Для каждого шага в вашей многошаговой задаче расширьте класс 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)
    )
}

Java 

@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 в нужную активность, вызвав метод GuidedStepSupportFragment.add() в методе onCreate() вашей активности.

Если ваше Activity содержит только объекты GuidedStepSupportFragment , используйте GuidedStepSupportFragment.addAsRoot() вместо add() для добавления первого GuidedStepSupportFragment . Использование addAsRoot() гарантирует, что если пользователь нажмет кнопку «Назад» на пульте телевизора во время просмотра первого GuidedStepSupportFragment , то закроются как GuidedStepSupportFragment так и родительское Activity.

Примечание: Добавляйте объекты GuidedStepSupportFragment программным способом, а не в XML-файлы разметки.

Создание и обработка действий пользователя

Добавьте действия пользователя, переопределив onCreateActions() . В переопределенном методе добавьте новый GuidedAction для каждого элемента действия и укажите строку действия, описание и ID. Используйте 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())
    ...

Java 

@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() с общим значением ID для группировки действий в набор. Все действия в одном списке с одинаковым ID набора считаются связанными. Когда пользователь выбирает одно из действий в этом наборе, это действие становится отмеченным, а все остальные действия — снятыми с отметки.
  • Добавьте действие выбора даты, используя GuidedDatePickerAction.Builder вместо GuidedAction.Builder в onCreateActions() . Переопределите onGuidedActionEditedAndProceed() , чтобы получить значение измененной даты, введенное пользователем.
  • Добавьте действие, использующее поддействия, чтобы пользователь мог выбирать из расширенного списка вариантов. Поддействия описаны в разделе «Добавление поддействий» .
  • Добавьте действие кнопки, которое будет отображаться справа от списка действий и будет легкодоступным. Действия кнопок описаны в разделе «Добавление действий кнопок» .

Также можно добавить визуальный индикатор, указывающий на то, что выбор действия приводит к новому шагу, установив параметр hasNext(true) .

Для получения информации обо всех различных параметрах, которые вы можете задать, см. GuidedAction .

Для обработки действий переопределите метод onGuidedActionClicked() и обработайте переданное значение GuidedAction . Определите выбранное действие, изучив GuidedAction.getId() .

Добавить поддействия

Для некоторых действий может потребоваться предоставить пользователю дополнительный набор вариантов выбора. В GuidedAction можно указать список поддействий, которые отображаются в виде меню дочерних действий.

Рисунок 2. Пошаговые действия с пошаговым управлением.

Список поддействий может содержать обычные действия или действия с переключателями, но не действия выбора даты или действия с редактируемым текстом. Кроме того, поддействие не может иметь собственный набор поддействий, поскольку система не поддерживает более одного уровня поддействий.

Для добавления поддействий сначала создайте и заполните список объектов GuidedAction , которые будут выступать в качестве поддействий, как показано в следующем примере:

Котлин 

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

Java 

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

Java 

@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());
...
}

Наконец, для обработки выбора поддействий переопределите 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
}

Java 

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

Добавить действия кнопки

Если ваш пошаговый алгоритм содержит большой список действий, пользователям, возможно, придётся прокручивать его, чтобы получить доступ к наиболее часто используемым действиям. Используйте кнопки, чтобы отделить часто используемые действия от списка действий. Кнопки отображаются рядом со списком действий, и к ним легко перейти.

Рисунок 3. Действия кнопок в режиме пошагового выполнения.

Действия кнопок создаются и обрабатываются так же, как и обычные действия, но вы создаете действия кнопок в onCreateButtonActions() а не в onCreateActions() . Реагируйте на действия кнопок в onGuidedActionClicked() .

Используйте действия кнопок для простых действий, таких как навигация между шагами. Не используйте действие выбора даты или другие редактируемые действия в качестве действий кнопок. Кроме того, действия кнопок не могут иметь поддействия.

Сгруппируйте шаги, выполняемые по инструкции, в последовательность действий.

Объект GuidedStepSupportFragment представляет собой отдельный шаг. Для создания упорядоченной последовательности шагов сгруппируйте несколько объектов GuidedStepSupportFragment вместе, используя GuidedStepSupportFragment.add() чтобы добавить следующий шаг в последовательности в стек фрагментов.

Котлин 

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

Java 

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

Если пользователь нажимает кнопку «Назад» на пульте телевизора, устройство отображает предыдущий фрагмент GuidedStepSupportFragment в стеке фрагментов. Если вы предоставляете собственное GuidedAction , возвращающее к предыдущему шагу, вы можете реализовать поведение «Назад», вызвав getFragmentManager().popBackStack() . Если вам нужно вернуть пользователя к еще более раннему шагу в последовательности, используйте popBackStackToGuidedStepSupportFragment() для возврата к определенному фрагменту GuidedStepSupportFragment в стеке фрагментов.

Когда пользователь завершит последний шаг в последовательности, используйте finishGuidedStepSupportFragments() , чтобы удалить все экземпляры GuidedStepSupportFragment из текущего стека и вернуться к исходной родительской активности. Если первый GuidedStepSupportFragment добавлен с помощью addAsRoot() , вызов finishGuidedStepSupportFragments() также закроет родительскую активность.

Настройка пошаговой презентации

Класс GuidedStepSupportFragment может использовать пользовательские темы, которые управляют такими аспектами представления, как форматирование текста заголовка или анимация перехода между шагами. Пользовательские темы должны наследовать от Theme_Leanback_GuidedStep и могут предоставлять переопределяющие значения для атрибутов, определенных в GuidanceStylist и GuidedActionsStylist .

Чтобы применить пользовательскую тему к вашему GuidedStepSupportFragment , выполните одно из следующих действий:

  • Примените тему к родительской активности, установив атрибут android:theme для элемента activity в манифесте Android. Установка этого атрибута применяет тему ко всем дочерним представлениям и является наиболее простым способом применения пользовательской темы, если родительская активность содержит только объекты GuidedStepSupportFragment .
  • Если ваша активность уже использует пользовательскую тему оформления, и вы не хотите применять стили GuidedStepSupportFragment к другим представлениям в активности, добавьте атрибут LeanbackGuidedStepTheme_guidedStepTheme к существующей пользовательской теме оформления вашей активности. Этот атрибут указывает на пользовательскую тему, которую используют только объекты GuidedStepSupportFragment в вашей активности.
  • Если вы используете объекты GuidedStepSupportFragment в разных действиях, являющихся частью одной и той же многошаговой задачи, и хотите использовать единую визуальную тему для всех шагов, переопределите GuidedStepSupportFragment.onProvideTheme() и верните свою пользовательскую тему.

Для получения дополнительной информации о добавлении стилей и тем см. раздел «Стили и темы» .

Класс GuidedStepSupportFragment использует специальные классы стилистов для доступа к атрибутам темы и их применения. Класс GuidanceStylist использует информацию о теме для управления отображением левого окна подсказок, а класс GuidedActionsStylist использует информацию о теме для управления отображением правого окна действий.

Чтобы настроить визуальный стиль ваших шагов сверх возможностей настройки темы, создайте подкласс GuidanceStylist или GuidedActionsStylist и верните свой подкласс в GuidedStepSupportFragment.onCreateGuidanceStylist() или GuidedStepSupportFragment.onCreateActionsStylist() . Подробную информацию о том, что можно настроить в этих подклассах, см. в документации по GuidanceStylist и GuidedActionsStylist .

Назад
Познакомьте новых пользователей с вашим приложением
Далее
Режим окружающей среды