接收富媒体内容

图 1. 统一 API 提供了一个单一位置来处理传入内容,无论具体的 UI 机制是什么,例如从触摸并按住菜单粘贴或使用拖放。

用户喜欢图像、视频和其他富有表现力的内容,但在应用中插入和移动这些内容并不总是那么容易。为了简化应用接收富媒体内容的过程,Android 12(API 级别 31)引入了一个统一 API,让您的应用能够接受来自任何来源(剪贴板、键盘或拖动)的内容。

您可以将接口(例如 OnReceiveContentListener)附加到 UI 组件,并在通过任何机制插入内容时获得回调。此回调将成为您的代码处理所有内容接收的单一位置,无论是纯文本、带样式文本、标记、图像、视频、音频文件还是其他内容。

为了与以前的 Android 版本保持向后兼容,此 API 也可在 AndroidX 中使用,从 Core 1.7Appcompat 1.4 开始,我们建议您在实现此功能时使用这些版本。

概览

对于其他现有 API,每种 UI 机制(例如触摸并按住菜单或拖动)都有其对应的 API。这意味着您必须分别与每个 API 集成,为每个插入内容的机制添加相似的代码。

An image showing the different actions and the relative API to implement
图 2. 以前,应用为每种插入内容的 UI 机制实现不同的 API。

OnReceiveContentListener API 通过创建一个要实现的单一 API 来整合这些不同的代码路径,因此您可以专注于您的应用特定逻辑,让平台处理其余部分。

An image showing the simplified unified API
图 3. 统一 API 让您能够实现一个支持所有 UI 机制的单一 API。

这种方法还意味着,当平台添加新的内容插入方式时,您无需进行额外的代码更改即可在您的应用中启用支持。如果您的应用需要为特定用例实现完全自定义,您仍然可以使用现有 API,这些 API 的工作方式保持不变。

实现

该 API 是一个只有一个方法 OnReceiveContentListener 的监听器接口。为了支持旧版 Android 平台,我们建议在 AndroidX Core 库中使用匹配的 OnReceiveContentListener 接口。

要使用该 API,请通过指定您的应用可以处理的内容类型来实现监听器:

Kotlin

object MyReceiver : OnReceiveContentListener {
    val MIME_TYPES = arrayOf("image/*", "video/*")
    
    // ...
    
    override fun onReceiveContent(view: View, payload: ContentInfoCompat): ContentInfoCompat? {
        TODO("Not yet implemented")
    }
}

Java

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

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

Kotlin

class MyReceiver : OnReceiveContentListener {
    override fun onReceiveContent(view: View, contentInfo: ContentInfoCompat): ContentInfoCompat {
        val split = contentInfo.partition { item: ClipData.Item -> item.uri != null }
        val uriContent = split.first
        val remaining = split.second
        if (uriContent != null) {
            // App-specific logic to handle the URI(s) in uriContent.
        }
        // 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
    }

    companion object {
        val MIME_TYPES = arrayOf("image/*", "video/*")
    }
}

Java

 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) {
             // App-specific logic to handle the URI(s) in uriContent.
         }
         // 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。返回任何剩余数据,以将该数据的处理委托给平台。

实现监听器后,将其设置在您的应用中相应的 UI 元素上:

Kotlin

class MyActivity : Activity() {
    public override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...
        val myInput = findViewById(R.id.my_input)
        ViewCompat.setOnReceiveContentListener(myInput, MyReceiver.MIME_TYPES, MyReceiver())
    }
}

Java

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

URI 权限

平台会自动为传递给 OnReceiveContentListener 的载荷中的任何 内容 URI 授予和释放读取权限。

通常,您的应用会在服务或 Activity 中处理内容 URI。对于长时间运行的处理,请使用 WorkManager。实现此功能时,通过使用 Intent.setClipData 传递内容并设置标志 FLAG_GRANT_READ_URI_PERMISSION,将权限扩展到目标服务或 Activity。

或者,您可以在当前上下文中使用后台线程来处理内容。在这种情况下,您必须维护对监听器接收到的 payload 对象的引用,以帮助确保权限不会被平台过早撤销。

自定义视图

如果您的应用使用自定义 View 子类,请务必确保 OnReceiveContentListener 不会被绕过。

如果您的 View 类覆盖了 onCreateInputConnection 方法,请使用 Jetpack API InputConnectionCompat.createWrapper 来配置 InputConnection

如果您的 View 类覆盖了 onTextContextMenuItem 方法,当菜单项为 R.id.pasteR.id.pasteAsPlainText 时,委托给 super。

与键盘图片 API 的比较

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

表 1. Jetpack 支持的功能和 API 级别。
操作或功能 键盘图片 API 支持 统一 API 支持
从键盘插入 是(API 级别 13 及更高版本) 是(API 级别 13 及更高版本)
使用触摸并按住菜单粘贴插入
使用拖放插入 是(API 级别 24 及更高版本)
表 2. 原生 API 支持的功能和 API 级别。
操作或功能 键盘图片 API 支持 统一 API 支持
从键盘插入 是(API 级别 25 及更高版本) 是(Android 12 及更高版本)
使用触摸并按住菜单粘贴插入
使用拖放插入