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.

Rysunek 1. Skróty do aplikacji i przypięte skróty.

Sposób dostarczania treści za pomocą skrótów zależy od przypadku użycia oraz od tego, czy kontekst skrótu jest określany przez aplikację czy przez użytkownika. Mimo że kontekst skrótu statycznego się nie zmienia, a kontekst skrótu dynamicznego zmienia się nieustannie, w obu przypadkach kontekst jest określany przez aplikację. W przypadkach, gdy użytkownik wybiera sposób dostarczania treści przez aplikację, np. w przypadku 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 aplikacjach, które łączą się z treściami za pomocą spójnej struktury przez cały czas korzystania z aplikacji przez użytkownika. Ponieważ większość programów uruchamiających wyświetla tylko 4 skróty naraz, 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ń wykonywanych przez użytkowników w aplikacji. Jeśli na przykład tworzysz grę, która umożliwia użytkownikowi rozpoczęcie gry 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 ukończy poziom.
• Przypięte skróty są używane w przypadku określonych działań inicjowanych przez użytkownika. Użytkownik może na przykład przypiąć określoną witrynę do programu uruchamiającego. Jest to korzystne, ponieważ umożliwia użytkownikowi wykonanie niestandardowego działania, np. przejście do witryny w jednym kroku, szybciej niż w przypadku 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ć spójne przez cały okres korzystania z 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 są 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>
   

   Uwaga: jeśli używasz elementu activity-alias, zdefiniuj metadane w elemencie activity-alias, a nie w aktywności, do której kieruje, używając atrybutu targetActivity.

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> umieść informacje o skrócie statycznym, 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żej znajdziesz opisy różnych atrybutów w skrócie statycznym. Podaj wartość atrybutów android:shortcutId i android:shortcutShortLabel. Wszystkie inne wartości są opcjonalne.

android:shortcutId

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

Uwaga: nie możesz ustawić wartości tego atrybutu na ciąg zasobów, np. @string/shortcut_id.

android:shortcutShortLabel

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

Więcej informacji znajdziesz w artykule setShortLabel().

Uwaga: wartość tego atrybutu musi być ciągiem zasobów, np. @string/shortcut_short_label.

android:shortcutLongLabel

Rozszerzone wyrażenie opisujące cel skrótu. Jeśli jest wystarczająco dużo miejsca, program uruchamiający wyświetla tę wartość zamiast android:shortcutShortLabel. Jeśli to możliwe, ogranicz ten długi opis do 25 znaków.

Więcej informacji znajdziesz w artykule setLongLabel().

Uwaga:wartość tego atrybutu musi być ciągiem zasobów, np.@string/shortcut_long_label

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 wpływu, jeśli android:enabled ma wartość true.

Uwaga: wartość tego atrybutu musi być ciągiem zasobów, np. @string/shortcut_disabled_message.

android:enabled

Określa, czy użytkownik może wchodzić w interakcję ze skrótem z poziomu obsługiwanego programu uruchamiającego. Domyślna wartość android:enabled to true. Jeśli ustawisz ją na false, ustaw android:shortcutDisabledMessage, który 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 do wyświetlania skrótu użytkownikowi. Ta wartość może być ścieżką do obrazu lub pliku zasobów, który zawiera obraz. Aby poprawić wydajność i spójność, używaj ikon adaptacyjnych, gdy tylko jest to możliwe.

**Uwaga:** ikony skrótów nie mogą zawierać odcieni.

Konfigurowanie elementów wewnętrznych

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

intent

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

**Uwaga:** ten element intent nie może zawierać zasobów ciągów znaków.

Możesz podać wiele intencji dla jednego skrótu. Szczegółowe informacje znajdziesz w artykułach Zarządzanie wieloma intencjami i aktywnościami oraz Ustawianie intencji, a także w dokumentacji klasy TaskStackBuilder.

categories

Umożliwia grupowanie typów działań wykonywanych przez skróty aplikacji, np. tworzenie nowych wiadomości na czacie.

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

capability-binding

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

W poprzednim przykładzie skrót jest powiązany ze zdolnością zadeklarowaną dla CREATE_MESSAGE, która jest wbudowaną intencją akcji w aplikacji. To powiązanie możliwości umożliwia użytkownikom używanie poleceń głosowych w Asystencie Google do wywoływania skrótu.

Tworzenie skrótów dynamicznych

Skróty dynamiczne zawierają linki do określonych działań w aplikacji, które są zależne od kontekstu. Te działania mogą się zmieniać między użyciami aplikacji i podczas jej działania. Skróty dynamiczne można wykorzystać do dzwonienia do konkretnej osoby, nawigowania do określonej lokalizacji i wczytywania gry od ostatniego zapisu użytkownika. Możesz też używać skrótów dynamicznych do otwierania rozmowy.

