提供直接分享目標

圖 1：Sharesheet 中的直接分享列，如1所示

使用直接分享目標，讓其他應用程式的使用者更輕鬆快速地將網址、圖片或其他類型的資料分享給您的應用程式。直接分享功能會直接在 Android 分享列中顯示來自訊息和社群媒體應用程式的聯絡人，使用者不必選取應用程式，然後搜尋聯絡人。

ShortcutManagerCompat 是一種提供分享捷徑的 AndroidX API， 與已淘汰的 ChooserTargetService API 相容建議您設定此屬性。 同時發布共用捷徑和 ChooserTargets 的功能。如需操作說明， 請參閱「使用 AndroidX 提供共用捷徑和 ChooserTargets」 。

發布直接分享目標

Sharesheet 直接共用列只會顯示共用捷徑 API 提供的動態捷徑。如要發布直接分享，請完成下列步驟 目標。

  1. 在應用程式的 XML 資源檔案中宣告 share-target 元素。

    <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
<share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity">
    <data android:mimeType="text/plain" />
    <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" />
</share-target>
</shortcuts>

  2. 在應用程式初始化時，請使用 setDynamicShortcuts 依重要性排序動態捷徑。

    指數越低代表重要性越高。建立通訊的管道 也可以是依最近時間排序的最熱門對話，就像在 請勿發布過時的捷徑；表示不可能出現的對話 過去 30 天內的使用者活動都會視為過時。

    Kotlin

    ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))

    Java

    List<ShortcutInfoCompat> shortcuts = new ArrayList<>();
shortcuts.add(shortcut1);
shortcuts.add(shortcut2);
...
ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);

  3. 如果你開發通訊應用程式，請透過以下方式回報捷徑使用情形： 每次使用者都會立即產生 pushDynamicShortcut 接收或傳送訊息給聯絡人。請參閱「回報捷徑使用情況： 通訊應用程式請參閱本頁的內容。例如，針對使用者傳送的訊息回報使用情形 透過指定套件的功能繫結 ShortcutInfoCompat.Builder#addCapabilityBinding 具備 actions.intent.SEND_MESSAGE 功能

    Kotlin

    val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
.addCapabilityBinding("actions.intent.SEND_MESSAGE").build()
ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

    Java

    ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

  4. 如果使用者刪除聯絡人，請使用 removeLongLivedShortcut。建議您設定此屬性。 移除捷徑的方式，無論系統是否已快取該捷徑 免費 Google Cloud 服務以下程式碼片段舉例說明如何完成這項作業。

    Kotlin

    val deleteShortcutId = "..."
ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))

    Java

    String deleteShortcutId = "...";
ShortcutManagerCompat.removeLongLivedShortcuts(
    myContext, Arrays.asList(deleteShortcutId));

改善直接分享目標的排名

