Utwórz skróty

Skróty dostarczają użytkownikom określone typy treści, umożliwiając im szybki dostęp do części aplikacji.

Sposób dostarczania treści za pomocą skrótów zależy od przypadku użycia i od tego, czy kontekst skrótu jest określany przez aplikację czy przez użytkownika. Chociaż kontekst statycznego skrótu nie zmienia się, a kontekst dynamicznego skrótu zmienia się nieustannie, w obu przypadkach kontekst jest określany przez aplikację. W przypadku gdy użytkownik wybiera sposób dostarczania treści przez aplikację, np. za pomocą przypiętego skrótu, kontekst jest określany przez użytkownika. Poniższe scenariusze opisują kilka przypadków użycia każdego typu skrótu:

• Skróty statyczne najlepiej sprawdzają się w przypadku aplikacji, które łączą się z treściami za pomocą spójnej struktury przez cały okres interakcji użytkownika z aplikacją. Większość programów uruchamiających wyświetla jednocześnie tylko 4 skróty, dlatego skróty statyczne są przydatne do wykonywania rutynowych zadań w spójny sposób, np. gdy użytkownik chce wyświetlić kalendarz lub e-mail w określony sposób.
• Skróty dynamiczne są używane w przypadku działań w aplikacjach, które są zależne od kontekstu. Skróty zależne od kontekstu są dostosowane do działań, które użytkownicy wykonują w aplikacji. Jeśli na przykład tworzysz grę, która umożliwia użytkownikowi rozpoczęcie rozgrywki od bieżącego poziomu, musisz często aktualizować skrót. Użycie skrótu dynamicznego umożliwia aktualizowanie skrótu za każdym razem, gdy użytkownik przejdzie poziom.
• Przypięte skróty służą do wykonywania konkretnych działań inicjowanych przez użytkownika. Użytkownik może na przykład przypiąć konkretną witrynę do programu uruchamiającego. Jest to korzystne, ponieważ umożliwia użytkownikowi wykonanie niestandardowego działania, np. przejście do witryny w 1 kroku, szybciej niż w przypadku korzystania z domyślnej instancji przeglądarki.

Tworzenie skrótów statycznych

Skróty statyczne zawierają linki do ogólnych działań w aplikacji, które muszą pozostać niezmienne przez cały okres istnienia bieżącej wersji aplikacji. Dobre opcje skrótów statycznych to wyświetlanie wysłanych wiadomości, ustawianie alarmu i wyświetlanie aktywności fizycznej użytkownika w danym dniu.

Aby utworzyć skrót statyczny:

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, w którym zdefiniowane są 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>, który zawiera 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 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.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>
   

Dostosowywanie wartości atrybutów

Poniższa lista zawiera opisy różnych atrybutów w statycznym skrócie. Podaj wartość dla android:shortcutId i android:shortcutShortLabel. Wszystkie pozostałe wartości są opcjonalne.

android:shortcutId

Literał ciągu znaków, który reprezentuje skrót, gdy obiekt ShortcutManager wykonuje na nim operacje.

android:shortcutShortLabel

Krótkie zdanie opisujące przeznaczenie skrótu. Jeśli to możliwe, ogranicz ten krótki opis do 10 znaków.

Więcej informacji znajdziesz w sekcji setShortLabel().

android:shortcutLongLabel

Rozszerzone wyrażenie opisujące przeznaczenie skrótu. Jeśli jest wystarczająco dużo miejsca, program uruchamiający wyświetla tę wartość zamiast android:shortcutShortLabel. W miarę możliwości ogranicz długość tego opisu do 25 znaków.

Więcej informacji znajdziesz w sekcji setLongLabel().

android:shortcutDisabledMessage

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

android:enabled

Określa, czy użytkownik może korzystać ze skrótu w obsługiwanym programie uruchamiającym. Wartość domyślna parametru android:enabled to true. Jeśli ustawisz wartość false, podaj android:shortcutDisabledMessage, które wyjaśnia, dlaczego wyłączasz skrót. Jeśli uważasz, że nie musisz podawać takiego komunikatu, całkowicie usuń skrót z pliku XML.

android:icon

Bitmapa lub ikona adaptacyjna, której program uruchamiający używa podczas wyświetlania skrótu użytkownikowi. Może to być ścieżka do obrazu lub pliku zasobu, który zawiera obraz. Aby zwiększyć skuteczność i spójność, w miarę możliwości używaj ikon adaptacyjnych.

Konfigurowanie elementów wewnętrznych

Plik XML, który zawiera listę skrótów statycznych aplikacji, obsługuje te elementy w każdym elemencie <shortcut>. W przypadku każdego zdefiniowanego skrótu statycznego musisz uwzględnić element wewnętrzny intent.

intent

Działanie, które system uruchamia, gdy użytkownik wybierze skrót. Ten zamiar musi zawierać wartość atrybutu android:action.

Do jednego skrótu możesz podać wiele intencji. Szczegółowe informacje znajdziesz w sekcjach Zarządzanie wieloma intencjami i aktywnościami, Ustawianie intencji i w dokumentacji klasy TaskStackBuilder.

categories

Zawiera grupę typów działań, które wykonują skróty aplikacji, np. tworzenie nowych wiadomości na czacie.

Listę obsługiwanych kategorii skrótów znajdziesz w ShortcutInfodokumentacji klasy.

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, czyli wbudowanego zamiaru działań w aplikacji. To powiązanie funkcji umożliwia użytkownikom używanie poleceń głosowych z Asystentem Google do wywoływania skrótu.

