提供直接分享目標

所示

使用直接分享目標功能，讓其他應用程式的使用者更輕鬆快速 可與應用程式分享網址、圖片或其他種類的資料。直接分享功能的運作方式 直接在 Android 裝置上透過訊息和社交應用程式分享聯絡人 Sharesheet，使用者不必選取應用程式就能搜尋聯絡人。

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

發布直接分享目標

Sharesheet Direct Share 列只會顯示 Shared 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。建議您設定此屬性。 移除捷徑的方式，無論系統是否已快取該捷徑 免費 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 或多媒體訊息功能， 將對應的捷徑與非文字 MIME 類型建立關聯，例如 《image/*》和《video/*》。
• 系統為特定對話推送且使用動態捷徑後 則不要變更捷徑 ID。這可確保能保留使用資料 以便進行排名

當使用者輕觸任何直接分享目標時，應用程式必須將使用者導向至使用者介面 就能直接對攻擊目標採取行動。請勿向使用者顯示不清 UI，也不要將其放置在與輕觸目標無關的 UI 中。比方說，在訊息應用程式中輕觸「直接分享」圖示 target 會將使用者導向所選使用者的會話群組檢視。 鍵盤會顯示，並預先填入分享資料。

Share Shortcuts API

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

setCategories()

自 Android 10 起，類別也可用於篩選 可處理共用意圖或動作請參閱宣告共用 target。此為快速指令的必填欄位 預設選項是共用目標

setLongLived()

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

縮短捷徑存在時間有助於提高排名。請參閱取得最佳 排名。

setShortLabel()、setLongLabel()

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

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

提供捷徑圖像

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

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

請確認自動調整點陣圖遵循自動調整圖示的規範和尺寸。 最常見的做法是將預定的方形點陣圖縮放為 72x72 dp，並將透明畫布置中。如果您的圖示 包含透明區域，請務必加入背景顏色；否則 透明區域會顯示為黑色

請勿提供套用特定形狀的圖像。舉例來說， Android 10 (API 級別 29) 常用於為直接分享功能提供使用者顯示圖片 已遮蓋到圓形的 ChooserTarget。Android Sharesheet 和其他 Android 10 中的系統介面現已推出形狀和主題捷徑圖像。 我們建議您透過 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 功能

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/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 個快速鍵，以及 八在橫向模式下使用查看 常見問題 ，進一步瞭解有關分享捷徑的詳細資訊和指南。