Android Sharesheet 會顯示固定數量的直接分享目標。這些建議會依排名排序。你可以採取下列做法，提高捷徑的排名：

  • 請確認所有 shortcutIds 都是唯一值，且不會用於不同的目標。
  • 呼叫 setLongLived(true)，確保捷徑可長時間存在。
  • 針對對話相關捷徑，請透過 ShortcutManagerCompat.pushDynamicShortcut 重新發布相應捷徑，以便回報傳送和接收訊息的捷徑使用率。詳情請參閱本頁的「回報通訊應用程式的捷徑用量」。
  • 避免提供不相關或過時的直接分享目標，例如 過去 30 天內，未曾傳訊的使用者。
  • 如果是簡訊應用程式，請避免提供短碼或對話的捷徑 系統認定為疑似垃圾內容的相關內容。使用者不太可能和 就能找到這些對話
  • 呼叫 setCategories()，將捷徑與適當的 mimeType 屬性建立關聯。舉例來說，如果聯絡人未啟用 RCS 或 MMS，您就不會將對應的捷徑與非文字 MIME 類型 (例如 image/* 和 video/*) 建立關聯。
  • 系統為特定對話推送且使用動態捷徑後 。這可確保能保留使用資料 以便進行排名

當使用者輕觸任何直接分享目標時，應用程式必須將使用者導向至使用者介面 就能直接對攻擊目標採取行動。不要顯示 使用者會使出容易混淆的 UI，而且不要將使用者放置在與 則是點選目標比方說，在訊息應用程式中輕觸「直接分享」圖示 target 會將使用者導向所選使用者的會話群組檢視。鍵盤會顯示在畫面上，訊息則會預先填入共用資料。

Sharing Shortcuts API

自 Android 10 (API 級別 29) 起， ShortcutInfo.Builder 新增了方法和強化功能 提供共用目標的額外資訊

setCategories()
從 Android 10 開始，類別也用於篩選可處理分享意圖或動作的捷徑。詳情請參閱「宣告分享目標」。如要將捷徑用於分享目標，則必須填入這個欄位。
setLongLived()

指定捷徑是否在應用程式將其設為隱藏 (動態或固定捷徑) 或未發布時有效。如果快速鍵 因此可由各種系統服務快取 已取消發布為動態捷徑。

讓捷徑的生命週期更長，有助於提升排名。請參閱取得最佳 排名。

setShortLabel()、setLongLabel()

發布給個別使用者的捷徑時，請附上對方的完整 setLongLabel() 中的名稱或任何簡稱，例如暱稱或名字 名稱，在 setShortLabel() 中。

請參考在 GitHub 上發布共用捷徑的範例。

提供捷徑圖像

如要建立共用捷徑，你必須透過 setIcon() 新增圖片。

分享捷徑會出現在不同系統介面，且可能會重新調整。 此外，部分搭載 Android 7、8 或 9 (API 級別 25) 的裝置 26、27 和 28) 可能在沒有背景的情況下顯示僅點陣圖圖示， 大幅降低對比度為確保捷徑的外觀符合預期，請使用 IconCompat.createWithAdaptiveBitmap() 提供自適應點陣圖。

請確認自適應點陣圖遵循相同的自適應圖示設定規範和尺寸。最常見的做法是將所需正方形位圖縮放至 72 x 72 dp，並將其置中於 108 x 108 dp 的透明畫布中。如果您的圖示 包含透明區域，請務必加入背景顏色；否則 透明區域會顯示為黑色

請勿提供經過特定形狀遮罩的圖像。舉例來說，在 Android 10 (API 級別 29) 之前，如果要為 Direct Share ChooserTarget 提供使用者頭像，通常會將頭像遮罩成圓形。Android 10 中的 Android Sharesheet 和其他系統途徑現在會為捷徑圖像設定形狀和主題。我們建議您透過 ShortcutManagerCompat、 自動將回溯共用 ChooserTarget 物件調整為 社交圈。

宣告分享目標

分享目標必須在應用程式的資源檔案中宣告，類似於靜態捷徑定義。新增持份 資源檔案 <shortcuts> 根元素內的目標定義， 以及其他靜態捷徑定義每個 <share-targets> 元素都包含共用資料類型、相符的類別，以及將處理分享意圖的目標類別相關資訊。XML 程式碼如下所示：

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity">
    <data android:mimeType="text/plain" />
    <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" />
  </share-target>
</shortcuts>

共用目標中的資料元素類似於意圖篩選器中的資料規格。每個分享目標可以有多個類別，這些類別只用於將應用程式發布的捷徑與其分享目標定義相符。類別可以包含任意應用程式定義 輕鬆分配獎金

當使用者在 Android Sharesheet 中選取共用捷徑 與上述範例 target-share 相符，應用程式將取得下列內容： 共用意圖：

Action: Intent.ACTION_SEND
ComponentName: {com.example.android.sharingshortcuts /
                com.example.android.sharingshortcuts.SendMessageActivity}
Data: Uri to the shared content
EXTRA_SHORTCUT_ID: <ID of the selected shortcut>

如果使用者透過啟動器捷徑開啟分享目標，應用程式會取得在 ShortcutManagerCompat 中新增分享捷徑時建立的意圖。由於這是其他意圖，因此 Intent.EXTRA_SHORTCUT_ID 無法使用。 而且您必須手動傳遞 ID，以備不時之需

回報通訊應用程式的捷徑使用情形

如果你開發通訊應用程式，可以改善在 Android Sharesheet，以回報外寄郵件和傳入訊息的使用情形。 如要這麼做，請透過以下方法重新發布代表聯絡人的對話捷徑： ShortcutManagerCompat.pushDynamicShortcut。

捷徑用法和功能繫結可回溯相容於 Android 5.0 (API 21)。

回報傳送訊息時使用捷徑

回報使用者傳送的訊息，功能上類似於在建立訊息後按一下「傳送」按鈕。

如要觸發用量回報功能，請在捷徑中指定功能繫結 到 ShortcutInfoCompat.Builder#addCapabilityBinding 具備 actions.intent.SEND_MESSAGE 功能

Kotlin

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
.addCapabilityBinding("actions.intent.SEND_MESSAGE").build()
ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

Java

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

如果傳送的訊息是群組聊天訊息，您也必須新增 Audience 參數值，因為 recipient 類型與功能相關聯。

Kotlin

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", listOf("Audience")).build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

Java

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", Arrays.asList("Audience"))
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

回報收到訊息時使用捷徑

如要在使用者收到簡訊等訊息時觸發使用狀況報告， 即時通訊訊息、電子郵件或通知，您必須另外指定 快速指令中的繫結 ShortcutInfoCompat.Builder#addCapabilityBinding，內含 actions.intent.RECEIVE_MESSAGE 功能。

Kotlin

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE").build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

Java

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE")
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

如果收到的訊息來自群組聊天，您也必須新增 Audience 參數值，因為 sender 類型與功能相關聯。

Kotlin

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", listOf("Audience")).build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

Java

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(groupShortTitle)
  .setLongLabel(groupLongTitle)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", Arrays.asList("Audience"))
  .build();

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);

使用 AndroidX 提供共用捷徑和 ChooserTargets

如要與 AndroidX 相容性程式庫搭配使用，應用程式的資訊清單 必須包含中繼資料 chooser-target-service 和意圖篩選器組合。詳情請見 目前 ChooserTargetService Direct Share API。

這個服務已在相容性程式庫中宣告，因此使用者不必在應用程式資訊清單中宣告服務。不過， 傳送至服務的共用活動必須是選擇工具目標 。

在以下範例中，ChooserTargetService 的實作項目是 androidx.core.content.pm.ChooserTargetServiceCompat，已在 AndroidX 中定義：

<activity
    android:name=".SendMessageActivity"
    android:label="@string/app_name"
    android:theme="@style/SharingShortcutsDialogTheme">
    <!-- This activity can respond to Intents of type SEND -->
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:mimeType="text/plain" />
    </intent-filter>
    <!-- Only needed if you import the sharetarget AndroidX library that
         provides backwards compatibility with the old DirectShare API.
         The activity that receives the Sharing Shortcut intent needs to be
         taken into account with this chooser target provider. -->
    <meta-data
        android:name="android.service.chooser.chooser_target_service"
        android:value="androidx.sharetarget.ChooserTargetServiceCompat" />
</activity>

分享捷徑常見問題

系統會如何儲存捷徑使用資料？他們會離開裝置？

捷徑會完全儲存在裝置上，位於加密磁碟分區的系統資料目錄中。圖示、意圖等捷徑中的資訊 只有系統服務以及使用者可以存取個人和資源名稱 也就是發布捷徑的應用程式。

什麼是直接分享？

我們在 Android 6.0 (API 級別 23) 中推出了「直接分享」功能，可讓應用程式 透過 ChooserTargetService 提供 ChooserTarget 物件。系統會根據需求以回應方式擷取結果，導致目標載入時間緩慢。

在 Android 10 (API 級別 29) 中，我們取代了 ChooserTargetService Direct 使用新的 Shared Shortcuts API 共用 API。而非擷取結果 視需要使用 Share Shortcuts API 讓應用程式發布直接分享功能 指定目標這可在準備 ShareSheet 時，加快擷取直接分享目標的速度。ChooserTargetService 直接分享 機制會繼續運作，但系統會將目標排名 這樣就能低於任何使用 Share Shortcuts API 的目標。

Android 11 (API 級別 30) 已淘汰 ChooserTargetService 服務，且 Share Shortcuts API 是提供直接分享目標的唯一方法。

分享目標的發布捷徑與啟動器捷徑 (在啟動器中長按應用程式圖示時，捷徑的常見用法) 有何不同？

任何用於「分享目標」目的而發布的捷徑，也是啟動器捷徑，並會在長按應用程式圖示時顯示在選單中。 個別活動的捷徑數量上限也適用於 應用程式發布時的捷徑 (分享目標和舊版啟動器捷徑) 合併)。

發布分享捷徑的數量有何規範？

共用捷徑的數量受限於透過 getMaxShortcutCountPerActivity(android.content.Context) 提供的動態捷徑限制。每個人都可以發布 在應用程式啟動器中長按，並開啟分享工作表。大多數應用程式啟動器都位於 在直向模式下，最多可長按顯示 4 或 5 個快速鍵，以及 八在橫向模式下使用查看 常見問題 ，進一步瞭解有關分享捷徑的詳細資訊和指南。