Tworzenie skrótów dynamicznych

Skróty dynamiczne zawierają linki do konkretnych działań w aplikacji, które są dostosowane do kontekstu. Działania te mogą się zmieniać w zależności od tego, jak korzystasz z aplikacji, oraz w trakcie jej działania. Dynamiczne skróty mogą służyć np. do dzwonienia do konkretnej osoby, nawigowania do określonej lokalizacji czy wczytywania gry od ostatniego zapisanego punktu. Do otwierania rozmów możesz też używać skrótów dynamicznych.

Biblioteka Jetpack ShortcutManagerCompat to pomocnicza biblioteka interfejsu ShortcutManager API, która umożliwia zarządzanie dynamicznymi skrótami w aplikacji. Korzystanie z biblioteki ShortcutManagerCompat zmniejsza ilość powtarzalnego kodu i pomaga zapewnić spójne działanie skrótów w różnych wersjach Androida. Ta biblioteka jest też wymagana do przesyłania dynamicznych skrótów, aby mogły się one pojawiać na platformach Google, takich jak Asystent, za pomocą biblioteki integracji skrótów Google.

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

• Wypychanie i aktualizowanie: użyj pushDynamicShortcut(), aby opublikować i zaktualizować dynamiczne skróty. Jeśli istnieją już skróty dynamiczne lub przypięte o tym samym identyfikatorze, każdy skrót, który można zmienić, zostanie zaktualizowany.
• Usuń:usuń zestaw dynamicznych skrótów za pomocą removeDynamicShortcuts(). Usuń wszystkie skróty dynamiczne za pomocą removeAllDynamicShortcuts().

Więcej informacji o wykonywaniu operacji na skrótach znajdziesz w artykule Zarządzanie skrótami oraz w dokumentacji ShortcutManagerCompat.

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

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)

Dodawanie biblioteki integracji skrótów Google

Biblioteka integracji skrótów Google to opcjonalna biblioteka Jetpack. Umożliwia ona przesyłanie dynamicznych skrótów, które mogą być wyświetlane w usługach Androida, takich jak program uruchamiający, oraz w usługach Google. Korzystanie z tej biblioteki pomaga użytkownikom odkrywać skróty, które umożliwiają szybki dostęp do określonych treści lub powtarzanie działań w aplikacji.

Skróty dynamiczne przesyłane za pomocą tej biblioteki nie podlegają limitom skrótów egzekwowanym na poszczególnych urządzeniach. Dzięki temu aplikacja może wysyłać skrót za każdym razem, gdy użytkownik wykona powiązane działanie w aplikacji. Wysyłanie w ten sposób często używanych skrótów pozwala Google poznać wzorce korzystania z aplikacji przez użytkownika i sugerować mu skróty odpowiednie w danym kontekście.

Asystent może na przykład nauczyć się na podstawie skrótów przesłanych z aplikacji do śledzenia aktywności, że użytkownik zwykle biega każdego ranka, i proaktywnie sugerować skrót „rozpocznij bieg”, gdy użytkownik rano weźmie telefon do ręki.

Biblioteka integracji skrótów Google nie oferuje żadnych funkcji, do których można się odwoływać. Dodanie tej biblioteki do aplikacji umożliwia platformom Google korzystanie ze skrótów, które aplikacja wysyła za pomocą ShortcutManagerCompat.

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

1. Zaktualizuj plik gradle.properties, aby obsługiwał biblioteki AndroidX:

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

2. W pliku 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 biblioteki do projektu aplikacji na Androida aplikacja może używać metody pushDynamicShortcut() z ShortcutManagerCompat do wysyłania dynamicznych skrótów, które kwalifikują się do wyświetlania w programie uruchamiającym i na platformach Google.

Tworzenie przypiętych skrótów

Na 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 pojawiają się w obsługiwanych programach uruchamiających jako osobne ikony. Rysunek 1 przedstawia różnicę między tymi 2 rodzajami skrótów.

Aby przypiąć skrót do obsługiwanego programu uruchamiającego za pomocą aplikacji, 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 jeden z 2 sposobów w zależności od tego, czy skrót istnieje:

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

3. Przypnij skrót do programu uruchamiającego urządzenia, 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 aktualizować jego zawartość za pomocą metody updateShortcuts(). Więcej informacji znajdziesz w artykule Aktualizowanie skrótów.

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

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

Tworzenie własnej aktywności skrótu

Możesz też utworzyć specjalną aktywność, która pomoże użytkownikom tworzyć skróty, wraz z opcjami niestandardowymi i przyciskiem potwierdzenia. Na ilustracji 2 widać przykład tego typu aktywności w aplikacji Gmail.

W pliku manifestu aplikacji dodaj ACTION_CREATE_SHORTCUT do elementu <intent-filter> aktywności. Ta deklaracja określa następujące zachowanie, gdy użytkownik próbuje utworzyć skrót:

1. System uruchamia specjalistyczne działanie aplikacji.
2. Użytkownik ustawia opcje skrótu.
3. Użytkownik klika przycisk potwierdzenia.
4. Aplikacja tworzy skrót za pomocą metody createShortcutResultIntent(). Ta metoda zwraca Intent, który Twoja aplikacja przekazuje z powrotem do wcześniej wykonywanego działania za pomocą setResult().
5. Aplikacja wywołuje funkcję finish() w przypadku aktywności użytej do utworzenia spersonalizowanego skrótu.

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

Testowanie skrótów

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

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