提供直接分享目標

圖 1： Sharesheet 中的「直接共用」列，如 1 所示

使用直接分享目標，讓其他應用程式的使用者能夠更輕鬆快速地與您的應用程式分享網址、圖片或其他種類的資料。直接分享的運作方式是直接在 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 回報捷徑使用情形。詳情請參閱本頁的「回報通訊應用程式的捷徑使用情形」。舉例來說，您可以透過 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 或多媒體訊息功能，您就不會將對應的捷徑與非文字 MIME 類型 (例如 image/* 和 video/*) 建立關聯。
  • 針對特定對話，推送動態捷徑並回報使用情形後，請勿變更捷徑 ID。這樣做可確保系統保留使用資料來決定排名。

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

分享捷徑 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 Sharesheet 及其他 Android 10 系統介面現在的形狀和主題捷徑圖像。建議透過 ShortcutManagerCompat 提供共用捷徑，此時系統會自動為您將 Backcompat Direct Share 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) 回溯相容。

回報外寄郵件的捷徑使用情形

回報使用者傳送訊息的用量運作方式與建立訊息後按一下「傳送」按鈕類似。

如要觸發用量報告，請透過 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);

如果傳入的訊息來自群組通訊，由於 sender 類型與功能相關聯，因此您也必須新增 Audience 參數值。

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 相容性程式庫搭配使用，應用程式的資訊清單必須包含中繼資料選擇器-target-service 和意圖篩選器集。請參閱目前的 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) 中，我們以新的 Share Shortcuts API 取代 ChooserTargetService Direct Share API。相較之下，Share Shortcuts API 可允許應用程式預先發布直接分享目標，不必主動擷取結果。這樣在準備 ShareSheet 時，就會迅速加快直接共用目標的擷取程序。ChooserTargetService 直接分享機制會繼續運作，但系統會優先採用其他目標，而非使用 Share Shortcuts API 的目標。

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

共用目標的發布捷徑與啟動器捷徑 (在啟動器中長按應用程式圖示時常用的快速鍵用途) 有何不同？

任何基於「分享目標」目的發布的捷徑也是一種啟動器捷徑，且當您長按應用程式圖示時，就會出現在選單中。每個活動的捷徑數量上限也會計入應用程式發布的捷徑總數 (共用目標和舊版啟動器捷徑組合)。

共用捷徑應發布多少個指引。

共用捷徑數量受限於 getMaxShortcutCountPerActivity(android.content.Context) 可用的動態捷徑限制。使用者可以發布符合此限制的任何數字，但請注意，共用捷徑會顯示在應用程式啟動器中，或是顯示在分享工作表中。在長按時，大多數應用程式啟動器在直向模式下最多可以有四或五個捷徑，在橫向模式下則最多。如需共用捷徑的詳細資訊和指引，請參閱常見問題。

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