提供直接共享目标

图 1 ：Sharesheet 中的“直接共享”行，如图 1 所示

使用直接共享目标可让其他应用的用户更加轻松快捷地与您的应用分享网址、图片或其他类型的数据。直接共享的工作原理是，直接在 Android Sharesheet 上显示即时通讯和社交应用中的联系人，用户无需选择应用，然后再搜索联系人。

注意： 从 Android 11（API 级别 30）开始，您只能通过本页面后面所述的 Sharing Shortcuts API 提供直接共享目标。

ShortcutManagerCompat 是一个提供共享快捷方式的 AndroidX API，并且向后兼容已废弃的 ChooserTargetService API。这是发布共享快捷方式和 ChooserTargets 的首选方式。有关说明，请参阅本页中的使用 AndroidX 提供共享快捷方式和 ChooserTarget。

发布直接共享目标

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 报告快捷方式的使用情况。如需了解详情，请参阅本页中的报告通信应用的快捷方式使用情况。例如，通过使用具有 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。这样可以确保保留使用情况数据以用于排名。

如果用户点按任何直接共享目标，您的应用必须将用户转到一个界面，在该界面中，用户可以直接对目标对象执行操作。请勿向用户显示消除歧义界面，也不要将他们放置在与点按的目标无关的界面中。例如，在即时通讯应用中，点按“直接共享”目标会将用户转到与所选人员的对话视图。键盘可见，并且消息中已预填充共享的数据。

Sharing Shortcuts API

从 Android 10（API 级别 29）开始，ShortcutInfo.Builder 添加了一些方法和增强功能，以提供有关共享目标的更多信息：

setCategories()

从 Android 10 开始，类别还可用于过滤可以处理共享 intent 或操作的快捷方式。如需了解详情，请参阅声明共享目标。要用作共享目标的快捷方式必须填写此字段。

setLongLived()

指定快捷方式在被应用取消发布或设为不可见后（作为动态或固定快捷方式）是否有效。如果某个快捷方式长期存在，则可能被各种系统服务缓存，即使已取消发布为动态快捷方式也是如此。

使快捷方式长期存在有助于提高其排名。如需了解详情，请参阅获得最佳排名。

setShortLabel()、setLongLabel()

发布个人的快捷方式时，请在 setLongLabel() 中包含其全名，在 setShortLabel() 中包含任何简称，例如昵称或名字。

查看在 GitHub 上发布共享快捷方式的示例。

提供快捷方式图像

要创建共享快捷方式，您需要通过 setIcon() 添加图片。

共享快捷方式可以跨系统 Surface 显示，并且可能会被改变外观。此外，某些搭载 Android 版本 7、8 或 9（API 级别 25、26、27 和 28）的设备可能会显示没有背景的纯位图图标，而这会大幅降低对比度。为确保快捷方式的显示方式与预期相符，请使用 IconCompat.createWithAdaptiveBitmap() 提供自适应位图。

确保自适应位图遵循为自适应图标设定的准则和尺寸。 最常见的实现方法是将所需的方形位图缩放到 72x72 dp，并在 108x108 dp 的透明画布中居中显示。如果图标包含透明区域，您需要添加背景颜色；否则，透明区域会显示为黑色。

不要提供框在特定形状中的图像。例如，在 Android 10（API 级别 29）之前，为直接共享 ChooserTarget 提供框在圆形中的用户头像是很常见的。现在，Android 10 中的 Android Sharesheet 和其他系统 surface 可为快捷方式图像设置形状和主题。通过 ShortcutManagerCompat 提供共享快捷方式的首选方法可自动为您将 Backcompat 直接共享 ChooserTarget 对象设置为圆形。

声明共享目标

共享目标必须在应用的资源文件中声明，这与静态快捷方式定义类似。请在资源文件的 <shortcuts> 根元素中添加共享目标定义以及其他静态快捷方式定义。每个 <share-targets> 元素都包含有关共享数据类型、匹配类别以及将处理共享 intent 的目标类的信息。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>

