ショートカットは、ユーザーがアプリの要素にすばやくアクセスできる方法で、特定の種類のコンテンツを提供します。
ショートカットでコンテンツを提供する方法は、ユースケースと、ショートカットのコンテキストがアプリ主導かユーザー主導かによって異なります。静的ショートカットのコンテキストは不変であり、動的ショートカットのコンテキストは常に変化しますが、どちらの場合もコンテキストはアプリ主導で決まります。固定ショートカットのようにユーザーがアプリのコンテンツ提供方法を選択する場合、コンテキストはユーザー主導で決まります。ショートカットの種類ごとにユースケースをいくつか示します。
- 静的ショートカットは、ユーザーがアプリを操作している間、一貫した構造でコンテンツにリンクするアプリに最適です。ほとんどのランチャーは一度に 4 つのショートカットしか表示できないため、静的ショートカットは一般的なアクティビティで有用です。たとえば、ユーザーがカレンダーまたはメールを特定の方法で表示したい場合、静的ショートカットにより、ルーティン タスクを一貫した方法で実施できます。
- 動的ショートカットは、コンテキスト依存のアプリのアクションに使用されます。たとえば、ユーザーがゲームを起動したときに現在のレベルから開始できるゲームを作成する場合、ショートカットを頻繁に更新する必要があります。動的ショートカットを使用すると、ユーザーがレベルをクリアするたびにショートカットが更新されます。
- 固定ショートカットは、特定のユーザー主導アクションに使用されます。たとえば、特定のウェブサイトをランチャーに固定する場合などです。これは、ユーザーがカスタム アクションを実行できるようになるため、便利です。たとえば、ブラウザのデフォルト インスタンスを使用するより迅速に、ワンステップでウェブサイトに移動できます。
静的ショートカットを作成する
静的ショートカットは、アプリ内の一般的なアクションへのリンクを提供します。こうしたアクションは、アプリの現行バージョンの存続期間を通して一貫性を保つ必要があります。静的ショートカットの適切な使用方法としては、送信済みメッセージの表示、アラームの設定、ユーザーの 1 日の運動状況の表示などがあります。
静的ショートカットを作成する手順は次のとおりです。
-
アプリのマニフェスト ファイル(
AndroidManifest.xml
)で、インテント フィルタがandroid.intent.action.MAIN
アクションとandroid.intent.category.LAUNCHER
カテゴリに設定されているアクティビティを見つけます。 -
次に示すように、アプリのショートカットが定義されているリソース ファイルを参照する
<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>
-
新しいリソース ファイル
res/xml/shortcuts.xml
を作成します。 -
この新しいリソース ファイルに、
<shortcut>
要素のリストを含む<shortcuts>
ルート要素を追加します。各<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" /> </shortcut> <!-- Specify more shortcuts here. --> </shortcuts>
属性値をカスタマイズする
以下では、静的ショートカット内のさまざまな属性について説明します。android:shortcutId
と android:shortcutShortLabel
の値は必須ですが、その他の値はすべて省略可能です。
-
android:shortcutId
-
文字列リテラル。
ShortcutManager
オブジェクトがオペレーションを実行するときのショートカットを表します。注: この属性の値をリソース文字列(
@string/foo
など)に設定することはできません。 -
android:shortcutShortLabel
-
ショートカットの目的を説明する簡潔なフレーズ。可能であれば、ショートカットの「短い説明」の長さは 10 文字以内にします。
詳しくは、
setShortLabel()
をご覧ください。注: この属性の値はリソース文字列(
@string/shortcut_short_label
など)にする必要があります。 -
android:shortcutLongLabel
-
ショートカットの目的を説明する詳細なフレーズ。十分なスペースがある場合、ランチャーは
android:shortcutShortLabel
の代わりにこの値を表示します。可能であれば、ショートカットの「長い説明」の長さは 25 文字以内にします。詳しくは、
setLongLabel()
をご覧ください。注: この属性の値はリソース文字列(
@string/shortcut_long_label
など)にする必要があります。 -
android:shortcutDisabledMessage
-
ユーザーが無効なショートカットを起動しようとしたときに、サポートされているランチャーに表示されるメッセージ。このメッセージでは、ショートカットが現在無効になっている理由をユーザーに説明する必要があります。
android:enabled
がtrue
の場合、この属性の値は効力を持ちません。注: この属性の値はリソース文字列(
@string/shortcut_disabled_message
など)にする必要があります。 -
android:enabled
-
サポートされているランチャーからユーザーがショートカットを操作できるかどうかを指定します。
android:enabled
のデフォルト値はtrue
です。false
に設定した場合は、android:shortcutDisabledMessage
も設定して、ショートカットを無効にした理由を説明する必要があります。そのようなメッセージを提供する必要がないと考える場合は、XML ファイルからショートカットを完全に削除するのが最も簡単です。 -
android:icon
-
ランチャーがショートカットをユーザーに表示するときに使用するビットマップまたはアダプティブ アイコン。この値には、画像へのパスか、画像を含むリソース ファイルのいずれかを指定できます。パフォーマンスと一貫性を向上させるには、可能な限りアダプティブ アイコンを使用します。
注: ショートカット アイコンに色合いを持たせることはできません。
内部要素を設定する
アプリの静的ショートカットをリストした XML ファイルは、各 <shortcut>
要素内で以下の要素をサポートします。定義する静的ショートカットごとに、intent
内部要素を含める必要があります。
-
intent
-
ユーザーがショートカットを選択したときにシステムが起動するアクション。このインテントでは、
android:action
属性の値を指定する必要があります。注: この
intent
要素に文字列リソースを含めることはできません。1 つのショートカットに複数のインテントを指定できます。詳しくは、複数のインテントとアクティビティを管理する、インテントを設定する、
TaskStackBuilder
クラスのリファレンスをご覧ください。 -
categories
-
アプリのショートカットで実行するアクション(新しいチャット メッセージの作成など)の種類をグループ化します。
サポートされているショートカット カテゴリの一覧については、
ShortcutInfo
クラスのリファレンスをご覧ください。
動的ショートカットを作成する
動的ショートカットは、アプリ内のコンテキストに応じた特定のアクションへのリンクを提供します。このアクションは、アプリを使用するたびに、また、アプリの実行中でも変更できます。動的ショートカットに適したアクションとしては、特定の相手への通話発信、特定の場所へのナビゲーション、ユーザーの前回のセーブポイントからのゲームの読み込みなどがあります。
ShortcutManager
API を使用すると、動的ショートカットで以下のオペレーションを実行できます。
-
公開:
setDynamicShortcuts()
を使用して動的ショートカットのリスト全体を再定義するか、addDynamicShortcuts()
を使用して動的ショートカットの既存のリストを拡張します。 -
更新:
updateShortcuts()
メソッドを使用します。 -
削除:
removeDynamicShortcuts()
を使用して動的ショートカットのセットを削除するか、removeAllDynamicShortcuts()
を使用してすべての動的ショートカットを削除します。
ショートカットでオペレーションを実行する方法の詳細については、ショートカットを管理すると
ShortcutManager
のリファレンスをご覧ください。
次のコード スニペットは、動的ショートカットを作成してアプリに関連付ける方法の例を示しています。
注: ShortcutManager
クラスのインスタンスを取得するには、引数に ShortcutManager.class
を指定した
Context.getSystemService(Class)
か、引数に
Context.SHORTCUT_SERVICE
を指定した
Context.getSystemService(String)
を使用する必要があります。
Kotlin
val shortcutManager = getSystemService<ShortcutManager>(ShortcutManager::class.java) val shortcut = ShortcutInfo.Builder(context, "id1") .setShortLabel("Website") .setLongLabel("Open the website") .setIcon(Icon.createWithResource(context, R.drawable.icon_website)) .setIntent(Intent(Intent.ACTION_VIEW, Uri.parse("https://www.mysite.example.com/"))) .build() shortcutManager!!.dynamicShortcuts = Arrays.asList(shortcut)
Java
ShortcutManager shortcutManager = getSystemService(ShortcutManager.class); ShortcutInfo shortcut = new ShortcutInfo.Builder(context, "id1") .setShortLabel("Website") .setLongLabel("Open the website") .setIcon(Icon.createWithResource(context, R.drawable.icon_website)) .setIntent(new Intent(Intent.ACTION_VIEW, Uri.parse("https://www.mysite.example.com/"))) .build(); shortcutManager.setDynamicShortcuts(Arrays.asList(shortcut));
固定ショートカットを作成する
Android 8.0(API レベル 26)以降では、固定ショートカットを作成できます。固定ショートカットは、静的ショートカットや動的ショートカットとは異なり、サポートされているランチャーに個別のアイコンとして表示されます。図 1 に、2 種類のショートカットの違いを示します。
注: サポートされているランチャーにショートカットを固定しようとすると、ショートカットを固定する権限をユーザーに求める確認ダイアログが表示されます。ユーザーがショートカットの固定を許可しなかった場合、ランチャーはリクエストをキャンセルします。

