Utwórz skróty

Skróty zapewniają użytkownikom określone rodzaje treści, ułatwiając im szybki dostęp do różnych części aplikacji.

Obraz przedstawiający kontrast między skrótami do aplikacji a przypiętymi skrótami
Rysunek 1. Skróty do aplikacji i przypięte skróty.

Sposób dostarczania treści za pomocą skrótów zależy od konkretnego przypadku użycia oraz tego, czy kontekst skrótu zależy od aplikacji czy użytkownika. Chociaż kontekst skrótu statycznego się nie zmienia, a kontekst dynamicznego skrótu stale się zmienia, aplikacja wpływa na kontekst w obu przypadkach. Jeśli użytkownik wybierze sposób, w jaki aplikacja dostarcza mu treści, np. przypięty skrót, kontekst jest zdefiniowany przez użytkownika. W poniższych scenariuszach opisano kilka przypadków użycia poszczególnych typów skrótów:

  • Skróty statyczne sprawdzają się najlepiej w aplikacjach, które prowadzą do treści przy użyciu spójnej struktury przez cały czas trwania korzystania z aplikacji przez użytkownika. Większość programów uruchamiających wyświetla tylko 4 skróty naraz, dlatego są przydatne do wykonywania rutynowych zadań w spójny sposób, na przykład gdy użytkownik chce wyświetlać kalendarz lub e-maila w określony sposób .
  • Skróty dynamiczne służą do wykonywania działań w aplikacjach, które uwzględniają kontekst. Skróty zależne od kontekstu są dostosowane do działań wykonywanych przez użytkowników w aplikacji. Jeśli na przykład tworzysz grę, w której użytkownik może rozpoczynać od obecnego poziomu, musisz często aktualizować skrót. Skrót dynamiczny umożliwia aktualizowanie skrótu za każdym razem, gdy użytkownik usunie dany poziom.
  • Przypięte skróty są używane do wykonywania określonych działań przez użytkowników. Użytkownik może na przykład chcieć przypiąć konkretną stronę do programu uruchamiającego. Jest to korzystne, bo pozwala użytkownikowi wykonać niestandardowe działanie, np. otwarcie witryny w jednym kroku, szybciej niż w przypadku domyślnej instancji przeglądarki.

Utwórz skróty statyczne

Skróty statyczne zapewniają linki do ogólnych działań w aplikacji. Te działania muszą być spójne przez cały okres korzystania z bieżącej wersji aplikacji. Dobre opcje skrótów statycznych obejmują wyświetlanie wysłanych wiadomości, ustawianie alarmu i wyświetlanie aktywności użytkownika w danym dniu.

Aby utworzyć skrót statyczny, wykonaj te czynności:

  1. W pliku AndroidManifest.xml aplikacji znajdź aktywność, której filtry intencji są ustawione na działanie android.intent.action.MAIN i kategorię android.intent.category.LAUNCHER.

  2. Dodaj do tej aktywności element <meta-data>, który odwołuje się do pliku zasobów zawierającego zdefiniowane skróty aplikacji:

      <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. Utwórz nowy plik zasobów o nazwie res/xml/shortcuts.xml.

  4. W nowym pliku zasobów dodaj element główny <shortcuts> zawierający listę elementów <shortcut>. W każdym elemencie <shortcut> podaj informacje o statycznym skrócie, w tym jego ikonę, etykiety opisu i intencje, które uruchamia on w aplikacji:

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

Dostosuj wartości atrybutów

Na liście poniżej znajdziesz opisy różnych atrybutów w ramach statycznego skrótu. Podaj wartości android:shortcutId i android:shortcutShortLabel. Wszystkie inne wartości są opcjonalne.

android:shortcutId

Literał ciągu znaków reprezentujący skrót, gdy obiekt ShortcutManager wykonuje operacje na nim.

android:shortcutShortLabel

Zwięzłe wyrażenie opisujące przeznaczenie skrótu. Jeśli to możliwe, ogranicz ten krótki opis do 10 znaków.

Więcej informacji: setShortLabel().

android:shortcutLongLabel

Rozszerzone wyrażenie opisujące przeznaczenie skrótu. Jeśli wystarczy miejsca, program uruchamiający wyświetli tę wartość zamiast android:shortcutShortLabel. Jeśli to możliwe, ogranicz ten długi tekst do 25 znaków.

Więcej informacji: setLongLabel().

android:shortcutDisabledMessage

Komunikat, który pojawia się w obsługiwanym programie uruchamiającym, gdy użytkownik próbuje uruchomić wyłączony skrót. Komunikat musi wyjaśniać użytkownikowi, dlaczego skrót jest wyłączony. Wartość tego atrybutu nie ma zastosowania, jeśli android:enabled ma wartość true.

android:enabled

Określa, czy użytkownik może korzystać ze skrótu z obsługiwanego programu uruchamiającego. Wartością domyślną android:enabled jest true. Jeśli ustawisz wartość false, ustaw android:shortcutDisabledMessage, która wyjaśnia, dlaczego wyłączasz skrót. Jeśli uważasz, że nie musisz przesyłać takiego komunikatu, całkowicie usuń skrót z pliku XML.

