提供直接分享目標

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

ShortcutManagerCompat 是提供分享快速指令的 AndroidX API，可回溯相容於已淘汰的 ChooserTargetService API。建議使用這個方法發布分享捷徑和 ChooserTargets。如需操作說明，請參閱本頁的「使用 AndroidX 提供分享捷徑和 ChooserTargets」。

發布直接分享目標

Sharesheet 的「直接分享」列只會顯示 Sharing Shortcuts 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 或多媒體訊息，您就不會將對應的捷徑與非文字 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) 之前，通常會為遮蓋成圓形的直接分享 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。由於這是不同的意圖，因此 Intent.EXTRA_SHORTCUT_ID 不會提供， 如需 ID，您必須手動傳遞。

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

如果您正在開發通訊應用程式，可以回報傳送和接收訊息的使用情形，提升應用程式在 Android 分享選單中的排名。如要這麼做，請透過 ShortcutManagerCompat.pushDynamicShortcut 重新發布代表聯絡人的對話捷徑。

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

製作外寄郵件的捷徑使用情形報表

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

如要觸發用量報表，請透過 ShortcutInfoCompat.Builder#addCapabilityBinding 在捷徑中指定功能繫結，並使用 actions.intent.SEND_MESSAGE 功能。

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

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 類型。

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)

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 功能的能力繫結。

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

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

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 型別。

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)

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 相容性程式庫，應用程式的資訊清單必須包含中繼資料選擇器目標服務和意圖篩選器集。請參閱目前的 ChooserTargetService Direct Share API。

相容性程式庫已聲明這項服務，因此使用者不必在應用程式資訊清單中聲明這項服務。不過，從分享活動到服務的連結必須視為選擇器目標供應商。

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

<activity
    android:name=".SendMessageActivity"
    android:label="@string/app_name"
    android:theme="@style/Sha>ringS<hortcutsDialogTheme"
    !-- This activity can resp>ond t<o Intents of >type SEND< --
    intent-filter
        action android:name=>"and<roid.intent.action.SEND" /
        category android:>name=&quo<t;android.intent.category.DEFAULT&qu>ot; /<
        data >andro<id: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
     >    t<aken 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) 中，我們以新的 Sharing Shortcuts API 取代 ChooserTargetService Direct Share API。應用程式可透過 Sharing Shortcuts API 預先發布直接分享目標，不必在需要時才被動擷取結果。這大幅加快了準備 ShareSheet 時擷取直接分享目標的程序。ChooserTargetService直接分享機制仍可運作，但系統會將透過這種方式提供的目標，排序在任何使用 Sharing Shortcuts API 的目標之後。

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

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

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

發布分享捷徑的數量應遵循哪些指引？

分享捷徑的數量與透過 getMaxShortcutCountPerActivity(android.content.Context) 提供的動態捷徑數量相同。發布的捷徑數量沒有上限，但請注意，分享的捷徑可能會顯示在應用程式啟動器長按選單和分享功能表中。在大多數應用程式啟動器上，長按會顯示最多四或五個捷徑 (直向模式)，以及八個捷徑 (橫向模式)。如要進一步瞭解如何分享捷徑，請參閱這篇常見問題。