アプリを使用して、サポートされているランチャーにショートカットを固定する手順は次のとおりです。
-
isRequestPinShortcutSupported()
を使用して、デバイスのデフォルト ランチャーがショートカットのアプリ内固定をサポートしていることを確認します。 -
ショートカットがすでに存在するかどうかに応じて、次のいずれかの方法で
ShortcutInfo
オブジェクトを作成します。-
ショートカットがすでに存在する場合は、既存のショートカットの ID のみを含む
ShortcutInfo
オブジェクトを作成します。ショートカットに関連するその他の情報はすべてシステムにより自動的に検出され、固定されます。 -
新しいショートカットを固定する場合は、新しいショートカットの ID、インテント、短いラベルを含む
ShortcutInfo
オブジェクトを作成します。
注: システムによって固定ショートカットのバックアップと復元が自動的に行われるため、ショートカットの ID には、他のデバイスでは意味をなさないローカルで生成される識別子ではなく、不変の定数文字列またはサーバー側の識別子を使用する必要があります。
-
ショートカットがすでに存在する場合は、既存のショートカットの ID のみを含む
-
ショートカットをデバイスのランチャーに固定するため、
requestPinShortcut()
を呼び出します。このプロセス中に、PendingIntent
オブジェクトを渡すことができます。このオブジェクトは、ショートカットが正常に固定された場合にのみアプリに通知します。注: ユーザーがショートカットをランチャーに固定することを許可しなかった場合、アプリはコールバックを受け取りません。
ショートカットが固定されたら、アプリは
updateShortcuts()
メソッドを使用してコンテンツを更新できます。詳しくは、ショートカットを更新するをご覧ください。
次のコード スニペットは、固定ショートカットを作成する方法を示しています。
注: ShortcutManager
クラスのインスタンスを取得するには、引数に ShortcutManager.class
を指定した
Context.getSystemService(Class)
か、引数に
Context.SHORTCUT_SERVICE
を指定した
Context.getSystemService(String)
を使用する必要があります。
Kotlin
val shortcutManager = getSystemService(ShortcutManager::class.java) if (shortcutManager!!.isRequestPinShortcutSupported) { // Assumes there's already a shortcut with the ID "my-shortcut". // The shortcut must be enabled. val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build() // Create the PendingIntent object only if your app needs to be notified // that the user allowed the shortcut to be pinned. Note that, if the // pinning operation fails, your app isn't notified. We assume here that the // app has implemented 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()) { // Assumes there's already a shortcut with the ID "my-shortcut". // The shortcut must be enabled. ShortcutInfo pinShortcutInfo = new ShortcutInfo.Builder(context, "my-shortcut").build(); // Create the PendingIntent object only if your app needs to be notified // that the user allowed the shortcut to be pinned. Note that, if the // pinning operation fails, your app isn't notified. We assume here that the // app has implemented 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()); }
注: サポート ライブラリ API の
isRequestPinShortcutSupported()
と
requestPinShortcut()
もご覧ください。これらの API は、Android 7.1(API レベル 25)以下で動作します。サポート ライブラリは、非推奨の
EXTRA_SHORTCUT_INTENT
エクストラにフォールバックして、固定プロセスを試行します。
カスタム ショートカット アクティビティを作成する
![カスタム ダイアログ アクティビティにより「ホーム画面に Gmail のランチャー アイコンを追加しますか?」というメッセージが表示されているスクリーンショット。カスタム オプションは [いいえ] と [アイコンを追加] です。](https://developer.android.com/images/guide/topics/ui/shortcuts/pinned-shortcuts-dialog.png?hl=ja)
カスタム オプションと確認ボタンを備えたショートカットを作成する際に役立つ、特別なアクティビティを作成することもできます。図 2 は、Gmail アプリにおけるそのようなアクティビティの例を示しています。
アプリのマニフェスト ファイルで、
ACTION_CREATE_SHORTCUT
をアクティビティの
<intent-filter>
要素に追加します。この宣言により、ユーザーがショートカットを作成しようとしたとき、次の動作が設定されます。
- システムがアプリの特別なアクティビティを開始します。
- ユーザーがショートカットのオプションを設定します。
- ユーザーが確認ボタンを選択します。
-
アプリは
createShortcutResultIntent()
メソッドを使用してショートカットを作成します。このメソッドはIntent
を返します。アプリは、setResult()
で以前実行したアクティビティに、これを送り返します。 -
アプリは、カスタマイズされたショートカットの作成に使用されたアクティビティで、
finish()
を呼び出します。
同様に、アプリがインストールされたとき、または初めて起動されたときに、固定ショートカットをホーム画面に追加するようユーザーにリクエストするメッセージを表示することもできます。この方法は、通常のワークフローの一環としてショートカットの作成をユーザーに促すため、効果的です。
ショートカットをテストする
アプリのショートカットをテストするには、ショートカットをサポートするランチャーを備えたデバイスにアプリをインストールします。次に、以下のアクションを行います。
- アプリのランチャー アイコンを長押しして、アプリに定義したショートカットを表示します。
- ショートカットをタップし、デバイスのランチャーにドラッグして、固定します。