android:icon

Bitmapa lub ikona adaptacyjna, której używa program uruchamiający do wyświetlania skrótu użytkownikowi. Może to być ścieżka do obrazu lub plik zasobów zawierający obraz. Jeśli to możliwe, używaj ikon adaptacyjnych, aby zwiększyć wydajność i spójność.

Konfigurowanie elementów wewnętrznych

Plik XML zawierający listę statycznych skrótów do aplikacji obsługuje w każdym elemencie <shortcut> te elementy. W przypadku każdego zdefiniowanego statycznego skrótu musisz dodać element wewnętrzny intent.

intent

Działanie uruchamiane przez system, gdy użytkownik kliknie skrót. Ta intencja musi podawać wartość atrybutu android:action.

Dla jednego skrótu możesz podać wiele intencji. Więcej informacji znajdziesz w sekcjach Zarządzanie wieloma intencjami i działaniami, Ustawianie intencji oraz w dokumentacji klas TaskStackBuilder.

categories

Grupowanie typów działań wykonywanych za pomocą skrótów aplikacji, takich jak tworzenie nowych wiadomości czatu.

Listę obsługiwanych kategorii skrótów znajdziesz w dokumentacji klas ShortcutInfo.

capability-binding

Deklaruje możliwość powiązaną ze skrótem.

W poprzednim przykładzie skrót jest połączony z funkcją zadeklarowaną dla CREATE_MESSAGE, która jest intencją wbudowaną Działania w aplikacji. To powiązanie funkcji umożliwia użytkownikom korzystanie z Asystenta Google za pomocą poleceń głosowych w celu wywołania skrótu.

Utwórz skróty dynamiczne

Skróty dynamiczne zapewniają linki do określonych działań w aplikacji zależnych od kontekstu. Czynności te mogą się zmieniać w zależności od użycia aplikacji lub jej działania. Dobre zastosowania skrótów dynamicznych to np. dzwonienie do konkretnej osoby, przechodzenie do określonej lokalizacji czy wczytywanie gry z ostatniego punktu zapisu użytkownika. Do otwierania rozmowy możesz też używać skrótów dynamicznych.

Biblioteka ShortcutManagerCompat Jetpack jest pomocniczą dla ShortcutManager interfejsu API, który umożliwia zarządzanie dynamicznymi skrótami w aplikacji. Korzystanie z biblioteki ShortcutManagerCompat pozwala zmniejszyć ilość powtarzającego się kodu i zapewnić spójność skrótów w różnych wersjach Androida. Ta biblioteka jest też niezbędna do przekazywania skrótów dynamicznych, aby mogły się one pojawiać w usługach Google (np. w Asystencie) z biblioteką integracji skrótów Google.

Interfejs ShortcutManagerCompat API umożliwia aplikacji wykonywanie tych operacji za pomocą dynamicznych skrótów:

  • Przekazywanie i aktualizowanie: użyj pushDynamicShortcut(), by publikować i aktualizować skróty dynamiczne. Jeśli istnieją już skróty dynamiczne lub przypięte o tym samym identyfikatorze, każdy zmienny skrót zostanie zaktualizowany.
  • Usuń: pozwala usunąć zestaw skrótów dynamicznych, korzystając z polecenia removeDynamicShortcuts(). Usuń wszystkie skróty dynamiczne, używając polecenia removeAllDynamicShortcuts().

Więcej informacji na temat wykonywania operacji na skrótach znajdziesz w sekcji Zarządzanie skrótami i w dokumentacji ShortcutManagerCompat.

Oto przykład tworzenia skrótu dynamicznego i powiązania go z aplikacją:

Kotlin


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)

Java


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

Dodawanie biblioteki integracji skrótów Google

Biblioteka integracji skrótów Google to opcjonalna biblioteka Jetpack. Umożliwia stosowanie dynamicznych skrótów, które można wyświetlać na platformach Androida, np. w Menu z aplikacjami i w usługach Google takich jak Asystent. Ułatwia ona użytkownikom odkrywanie skrótów, które pozwalają szybko uzyskać dostęp do określonych treści lub ponownie odtworzyć działania w aplikacji.

Na przykład aplikacja do obsługi wiadomości może nacisnąć dynamiczny skrót do kontaktu o nazwie „Aleks” po tym, jak użytkownik napisze do tej osoby. Jeśli po wypchnięciu skrótu dynamicznego użytkownik powie do Asystenta „OK Google, wyślij wiadomość do Alexa w przykładowej aplikacji”, Asystent może uruchomić aplikację ExampleApp i automatycznie ją skonfigurować tak, aby wysyłał wiadomość do Alexa.

Skróty dynamiczne przekazywane za pomocą tej biblioteki nie podlegają limitom skrótów nałożonych na poszczególne urządzenia. Dzięki temu aplikacja może użyć skrótu za każdym razem, gdy użytkownik wykona powiązane z nią działanie. Dzięki temu Google będzie wiedzieć, jak często korzystają z niego użytkownicy, i zasugeruje do nich odpowiednie skróty.

