Эта страница переведена с помощью Cloud Translation API.

Создание ярлыков

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

Разница между ярлыками приложений и закрепленными ярлыками. — **Рисунок 1.** Ярлыки приложений и закрепленные ярлыки.

Способ доставки контента с помощью ярлыков зависит от конкретного сценария использования и от того, определяется ли контекст ярлыка приложением или пользователем. Хотя контекст статического ярлыка не меняется, а контекст динамического ярлыка постоянно меняется, в обоих случаях контекст определяется вашим приложением. В случаях, когда пользователь выбирает способ доставки контента вашим приложением, например, с помощью закрепленного ярлыка, контекст определяется пользователем. Следующие сценарии описывают несколько вариантов использования для каждого типа ярлыков:

Статические ярлыки лучше всего подходят для приложений, которые используют согласованную структуру ссылок на контент на протяжении всего времени взаимодействия пользователя с приложением. Поскольку большинство лаунчеров отображают одновременно только четыре ярлыка , статические ярлыки полезны для выполнения рутинных задач согласованным образом, например, если пользователь хочет просмотреть свой календарь или электронную почту определенным образом.
Динамические сочетания клавиш используются для действий в контекстно-зависимых приложениях. Контекстно-зависимые сочетания клавиш адаптированы к действиям, которые пользователь выполняет в приложении. Например, если вы создаете игру, которая позволяет пользователю начать с текущего уровня при запуске, вам необходимо часто обновлять сочетание клавиш. Использование динамического сочетания клавиш позволяет обновлять его каждый раз, когда пользователь проходит уровень.
Закрепленные ярлыки используются для выполнения определенных действий, инициированных пользователем. Например, пользователь может захотеть закрепить определенный веб-сайт на панели быстрого доступа. Это удобно, поскольку позволяет пользователю выполнять пользовательское действие — например, переходить на веб-сайт за один шаг, быстрее, чем при использовании стандартного экземпляра браузера.

Создание статических ярлыков

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

Для создания статического ярлыка выполните следующие действия:

В файле AndroidManifest.xml вашего приложения найдите активность, для которой установлены фильтры намерений: android.intent.action.MAIN action и android.intent.category.LAUNCHER category.

Добавьте в это действие элемент <meta-data> , который будет ссылаться на файл ресурсов, где определены сочетания клавиш приложения:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.myapplication">
  <application ... >
    <activity android:name="Main">
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
      <meta-data android:name="android.app.shortcuts"
                 android:resource="@xml/shortcuts" />
    </activity>
  </application>
</manifest>

Создайте новый файл ресурсов с именем res/xml/shortcuts.xml .

В новом файле ресурсов добавьте корневой элемент <shortcuts> , содержащий список элементов <shortcut> . В каждом элементе <shortcut> укажите информацию о статическом ярлыке, включая его значок, описание и интенты, которые он запускает в приложении:

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <shortcut
    android:shortcutId="compose"
    android:enabled="true"
    android:icon="@drawable/compose_icon"
    android:shortcutShortLabel="@string/compose_shortcut_short_label1"
    android:shortcutLongLabel="@string/compose_shortcut_long_label1"
    android:shortcutDisabledMessage="@string/compose_disabled_message1">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapplication"
      android:targetClass="com.example.myapplication.Main" />
    <!-- If your shortcut is associated with multiple intents, include them
         here. The last intent in the list determines what the user sees when
         they launch this shortcut. -->
    <categories android:name="android.shortcut.conversation" />
    <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
  </shortcut>
  <!-- Specify more shortcuts here. -->
</shortcuts>

Настройка значений атрибутов

Ниже приведен список описаний различных атрибутов статического ярлыка. Укажите значения для android:shortcutId и android:shortcutShortLabel . Все остальные значения являются необязательными.

android:shortcutId

Строковый литерал, представляющий собой сочетание клавиш, которое объект ShortcutManager обрабатывает при выполнении над ним операций.

android:shortcutShortLabel

Краткая фраза, описывающая назначение сочетания клавиш. По возможности ограничьте это краткое описание 10 символами.

Для получения более подробной информации см. setShortLabel() .

android:shortcutLongLabel

Расширенное описание назначения ярлыка. Если места достаточно, лаунчер отобразит это значение вместо android:shortcutShortLabel . По возможности ограничьте это длинное описание 25 символами.