Biblioteka Jetpack ShortcutManagerCompat to pomocnik interfejsu API ShortcutManager, który umożliwia zarządzanie dynamicznymi skrótami w aplikacji. Używanie biblioteki ShortcutManagerCompat zmniejsza ilość powtarzalnego kodu i pomaga zapewnić, że skróty będą działać spójnie w różnych wersjach Androida. Ta biblioteka jest też wymagana do przesyłania skrótów dynamicznych, aby mogły się one wyświetlać w usługach Google, takich jak Asystent, za pomocą biblioteki integracji skrótów Google.

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

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

Więcej informacji o wykonywaniu operacji na skrótach znajdziesz w artykułach Zarządzanie skrótami i Dokumentacja 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 skrótów dynamicznych, które mogą być wyświetlane w usługach Androida, takich jak program uruchamiający, oraz w usługach Google. Używanie tej biblioteki pomaga użytkownikom odkrywać skróty, aby szybko uzyskiwać dostęp do określonych treści lub powtarzać działania w aplikacji.

Skróty dynamiczne przesyłane za pomocą tej biblioteki nie podlegają ograniczeniom skrótów egzekwowanym na poziomie urządzenia. Dzięki temu aplikacja może przesyłać skrót za każdym razem, gdy użytkownik wykona powiązane działanie w aplikacji. Przesyłanie częstych skrótów w ten sposób umożliwia Google zrozumienie wzorców użytkowania użytkownika i sugerowanie mu skrótów odpowiednich do kontekstu.

Na przykład Asystent może się nauczyć na podstawie skrótów przesyłanych z aplikacji do śledzenia aktywności fizycznej, ż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 usługom Google przyjmowanie skrótów przesyłanych przez aplikację za pomocą ShortcutManagerCompat.

Aby użyć tej biblioteki w aplikacji:

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 od 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 przesyłania skrótów dynamicznych, które mogą być wyświetlane w programie uruchamiającym i w usługach Google.

Uwaga: Zalecamy używanie pushDynamicShortcut do przesyłania skrótów dynamicznych za pomocą biblioteki integracji skrótów Google. Aplikacja może używać innych metod do publikowania skrótów, ale mogą one się nie powieść, jeśli osiągną maksymalny limit skrótów.

Tworzenie przypiętych skrótów

W Androidzie 8.0 (interfejs API na poziomie 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 pokazuje różnicę między tymi 2 typami skrótów.

Uwaga: gdy próbujesz przypiąć skrót do obsługiwanego programu uruchamiającego, użytkownik otrzymuje okno potwierdzenia z prośbą o zgodę na przypięcie skrótu. Jeśli użytkownik nie zezwoli na przypięcie skrótu, program uruchamiający anuluje żądanie.

Aby przypiąć skrót do obsługiwanego programu uruchamiającego za pomocą aplikacji:

1. Użyj isRequestPinShortcutSupported(), aby sprawdzić, czy domyślny program uruchamiający urządzenia 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 znajdzie i przypnie 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.
   Uwaga: ponieważ system automatycznie tworzy kopie zapasowe i przywraca je na przypiętych skrótach, identyfikatory tych skrótów muszą zawierać stabilne, stałe ciągi znaków lub identyfikatory po stronie serwera, a nie identyfikatory generowane lokalnie, które mogą nie mieć sensu na innych urządzeniach.

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

   Uwaga: jeśli użytkownik nie zezwoli na przypięcie skrótu do programu uruchamiającego, Twoja aplikacja nie otrzyma wywołania zwrotnego.

   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.

Ten fragment kodu pokazuje, jak utworzyć przypięty skrót.

Uwaga: instancje klasy ShortcutManager uzyskasz, wywołując getSystemService() z klasą ShortcutManager.

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

Uwaga: zapoznaj się też z interfejsami API biblioteki pomocy isRequestPinShortcutSupported() i requestPinShortcut(), które działają w Androidzie 7.1 (poziom interfejsu API 25) i starszych. Biblioteka pomocy wraca do wycofanej EXTRA_SHORTCUT_INTENT dodatkowej, aby spróbować przypiąć skrót.

Tworzenie niestandardowej aktywności skrótu

Rysunek 2. Przykład niestandardowej aktywności okna dialogowego skrótu do aplikacji.

Możesz też utworzyć specjalną aktywność, która pomaga użytkownikom tworzyć skróty, wraz z opcjami niestandardowymi i przyciskiem potwierdzenia. Rysunek 2 przedstawia 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 konfiguruje następujące działanie, gdy użytkownik próbuje utworzyć skrót:

1. System uruchamia specjalną aktywność aplikacji.
2. Użytkownik ustawia opcje skrótu.
3. Użytkownik wybiera przycisk potwierdzenia.
4. Aplikacja tworzy skrót za pomocą metody createShortcutResultIntent(). Ta metoda zwraca Intent, który aplikacja przekazuje do wcześniej wykonywanej aktywności za pomocą setResult().
5. Aplikacja wywołuje finish() w aktywności używanej do tworzenia dostosowanego 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 aplikacji. 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 programem uruchamiającym, który obsługuje skróty. Następnie wykonaj te czynności:

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