提供直接共享目标

<ph type="x-smartling-placeholder">

</ph>

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

使用直接共享目标，让其他应用的用户更轻松快捷 与您的应用分享网址、图片或其他类型的数据。直接分享功能的运作方式 直接在 Android 设备上显示消息和社交应用中的联系人 Sharesheet，用户无需选择应用，然后搜索联系人。

注意： 从 Android 11（API 级别 30）开始，您可以提供“直接共享”功能 仅通过共享快捷方式 API 实现目标 此页面。

ShortcutManagerCompat 是一种提供共享快捷方式的 AndroidX API， 与已弃用的 ChooserTargetService API 兼容。这是首选 发布共享快捷方式和 ChooserTargets 的方法。如需相关说明， 请参阅使用 AndroidX 提供共享快捷方式和 ChooserTarget 。

发布直接共享目标

Sharesheet 直接共享行仅显示由 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 按重要性对动态快捷方式进行排序。

   指数越低，表示重要性越高。如果您要通过 Google Cloud 的 它们可能是出现次数最多的对话，并按新近度排序。 。请勿发布已过时的快捷方式；对话中没有 过去 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 Sharesheet 显示固定数量的直接共享目标，这些 建议按排名排序。您可以提高 快捷方式：

• 确保所有 shortcutIds 都是唯一的，并且绝不针对不同的目标重复使用。
• 通过调用 setLongLived(true)。
• 对于与对话相关的快捷方式，请报告快捷方式的使用情况 重新发布相应的快捷键 结束日期：ShortcutManagerCompat.pushDynamicShortcut。 如需了解详情，请参阅报告通信应用的快捷方式使用情况 页面了解详情。
• 避免提供不相关或过时的直接共享目标，例如 用户在过去 30 天内未向其发送过消息的联系人。
• 对于短信应用，请避免为短号码或对话提供快捷方式 识别为潜在垃圾内容用户不太可能与 这些对话。
• 调用 setCategories() 以将快捷方式与 适当的mimeType 属性。例如： 对于短信应用，如果该联系人未启用 RCS 或彩信功能，则 将相应的快捷方式与非文本 MIME 类型（例如 image/*和video/*。
• 对于指定对话，一旦推送了动态快捷方式，且使用情况 请勿更改快捷方式 ID。这样可以确保使用情况数据得到保留 进行排名。

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

Sharing Shortcuts API

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

setCategories()

从 Android 10 开始，类别还可用于过滤符合以下条件的快捷方式： 可以处理共享 intent 或操作。请参阅声明分成 target 了解详情。对于快捷方式，此字段为必填字段 将用作共享目标。

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 中的系统 surface 可为快捷方式图像设置形状和主题。 通过 ShortcutManagerCompat、 自动将向后兼容性直接共享 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 中选择共享快捷方式 与上述目标份额示例相匹配，应用将获得以下内容 分享意图：

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 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);

如果收到的消息来自群聊，您还必须添加 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 提供共享快捷方式和 ChooserTarget

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

此服务已在兼容性库中声明，因此用户需要 无需在应用清单中声明该服务。但是，来自 必须将对服务的共享活动视为选择器目标 提供商。

在以下示例中，ChooserTargetService 的实现为 androidx.core.content.pm.ChooserTargetServiceCompat，已定义 中：

<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 使用新的 Shared Shortcuts API 共享 API。不检索结果 通过共享快捷方式 API，应用可以根据需要被动发布直接共享功能 。这快速加快了检索“直接共享”的过程 目标。ChooserTargetService直接份额 机制将继续有效，但系统会对提供给 因此要低于使用 Shared Shortcuts API 的任何目标。

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

共享目标的已发布快捷方式与启动器有何不同 shortcuts（长按 启动器）？

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

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

共享快捷方式的数量受到相同的动态限制 可通过以下方式获取快捷方式： getMaxShortcutCountPerActivity(android.content.Context)。用户可以发布 但请注意，分享快捷方式 。大多数应用启动器 在竖屏模式下，长按可显示最多四个或五个快捷方式 8 处于横屏模式查看此信息 常见问题解答 ，了解有关共享快捷方式的更多详情和指南。