提供直接分享目標

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

使用直接分享目標，讓其他應用程式的使用者更輕鬆快速地與您的應用程式分享網址、圖片或其他類型的資料。直接分享功能會直接在 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 功能，在捷徑中指定功能繫結。

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 相容性程式庫，應用程式的資訊清單必須包含中繼資料選擇器目標服務和意圖篩選器集。請參閱目前的 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) 中，我們以新的 Sharing Shortcuts API 取代了 ChooserTargetService Direct Share API。應用程式不必在需要時才被動擷取結果，而是可以透過 Sharing Shortcuts API 預先發布 Direct Share 目標。這大幅加快了準備 ShareSheet 時擷取直接分享目標的程序。ChooserTargetService直接分享 機制仍可運作，但系統會將透過這種方式提供的目標，排序在任何使用 Sharing Shortcuts API 的目標之後。

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

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

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

應發布多少個分享捷徑？

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