Для получения более подробной информации см. setLongLabel() .

android:shortcutDisabledMessage

Сообщение, которое появляется в поддерживаемом лаунчере, когда пользователь пытается запустить отключенный ярлык. Сообщение должно объяснять пользователю, почему ярлык отключен. Значение этого атрибута не имеет эффекта, если android:enabled равно true .

android:enabled

Определяет, может ли пользователь взаимодействовать с ярлыком из поддерживаемого средства запуска. Значение по умолчанию для android:enabled — true . Если вы установите его в false , запустите сообщение android:shortcutDisabledMessage , объясняющее причину отключения ярлыка. Если вы считаете, что такое сообщение не требуется, полностью удалите ярлык из XML-файла.

android:icon

Растровое изображение или адаптивная иконка , которую использует средство запуска при отображении ярлыка пользователю. Это значение может быть путем к изображению или файлом ресурсов, содержащим изображение. Используйте адаптивные иконки везде, где это возможно, для повышения производительности и согласованности.

Настройка внутренних элементов

XML-файл, содержащий список статических ярлыков приложения, поддерживает следующие элементы внутри каждого элемента <shortcut> . Для каждого определенного статического ярлыка необходимо включить внутренний элемент intent .

intent

Действие, которое система запускает при выборе пользователем ярлыка. Этот интент должен содержать значение для атрибута android:action .

Для одного ярлыка можно указать несколько намерений. Подробности см. в разделах «Управление несколькими намерениями и действиями» , «Задача намерения» и справочнике по классу TaskStackBuilder .

categories

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

Список поддерживаемых категорий ярлыков см. в справочнике по классу ShortcutInfo .

capability-binding

Указывает на возможности, связанные с этим сочетанием клавиш.

В предыдущем примере ярлык связан с возможностью, объявленной для CREATE_MESSAGE , которая является встроенным намерением App Actions . Эта привязка возможности позволяет пользователям использовать голосовые команды с Google Assistant для вызова ярлыка.

Создавайте динамические ярлыки

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

Библиотека ShortcutManagerCompat от Jetpack — это вспомогательный инструмент для API ShortcutManager , позволяющий управлять динамическими ярлыками в вашем приложении. Использование библиотеки ShortcutManagerCompat сокращает количество шаблонного кода и помогает обеспечить согласованную работу ваших ярлыков во всех версиях Android. Эта библиотека также необходима для отображения динамических ярлыков на устройствах Google, таких как Google Assistant, с помощью библиотеки интеграции Google Shortcuts .

API ShortcutManagerCompat позволяет вашему приложению выполнять следующие операции с динамическими сочетаниями клавиш:

Публикация и обновление: используйте pushDynamicShortcut() для публикации и обновления динамических ярлыков. Если уже существуют динамические или закрепленные ярлыки с тем же ID, каждый изменяемый ярлык будет обновлен.
Удаление: удалить набор динамических сочетаний клавиш с помощью removeDynamicShortcuts() . Удалить все динамические сочетания клавиш с помощью removeAllDynamicShortcuts() .

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

Вот пример создания динамического ярлыка и его привязки к вашему приложению:

