富媒体内容插入

图 1. 统一 API 提供一个统一的位置来处理收到的内容，而无论系统采用何种特定界面机制，例如从长按菜单粘贴或使用拖放操作。

用户喜欢图片、视频和其他富有表现力的内容，但在应用中插入和移动这些内容并非易事。为了使您的应用能够轻松接收富媒体内容，我们引入了全新的统一 API，便于您接受来自任何来源（剪贴板粘贴、键盘输入或拖放操作）的内容。

您可以向界面组件附加新接口 OnReceiveContentListener，并在通过任何机制插入内容时获得回调。此回调会成为您的代码处理接收所有内容（从纯文本和样式文本到标记、图片、视频、音频文件等）的唯一位置。

为了向后兼容以前的 Android 版本，我们还向 AndroidX 添加了新的 API（可在 Core 1.5.0-beta1 和 Appcompat 1.3.0-beta-01 中获得），我们建议您在实现此功能时使用该 API。

概览

使用现有 API 时，每个界面机制（例如长按菜单或拖放）都有对应的 API。这意味着您必须单独与每个 API 集成，并为每种插入内容的机制添加类似的代码：

图 2. 以前，您的应用需要为每个界面机制实现不同的 API 来插入内容。

统一 API 会通过创建一个要实现的单一 API 来整合这些不同的代码路径，这样您就可以专注于应用特定的逻辑，而让平台处理其余的工作：

图 3. 全新的统一 API 可让您实现支持所有界面机制的单一 API。

此外，这种方法还意味着，在向平台添加插入内容的新方法时，您无需对代码做出其他更改即可在应用中启用相关支持。如果您的应用需要针对特定用例实现完全自定义，您仍然可以使用现有的 API，这些 API 将继续以相同的方式工作。

实现

新 API 是一个监听器接口，包含一种方法，即 OnReceiveContentListener。为了支持较低版本的 Android 平台，我们建议您使用 AndroidX Core 库中的匹配 OnReceiveContentListener 接口。

如需使用该 API，请先指定您的应用可以处理哪些类型的内容，以开始实现该监听器：

public class MyReceiver implements OnReceiveContentListener {
     public static final String[] MIME_TYPES = new String[] {"image/*", "video/*"};
     // ...

指定您的应用支持的所有内容 MIME 类型后，实现该监听器的其余部分：

 public class MyReceiver implements OnReceiveContentListener {
     public static final String[] MIME_TYPES = new String[] {"image/*", "video/*"};

     @Override
     public ContentInfoCompat onReceiveContent(View view, ContentInfoCompat contentInfo) {
         Pair<ContentInfoCompat, ContentInfoCompat> split = contentInfo.partition(
                 item -> item.getUri() != null);
         ContentInfo uriContent = split.first;
         ContentInfo remaining = split.second;
         if (uriContent != null) {
             ClipData clip = uriContent.getClip();
             for (int i = 0; i < clip.getItemCount(); i++) {
                 Uri uri = clip.getItemAt(i).getUri();
                 // App-specific logic to handle the URI ...
             }
         }
         // Return anything that your app didn't handle. This preserves the default platform
         // behavior for text and anything else that you aren't implementing custom handling for.
         return remaining;
     }
 }

如果您的应用已经支持与 intent 共享，您可以重复使用应用特定逻辑来处理内容 URI。将任何剩余数据返回以委派给平台进行处理。

实现监听器后，在您的应用界面元素的构造函数中设置该监听器：

public class MyActivity extends Activity {
     @Override
     public void onCreate(Bundle savedInstanceState) {
         // ...

         AppCompatEditText myInput = findViewById(R.id.my_input);
         ViewCompat.setOnReceiveContentListener(myInput, MyReceiver.MIME_TYPES, new MyReceiver());
     }
}

与键盘图片 API 相比

您可以将统一内容 API 视为现有键盘图片 API 的下一个版本。新的 API 支持键盘图片 API 的功能，以及一些其他功能。设备和功能兼容性因您使用 Jetpack 库还是 Android SDK 中的原生 API 而异。

支持的功能和 API 级别：Jetpack

操作或功能	受键盘图片 API 支持	受统一 API 支持
通过键盘插入	是（API 级别 13 及更高）	是（API 级别 13 及更高）
通过从长按菜单粘贴插入	否	是
通过拖放操作插入	否	是（API 级别 24 及更高）

支持的功能和 API 级别：原生 API

操作或功能	受键盘图片 API 支持	受统一 API 支持
通过键盘插入	是（API 级别 25 及更高）	是（Android 12 及更高版本）
通过从长按菜单粘贴插入	否
通过拖放操作插入	否