此页面由 Cloud Translation API 翻译。

图片键盘支持

用户通常希望使用表情符号、贴纸和其他类型的内容。在之前的 Android 版本中，软键盘（也称为输入法，或 IME - 只能向应用发送 Unicode 表情符号。对于富媒体内容，这些特定于应用的 API，不能在其他应用中使用，或者使用了通过简单的分享操作发送图片或剪贴板。

一张图片，显示了一个支持图片搜索的键盘 — **图 1.** 图片键盘支持示例。

从 Android 7.1（API 级别 25）开始，Android SDK 包含 Commit Content API：为 IME 提供了一种通用方式，直接将富媒体内容发布到应用中的文本编辑器。此 API 还适用于以下语言： v13 支持库（从修订版 25.0.0 开始）。我们建议使用库，因为它包含可简化实现的辅助方法。

借助此 API，您可以构建即时通讯应用，以便接收来自任何来源的富媒体内容以及可向任何应用发送丰富内容的键盘。Google 键盘以及诸如Android 信息 Google 在 Android 7.1 中支持 Commit Content API，如图 1 所示。

本文档介绍了如何在 IME 和。

工作原理

键盘图片插入需要 IME 和应用的参与。通过以下序列介绍了图片插入过程中的各个步骤：

当用户点按 EditText 时，编辑器会发送 EditorInfo.contentMimeTypes。
IME 会读取支持的类型列表，并在编辑器可以接受的软键盘中显示内容。
当用户选择图片时，IME 会调用 commitContent() 并发送 InputContentInfo 修改。commitContent() 调用类似于 commitText() 调用，但适用于富媒体内容。InputContentInfo 包含一个 URI，标识内容中的内容 provider。

此过程如图 2 所示：

显示从应用到 IME 再到应用的顺序的图片 — **图 2.** 应用到 IME 到应用的流程。

为应用添加图片支持

若要接受来自 IME 的富媒体内容，应用必须告知 IME 它包含的内容类型。接受并指定当收到内容时执行的回调方法。以下示例演示了如何创建接受 PNG 的 EditText 图片：

Kotlin

var editText: EditText = object : EditText(this) {
    override fun onCreateInputConnection(outAttrs: EditorInfo): InputConnection {
        var ic = super.onCreateInputConnection(outAttrs)
        EditorInfoCompat.setContentMimeTypes(outAttrs, arrayOf("image/png"))
        val mimeTypes = ViewCompat.getOnReceiveContentMimeTypes(this)
        if (mimeTypes != null) {
            EditorInfoCompat.setContentMimeTypes(outAttrs, mimeTypes)
            ic = InputConnectionCompat.createWrapper(this, ic, outAttrs)
        }
        return ic
    }
}

Java

EditText editText = new EditText(this) {
    @Override
    public InputConnection onCreateInputConnection(EditorInfo outAttrs) {
        InputConnection ic = super.onCreateInputConnection(outAttrs);
        EditorInfoCompat.setContentMimeTypes(outAttrs, new String[]{"image/png"});
        String[] mimeTypes = ViewCompat.getOnReceiveContentMimeTypes(this);
        if (mimeTypes != null) {
            EditorInfoCompat.setContentMimeTypes(outAttrs, mimeTypes);
            ic = InputConnectionCompat.createWrapper(this, ic, outAttrs);
        }
        return ic;
    }
};

以下是进一步说明：

本示例使用了支持库，因此其中有一些对 android.support.v13.view.inputmethod 而非 android.view.inputmethod。
本示例创建了一个 EditText，并替换了其 onCreateInputConnection(EditorInfo) 方法修改 InputConnection。 InputConnection 是 IME 与在接收输入数据的应用。
通话 super.onCreateInputConnection() 保留内置行为（发送和接收文本），并且提供对 InputConnection 的引用。
setContentMimeTypes() 将支持的 MIME 类型列表添加到 EditorInfo。致电 super.onCreateInputConnection()，setContentMimeTypes()之前。
每当 IME 提交内容时，系统便会执行 callback。方法 onCommitContent() 引用了 InputContentInfoCompat, 该字段包含一个内容 URI。
- 如果您的应用在 API 级别 25 上运行，则请求和发布权限或更高版本的 INPUT_CONTENT_GRANT_READ_URI_PERMISSION 标志由 IME 设置。否则，你已有权访问相应内容 URI，因为它是由 IME 或 content provider 授予的不限制访问权限。如需了解详情，请参阅向 IME。
createWrapper() 封装 InputConnection、修改后的 EditorInfo 以及回调放入新的 InputConnection 并将其返回。

以下是推荐的做法：

不支持富媒体内容的编辑器不会调用 setContentMimeTypes()，并且该用户保留自己的 EditorInfo.contentMimeTypes 设置发送至 null。
如果 InputContentInfo 中指定的 MIME 类型，则编辑器会忽略此内容都不匹配。
富媒体内容不会影响文本位置，也不会受其影响光标。使用内容时，编辑器可以忽略光标位置。
在编辑器的 OnCommitContentListener.onCommitContent() 方法，您可以异步返回 true，即使然后再加载内容
与在提交前可以在 IME 中修改的文本不同，富文本立即提交。如果您要允许用户修改或删除您需要自行实现逻辑