val shortcut = ShortcutInfoCompat.Builder(context, "id1")
        .setShortLabel("Website")
        .setLongLabel("Open the website")
        .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
        .setIntent(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")))
        .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

Добавьте библиотеку интеграции Google Shortcuts.

Библиотека интеграции Google Shortcuts — это дополнительная библиотека Jetpack. Она позволяет добавлять динамические ярлыки, которые могут отображаться на устройствах Android, таких как лаунчер, и на устройствах Google. Использование этой библиотеки помогает пользователям быстро находить ваши ярлыки для доступа к определенному контенту или воспроизведения действий в вашем приложении.

Динамические ярлыки, создаваемые с помощью этой библиотеки, не подпадают под ограничения на количество ярлыков, применяемые к каждому устройству отдельно. Это позволяет вашему приложению создавать ярлык каждый раз, когда пользователь выполняет связанное с ним действие. Частое создание ярлыков таким образом позволяет Google понимать модели поведения пользователей и предлагать им контекстно релевантные ярлыки.

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

Библиотека интеграции Google Shortcuts сама по себе не предоставляет никаких адресуемых функций. Добавление этой библиотеки в ваше приложение позволит устройствам Google Surface получать ярлыки, которые ваше приложение отправляет с помощью ShortcutManagerCompat .

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

Обновите файл gradle.properties , чтобы он поддерживал библиотеки AndroidX :

android.useAndroidX=true
# Automatically convert third-party libraries to use AndroidX
android.enableJetifier=true

В app/build.gradle добавьте зависимости для библиотеки интеграции Google Shortcuts и ShortcutManagerCompat :
```
dependencies {
  implementation "androidx.core:core:1.6.0"
  implementation 'androidx.core:core-google-shortcuts:1.0.0'
  ...
}
```

После добавления зависимостей библиотеки в ваш проект Android, ваше приложение сможет использовать метод pushDynamicShortcut() из ShortcutManagerCompat для отображения динамических ярлыков, которые могут отображаться на панели запуска и на участвующих устройствах Google.

Создание закрепленных ярлыков

На Android 8.0 (уровень API 26) и выше можно создавать закрепленные ярлыки. В отличие от статических и динамических ярлыков, закрепленные ярлыки отображаются в поддерживаемых лаунчерах как отдельные значки. На рисунке 1 показано различие между этими двумя типами ярлыков.

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

Используйте функцию isRequestPinShortcutSupported() , чтобы убедиться, что стандартная программа запуска устройства поддерживает закрепление ярлыков внутри приложений.
Создать объект ShortcutInfo можно двумя способами, в зависимости от того, существует ли ярлык:
1. Если ярлык уже существует, создайте объект ShortcutInfo , содержащий только идентификатор существующего ярлыка. Система автоматически найдет и закрепит всю остальную информацию, связанную с ярлыком.
2. Если вы закрепляете новый ярлык, создайте объект ShortcutInfo , содержащий идентификатор, намерение и краткую метку для нового ярлыка.
Примечание: Поскольку система автоматически выполняет резервное копирование и восстановление закрепленных ярлыков, идентификаторы этих ярлыков должны содержать стабильные, постоянные строки или идентификаторы на стороне сервера, а не идентификаторы, сгенерированные локально, которые могут быть неактуальны на других устройствах.
Закрепите ярлык на панели запуска устройства, вызвав requestPinShortcut() . В процессе можно передать объект PendingIntent , который уведомит ваше приложение только после успешного закрепления ярлыка.
Примечание: Если пользователь не закрепит ярлык на панели запуска, ваше приложение не получит обратный вызов.
После закрепления ярлыка ваше приложение может обновлять его содержимое с помощью метода updateShortcuts() . Для получения дополнительной информации см. раздел «Обновление ярлыков» .

Приведённый ниже фрагмент кода демонстрирует, как создать закреплённый ярлык.

val shortcutManager = getSystemService<ShortcutManager>()

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

Создайте пользовательское действие быстрого доступа

Настраиваемое диалоговое окно, отображающее запрос «Хотите добавить значок запуска Gmail на главный экран?». Настраиваемые варианты: «Нет, спасибо» и «Добавить значок». — **Рисунок 2.** Пример диалогового окна для создания пользовательского ярлыка приложения.

Также можно создать специализированное действие, которое поможет пользователям создавать ярлыки с настраиваемыми параметрами и кнопкой подтверждения. На рисунке 2 показан пример такого действия в приложении Gmail.

В файл манифеста вашего приложения добавьте ACTION_CREATE_SHORTCUT к элементу <intent-filter> активности. Это объявление настраивает следующее поведение, когда пользователь пытается создать ярлык:

Система запускает специализированную активность вашего приложения.
Пользователь задает параметры для ярлыка.
Пользователь нажимает кнопку подтверждения.
Ваше приложение создает ярлык с помощью метода createShortcutResultIntent() . Этот метод возвращает Intent , который ваше приложение передает обратно в ранее выполнявшуюся активность с помощью setResult() .
Ваше приложение вызывает finish() для активности, использованной для создания пользовательского ярлыка.

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

Тестовые сочетания клавиш

Чтобы проверить работу ярлыков вашего приложения, установите его на устройство с лаунчером, поддерживающим ярлыки. Затем выполните следующие действия:

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

О ярлыках

Добавьте возможности к ярлыкам