提供直接分享目標

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

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

注意： 自 Android 11 (API 級別 30) 起，您只能透過本頁稍後說明的 Sharing Shortcuts API 提供直接分享目標。

ShortcutManagerCompat 是提供分享快速鍵的 AndroidX API，可與已淘汰的 ChooserTargetService API 回溯相容。這是發布分享捷徑和 ChooserTargets 的首選方式。如需操作說明，請參閱本頁的「使用 AndroidX 提供共用捷徑和 ChooserTarget」一節。

發布直接分享目標

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。無論系統服務是否快取捷徑，這都是移除捷徑的首選方式。以下程式碼片段說明如何執行這項操作。

   Kotlin

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

   Java

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

改善直接分享目標的排名

Android 分享頁面會顯示固定數量的直接分享目標。這些建議會依排名排序。如要提升捷徑的排名，請按照下列步驟操作：

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

如果使用者輕觸任何直接分享目標，應用程式必須將他們帶往可直接對目標主體執行動作的 UI。請勿向使用者顯示不清 UI，也不要將其放置在與輕觸目標無關的 UI 中。舉例來說，在訊息應用程式中，輕觸直接分享目標後，使用者會前往與所選對象的對話檢視畫面。鍵盤會顯示在畫面上，訊息會預先填入共用資料。

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() 提供自適應點陣圖。

請確認自適應點陣圖遵循相同的自適應圖示設定規範和尺寸。最常見的做法是將預定的正方形點陣圖縮放為 72x72 dp，並在 108x108 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 中選取與上述目標共用範例相符的共用快捷鍵，應用程式會取得以下共用意圖：

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 分享列中的排名。如要這麼做，請透過 ShortcutManagerCompat.pushDynamicShortcut 重新發布代表聯絡人的對話捷徑。

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

回報傳送訊息時使用捷徑

針對使用者傳送的訊息回報用量，與在建立訊息後點選「傳送」按鈕的功能類似。

如要觸發用量報表，請使用具有 actions.intent.SEND_MESSAGE 功能的快速指令，透過 ShortcutInfoCompat.Builder#addCapabilityBinding 指定功能繫結。

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

回報收到訊息時使用捷徑

如要在使用者收到簡訊、即時通訊訊息、電子郵件或通知等訊息時觸發用量回報功能，您必須透過具有 actions.intent.RECEIVE_MESSAGE 功能的 ShortcutInfoCompat.Builder#addCapabilityBinding，在捷徑中額外指定功能繫結。

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 提供分享捷徑和 ChooserTarget

如要使用 AndroidX 相容性程式庫，應用程式的資訊清單必須包含中繼資料選擇器-目標-服務和意圖篩選器集。請參閱目前的 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 直接分享 API 取代為新的分享捷徑 API。分享捷徑 API 可讓應用程式預先發布直接分享目標，而非在需要時才回應式擷取結果。這樣在準備 ShareSheet 時，就能快速擷取直接分享目標的擷取過程。ChooserTargetService 直接分享機制會繼續運作，但系統會將以這種方式提供的目標排在使用 Sharing Shortcuts API 的任何目標之下。

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

針對分享目標發布的捷徑與啟動器捷徑 (在啟動器中長按應用程式圖示時的一般用途) 有何不同？

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

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

共用捷徑的數量受限於透過 getMaxShortcutCountPerActivity(android.content.Context) 提供的動態捷徑限制。使用者可以將任意數量發布至該限制，但請注意，分享捷徑會顯示在應用程式啟動器中，然後長按分享工作表中。在長按模式下，大多數應用程式啟動器在直向模式下最多會顯示四或五個捷徑，在橫向模式下則最多會顯示八個捷徑。如需更多詳細資訊和捷徑分享指南，請參閱這篇常見問題。