Na przykład Asystent może się uczyć na podstawie skrótów wywoływanych przez Twoją aplikację do śledzenia aktywności fizycznej, którą użytkownik zwykle uruchamia codziennie rano, i proponować skrót „Rozpocznij bieg”, gdy podniesie on telefon rano.

Biblioteka integracji skrótów Google nie zawiera żadnych funkcji, które można adresować. Gdy dodasz tę bibliotekę do aplikacji, usługi Google będą mogły używać skrótów przekazywanych przez Twoją aplikację za pomocą ShortcutManagerCompat.

Aby użyć tej biblioteki w aplikacji, wykonaj te czynności:

  1. Zaktualizuj plik gradle.properties, by obsługiwał biblioteki AndroidaX:

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

  2. W app/build.gradle dodaj zależności dla biblioteki integracji skrótów Google i ShortcutManagerCompat:

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

Po dodaniu zależności bibliotek do projektu na Androida aplikacja może używać metody pushDynamicShortcut() z usługi ShortcutManagerCompat do przekazywania skrótów dynamicznych, które mogą być wyświetlane w Menu z aplikacjami i na innych platformach Google.

Utwórz przypięte skróty

W Androidzie 8.0 (poziom interfejsu API 26) i nowszych możesz tworzyć przypięte skróty. W przeciwieństwie do skrótów statycznych i dynamicznych przypięte skróty są wyświetlane w obsługiwanych programach uruchamiających jako osobne ikony. Rysunek 1 przedstawia różnice między tymi 2 typami skrótów.

Aby przypiąć skrót do obsługiwanego programu uruchamiającego, wykonaj te czynności:

  1. Użyj isRequestPinShortcutSupported(), aby sprawdzić, czy domyślny program uruchamiający na urządzeniu obsługuje przypinanie skrótów w aplikacji.

  2. Utwórz obiekt ShortcutInfo na 1 z 2 sposobów w zależności od tego, czy skrót istnieje:

    1. Jeśli skrót istnieje, utwórz obiekt ShortcutInfo zawierający tylko identyfikator istniejącego skrótu. System automatycznie znajduje i przypina wszystkie inne informacje związane ze skrótem.
    2. Jeśli przypinasz nowy skrót, utwórz obiekt ShortcutInfo zawierający identyfikator, intencję i krótką etykietę nowego skrótu.

  3. Przypnij skrót do programu uruchamiającego na urządzeniu, wywołując requestPinShortcut(). Podczas tego procesu możesz przekazać obiekt PendingIntent, który powiadomi aplikację tylko wtedy, gdy skrót zostanie przypięty.

    Po przypięciu skrótu aplikacja może zaktualizować jego zawartość za pomocą metody updateShortcuts(). Więcej informacji znajdziesz w sekcji Aktualizowanie skrótów.

Poniższy fragment kodu pokazuje, jak utworzyć przypięty skrót.

Kotlin

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

Java

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

Tworzenie niestandardowych działań skrótów

Obraz przedstawiający działanie niestandardowego okna, na którym widać pytanie „Czy chcesz dodać ikonę programu uruchamiającego Gmaila do ekranu głównego?”. Dostępne opcje to „Nie, dziękuję” i „Dodaj ikonę”.
Rysunek 2. Przykład działania niestandardowego skrótu do aplikacji.

Możesz też utworzyć specjalne działanie, które pomoże użytkownikom tworzyć skróty, a także opcje niestandardowe i przycisk potwierdzenia. Rysunek 2 przedstawia przykład tej aktywności w aplikacji Gmail.

W pliku manifestu aplikacji dodaj parametr ACTION_CREATE_SHORTCUT do elementu <intent-filter> aktywności. Deklaracja określa takie zachowanie, gdy użytkownik próbuje utworzyć skrót:

  1. System rozpocznie specjalistyczną aktywność w aplikacji.
  2. Opcje skrótu ustawia użytkownik.
  3. Użytkownik klika przycisk potwierdzenia.
  4. Aplikacja tworzy skrót za pomocą metody createShortcutResultIntent(). Ta metoda zwraca żądanie Intent, które aplikacja przekazuje z powrotem do aktywności wykonywanej wcześniej za pomocą metody setResult().
  5. Aplikacja wywołuje metodę finish() w ramach aktywności użytej do utworzenia niestandardowego skrótu.

Podobnie aplikacja może prosić użytkowników o dodanie przypiętych skrótów do ekranu głównego po instalacji lub przy pierwszym uruchomieniu aplikacji. Ta metoda jest skuteczna, ponieważ pomaga użytkownikom utworzyć skrót w ramach zwykłego przepływu pracy.

Przetestuj skróty

Aby przetestować skróty do aplikacji, zainstaluj ją na urządzeniu z programem uruchamiającym, który obsługuje skróty. Następnie wykonaj te czynności:

  • Naciśnij i przytrzymaj ikonę programu uruchamiającego aplikację, aby wyświetlić skróty zdefiniowane przez Ciebie do aplikacji.
  • Przeciągnij skrót, aby przypiąć go do programu uruchamiającego na urządzeniu.