如需测试您的应用，请确保您的设备或模拟器具有可以富媒体内容。您可以在 Android 7.1 或更高版本中使用 Google 键盘。

为 IME 添加图片支持

想要向应用发送富媒体内容的 IME 必须实现提交内容 API，如以下示例所示：

替换 onStartInput() 或 onStartInputView() 并从目标中读取支持的内容类型列表编辑器。以下代码段展示了如何检查目标编辑器是否接受 GIF 图片。

Kotlin

override fun onStartInputView(editorInfo: EditorInfo, restarting: Boolean) {
    val mimeTypes: Array<String> = EditorInfoCompat.getContentMimeTypes(editorInfo)

    val gifSupported: Boolean = mimeTypes.any {
        ClipDescription.compareMimeTypes(it, "image/gif")
    }

    if (gifSupported) {
        // The target editor supports GIFs. Enable the corresponding content.
    } else {
        // The target editor doesn't support GIFs. Disable the corresponding
        // content.
    }
}

Java

@Override
public void onStartInputView(EditorInfo info, boolean restarting) {
    String[] mimeTypes = EditorInfoCompat.getContentMimeTypes(editorInfo);

    boolean gifSupported = false;
    for (String mimeType : mimeTypes) {
        if (ClipDescription.compareMimeTypes(mimeType, "image/gif")) {
            gifSupported = true;
        }
    }

    if (gifSupported) {
        // The target editor supports GIFs. Enable the corresponding content.
    } else {
        // The target editor doesn't support GIFs. Disable the corresponding
        // content.
    }
}

当用户选择图片时，将内容提交到应用。避免调用 commitContent()。可能导致编辑器失去焦点。以下代码段展示了如何来提交 GIF 图片。

Kotlin

// Commits a GIF image.

// @param contentUri = Content URI of the GIF image to be sent.
// @param imageDescription = Description of the GIF image to be sent.

fun commitGifImage(contentUri: Uri, imageDescription: String) {
    val inputContentInfo = InputContentInfoCompat(
            contentUri,
            ClipDescription(imageDescription, arrayOf("image/gif")),
            null
    )
    val inputConnection = currentInputConnection
    val editorInfo = currentInputEditorInfo
    var flags = 0
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N_MR1) {
        flags = flags or InputConnectionCompat.INPUT_CONTENT_GRANT_READ_URI_PERMISSION
    }
    InputConnectionCompat.commitContent(inputConnection, editorInfo, inputContentInfo, flags, null)
}

Java

// Commits a GIF image.

// @param contentUri = Content URI of the GIF image to be sent.
// @param imageDescription = Description of the GIF image to be sent.

public static void commitGifImage(Uri contentUri, String imageDescription) {
    InputContentInfoCompat inputContentInfo = new InputContentInfoCompat(
            contentUri,
            new ClipDescription(imageDescription, new String[]{"image/gif"}),
            null
    );
    InputConnection inputConnection = getCurrentInputConnection();
    EditorInfo editorInfo = getCurrentInputEditorInfo();
    Int flags = 0;
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N_MR1) {
        flags |= InputConnectionCompat.INPUT_CONTENT_GRANT_READ_URI_PERMISSION;
    }
    InputConnectionCompat.commitContent(
            inputConnection, editorInfo, inputContentInfo, flags, null);
}

作为 IME 的创建者，您很可能必须实现自己的 content provider 才能响应内容 URI 请求。例外情况是，如果您的 IME 支持内容，来自现有内容提供方 MediaStore。如需了解构建内容提供程序时，请参阅内容 provider 和 file provider 文档。

如果您要构建自己的 content provider，我们建议您不要将其导出按设置 android:exported至 false。请改为在提供程序中启用权限授予功能，方法是将 android:grantUriPermission 发送至 true。然后，IME 会在内容提交时授予访问内容 URI 的权限。您可以采用下列两种方法：

在 Android 7.1（API 级别 25）及更高版本中，调用 commitContent() 时，将标志参数设为 INPUT_CONTENT_GRANT_READ_URI_PERMISSION。然后，应用收到的 InputContentInfo 对象可以请求和通过调用 requestPermission() 和 releasePermission()。
在 Android 7.0（API 级别 24）及更低版本中， INPUT_CONTENT_GRANT_READ_URI_PERMISSION 会被忽略，因此请手动授予对该内容的权限。一种方法是 grantUriPermission()，但您可以实现自己的机制，满足您自己的要求。

如需测试您的 IME，请确保您的设备或模拟器具有可以接收 IME 的应用富媒体内容。您可以在 Android 7.1 或更高版本中使用 Google Messenger 应用。