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

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

Изображение, показывающее контраст между ярлыками приложений и закрепленными ярлыками.
Рисунок 1. Ярлыки приложений и закрепленные ярлыки.

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

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

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

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

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

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

  2. Добавьте в это действие элемент <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.ComposeActivity" />
      <!-- 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 .

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

  • Отправка и обновление: используйте 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)

Ява 

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

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);

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

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

Например, приложение для обмена сообщениями может использовать динамический ярлык для контакта с именем «Алекс» после того, как пользователь отправит этому человеку сообщение. Если после нажатия динамического ярлыка пользователь спрашивает Ассистента: «Эй, Google, отправь сообщение Алексу в примере приложения», Ассистент может запустить приложение Примера и автоматически настроить его для отправки сообщения Алексу.

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

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

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

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

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

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

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

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

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

  2. Создайте объект ShortcutInfo одним из двух способов, в зависимости от того, существует ли ярлык:

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

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

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

В следующем фрагменте кода показано, как создать закрепленный ярлык.

Котлин 

val shortcutManager = getSystemService(ShortcutManager::class.java)

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)
}

Ява 

ShortcutManager shortcutManager =
        context.getSystemService(ShortcutManager.class);

if (shortcutManager.isRequestPinShortcutSupported()) {
    // Enable the existing shortcut with the ID "my-shortcut".
    ShortcutInfo pinShortcutInfo =
            new 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.
    Intent pinnedShortcutCallbackIntent =
            shortcutManager.createShortcutResultIntent(pinShortcutInfo);

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

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.getIntentSender());
}

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

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

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

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

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

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

Тестовые ярлыки

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

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