在文本字段中使用触控笔输入

借助 Android 14（API 级别 34）及更高版本，用户可以使用触控笔在任何应用的任何文本输入字段中写入内容。Android 文本输入字段（包括 EditText 组件和 WebView 文本 widget）默认支持触控笔输入。

不过，如果您的应用需要自定义文本输入字段（请参阅自定义文本编辑器），或者其布局较为复杂，其中文本输入字段叠加在绘图界面上，则您需要自定义应用。

图 1. 使用触控笔手写输入的内容。

EditText

在 Android 14 及更高版本中，系统默认为所有 EditText 字段启用触控笔手写功能。在视图的手写边界内检测到触控笔动作事件时，系统会针对 EditText 启动手写模式。

手写边界包括视图周围的 40 dp 的垂直内边距和 10 dp 的水平内边距。使用 setHandwritingBoundsOffsets() 调整手写边界。使用 setAutoHandwritingEnabled(false) 停用手写功能。

输入字段，周围的矩形指示检测触控笔动作事件的边界。
图 2. EditText 字段的手写边界。

输入委托

应用可以显示看起来像文本输入字段，但实际上只是没有文本输入功能的静态界面元素的占位符界面元素。搜索字段就是一个常见的示例。点按静态界面元素会触发过渡到新界面，该界面包含用于输入焦点的功能文本输入字段。

图 3. 从静态界面元素到文本输入字段的输入委托。

触控笔输入委托

使用手写委托 API 支持在占位符输入字段中使用触控笔手写输入（请参阅 setHandwritingDelegatorCallback() 和 setIsHandwritingDelegate()）。占位符界面元素配置为将手写内容委托给可正常使用的输入字段，例如：

Kotlin

if (Build.VERSION.SDK_INT >= 34) {
    placeholderInputField.setHandwritingDelegatorCallback {
        showAndFocusDelegateInputField()
    }
    delegateInputField.setIsHandwritingDelegate(true)
}

Java

if (Build.VERSION.SDK_INT >= 34) {
    placeholderInputField.setHandwritingDelegatorCallback(this::showAndFocusInputFieldDelegate);
    delegateInputField.setIsHandwritingDelegate(true);
}

触控笔在占位符文本输入字段视图上移动会调用回调。该回调会触发界面转换，以显示并聚焦功能输入字段。回调实现通常与占位符元素上的点击监听器的实现相同。当功能输入字段创建 InputConnection 时，触控笔手写模式便会启动。

图 4. 从静态界面元素到文本输入字段的触控笔输入委托。

Material Design

com.google.android.material.search 库提供 SearchBar 和 SearchView 类，以协助实现占位符界面模式。

占位符和功能搜索视图与 setUpWithSearchBar() 相关联。

手写委托在 Material 库中进行配置，无需在应用中进行额外的开发。

与绘图表面重叠

如果您的应用的绘图界面上存在叠加文本字段的绘图界面，您可能需要停用触控笔手写功能，才能允许用户进行绘图。请参阅 setAutoHandwritingEnabled()。

测试

搭载 Android 14 及更高版本的设备支持触控笔手写，设备具有兼容的触控笔输入设备和支持 Android 14 触控笔手写 API 的输入法 (IME)。

如果您没有触控笔输入设备，请使用以下 Android 调试桥 (adb) 命令在具有 root 访问权限的任何设备（包括模拟器）上模拟触控笔输入：


// Android 14
adb shell setprop persist.debug.input.simulate_stylus_with_touch true && adb shell stop && adb shell start

// Android 15 and higher
// Property takes effect after screen reconfiguration such as orientation change.
adb shell setprop debug.input.simulate_stylus_with_touch true

如果您使用的是不支持触控笔的设备，请使用 Gboard Beta 版进行测试。

其他资源