提供直接分享目標

圖 1： Sharesheet 中的 Direct Share 列，如 1 所示

使用直接分享目標可讓其他應用程式的使用者以更輕鬆快速的方式，將網址、圖片或其他種類的資料提供給應用程式。直接分享功能的運作方式，是直接在 Android Sharesheet 上，透過訊息和社交應用程式顯示聯絡人，無需使用者選取應用程式就能搜尋聯絡人。

ShortcutManagerCompat 是一個提供分享捷徑的 AndroidX API，能與已淘汰的 ChooserTargetService API 回溯相容。建議您同時發布共用捷徑和 ChooserTargets。如需操作說明，請參閱本頁的「使用 AndroidX 提供共用捷徑和選擇工具」一節。

發布直接分享目標

Sharesheet Direct Share 資料列只會顯示由 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 回報捷徑使用情形。詳情請參閱本頁的「回報通訊應用程式的捷徑使用情形」一節。舉例來說，您可以在捷徑中透過具有 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);

  4. 如果使用者刪除聯絡人，請使用 removeLongLivedShortcut。無論系統服務是否已快取該捷徑，我們都建議您以這種方式移除捷徑。以下程式碼片段舉例說明如何完成這項作業。

    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/*) 建立關聯。
  • 針對特定對話推送動態捷徑並回報使用情況後，請勿變更捷徑 ID。這樣可以確保在排名時保留使用資料。

當使用者輕觸任何直接分享目標時，應用程式必須將他們導向 UI，讓使用者能直接對目標主體執行動作。請勿向使用者呈現容易混淆的 UI，也切勿將這類 UI 放置在與輕觸目標無關的使用者介面中。舉例來說，在訊息應用程式中，輕觸直接分享目標會將使用者導向所選對象的對話檢視。使用者可以看到鍵盤，並在訊息中預先填入分享資料。

Share 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.EXTRA_SHORTCUT_ID 是不同的意圖，因此無法使用，因此您必須手動傳遞 ID。

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

如果您開發通訊應用程式，可以回報傳出和傳入訊息的使用情形，藉此改善 Android Sharesheet 中的排名。如要這麼做，請透過 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 提供共用捷徑和 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 Share API 替換為新的 Shared Shortcuts API。透過 Share Shortcuts API 讓應用程式預先發布直接分享目標，而不是隨選擷取結果。這樣在準備 ShareSheet 時，就能快速擷取直接分享目標的擷取過程。ChooserTargetService 直接分享機制會繼續運作，但系統會以這種方式提供的目標排名，低於任何使用 Shared Shortcuts API 的目標。

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

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

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

針對共用捷徑所發布的設定數量指引。

共用捷徑的數量限制與透過 getMaxShortcutCountPerActivity(android.content.Context) 取得的動態捷徑相同。使用者可以將任意數量發布至該限制，但請注意，分享捷徑會顯示在應用程式啟動器中，然後長按分享工作表中。在直向模式下，大多數應用程式啟動器的長按會顯示最多四個或五個捷徑。在橫向模式下，最多則可顯示四個捷徑。如要進一步瞭解有關共用捷徑的詳細資訊和指引，請參閱常見問題。

上一頁
接收其他應用程式傳送的簡單資料