共享目标中的数据元素类似于 intent 过滤器中的数据规范。每个共享目标都可以有多个类别，这些类别仅用于将应用的已发布快捷方式与其共享目标定义相匹配。类别可以具有应用定义的任意值。

如果用户在 Android Sharesheet 中选择与上述目标共享示例匹配的共享快捷方式，应用将获得以下共享 intent：

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，因此 Intent.EXTRA_SHORTCUT_ID 将不可用；如果需要，您必须手动传递 ID。

报告通信应用的快捷方式使用情况

如果您正在开发通信应用，则可以通过报告外发和传入消息的使用情况来提高在 Android Sharesheet 中的排名。为此，请通过 ShortcutManagerCompat.pushDynamicShortcut 重新发布代表联系人的对话快捷方式。

快捷方式的使用和功能绑定向后兼容 Android 5.0 (API 21)。

报告外发邮件的快捷方式使用情况

报告用户所发送消息的使用情况在功能上类似于在创建消息后点击“发送”按钮。

如需触发使用情况报告，请通过 ShortcutInfoCompat.Builder#addCapabilityBinding 使用 actions.intent.SEND_MESSAGE capability 在快捷方式中指定功能绑定。

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 类型与 capability 相关联。

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 类型与 capability 相关联。

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 提供共享快捷方式和 ChooserTarget

为了能够使用 AndroidX 兼容性库，应用的清单必须包含元数据 chooser-target-service 和 intent-filter 集。请参阅当前的 ChooserTargetService Direct Share API。

此服务已在兼容性库中声明，因此用户无需在应用清单中声明此服务。不过，必须将从共享 activity 指向服务的链接视为选择器目标提供程序。

在以下示例中，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>

共享快捷方式常见问题解答

系统如何存储快捷方式使用情况数据？用户是否会离开设备？

快捷方式完全存储在设备端加密磁盘分区的系统数据目录中。快捷方式中的信息（例如图标、intent 以及人名和资源）只能由系统服务和发布快捷方式的同一应用访问。

“直接共享”有哪些发展历程？

我们在 Android 6.0（API 级别 23）中引入了“直接共享”，以允许应用通过 ChooserTargetService 提供 ChooserTarget 对象。结果会被动地按需检索，导致目标的加载时间较长。

在 Android 10（API 级别 29）中，我们将 ChooserTargetService Direct Share API 替换为了新的 Shared Shortcuts API。Shared Shortcuts API 可让应用提前发布直接共享目标，而不是被动地按需检索结果。这快速加快了在准备 ShareSheet 时检索直接共享目标的过程。ChooserTargetService 直接共享机制将继续有效，但系统会对以这种方式提供的目标进行排名，使其低于任何使用 Shared Shortcuts API 的目标。

Android 11（API 级别 30）废弃了 ChooserTargetService 服务，Sharing Shortcuts API 是提供直接共享目标的唯一方式。

共享目标的已发布快捷方式与启动器快捷方式（长按启动器中的应用图标时通常使用的快捷方式）有何不同？

为“共享目标”而发布的任何快捷方式也是一种启动器快捷方式，会在长按应用的图标时显示在菜单中。每个 activity 的快捷方式计数上限也适用于应用发布的快捷方式的总数（共享目标和旧版启动器快捷方式的总和）。

关于用户应发布的共享快捷方式数量有何指南？

共享快捷方式的数量受 getMaxShortcutCountPerActivity(android.content.Context) 提供的动态快捷方式数量限制。用户可以在该限制范围内发布任何数量的应用，但必须注意，分享快捷方式可以在应用启动器长按和共享表单中显示。大多数应用启动器在长按时，最多可以显示 4 个或 5 个快捷方式（在竖屏模式下），在横屏模式下最多显示 8 个快捷方式。如需关于共享快捷方式的更多详细信息和指南，请参阅此常见问题解答。