Создать ярлык

Ярлыки позволяют пользователям быстро переходить к определенным разделам приложения.

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

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

Как создать статические ярлыки

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

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

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

2. Добавьте в этот объект activity элемент <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>
   

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

4. В новом файле ресурсов добавьте корневой элемент <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>
   shortcuts.xml

Как настроить значения атрибутов

Ниже приведены описания различных атрибутов статического ярлыка. Укажите значения для атрибутов "дата начала" 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, встроенного намерения действий в приложении. Эта привязка позволяет пользователям вызывать ярлыки с помощью голосовых команд, отдаваемых Google Ассистенту.

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

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

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

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

• Отправить и обновить. Используйте pushDynamicShortcut(), чтобы опубликовать и обновить динамические ярлыки. Если уже есть динамические или закрепленные быстрые действия с тем же идентификатором, каждое изменяемое быстрое действие обновляется.
• Удалить: удалить набор динамических ярлыков с помощью команды 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)
ShortcutsSnippets.kt

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

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

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

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

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

Чтобы использовать эту библиотеку в приложении, добавьте зависимости для библиотеки интеграции быстрых действий Google и ShortcutManagerCompat в файл app/build.gradle или app/build.gradle.kts:

dependencies {
    implementation("androidx.core:core:1.6.0")
    implementation("androidx.core:core-google-shortcuts:1.0.0")
}

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 показаны различия между этими двумя типами ярлыков.

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

1. Используйте isRequestPinShortcutSupported(), чтобы проверить, поддерживает ли панель запуска по умолчанию закрепление ярлыков в приложении.

2. Создайте объект ShortcutInfoCompat, содержащий идентификатор, намерение и краткую метку для ярлыка. Если ярлык существует, используйте его идентификатор. Система автоматически находит и закрепляет всю остальную информацию, связанную с ярлыком.

3. Закрепите ярлык в панели запуска устройства, вызвав метод requestPinShortcut(). В процессе можно передать объект PendingIntent, который будет уведомлять приложение только в случае успешного закрепления ярлыка.

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

В следующем фрагменте кода показано, как создать закрепленное сочетание клавиш:

if (ShortcutManagerCompat.isRequestPinShortcutSupported(context)) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfoCompat.Builder(context, "my-shortcut")
        .setShortLabel("Website")
        .setIntent(
            Intent(
                Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")
            )
        )
        .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 =
        ShortcutManagerCompat.createShortcutResultIntent(context, 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 */ PendingIntent.FLAG_IMMUTABLE
    )

    ShortcutManagerCompat.requestPinShortcut(
        context,
        pinShortcutInfo,
        successCallback.intentSender
    )
}
ShortcutsSnippets.kt

Как создать активность для быстрой команды

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

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

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

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

Как проверить сочетания клавиш

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

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