文本字段中的触控笔输入

Android 14（API 级别 34）及更高版本允许用户使用触控笔在任意应用的任意文本输入字段中书写。Android 文本输入字段，包括 EditText 组件和 WebView 文本微件，默认支持触控笔输入。

但是，如果您的应用需要自定义文本输入字段（请参阅自定义文本编辑器），或者布局复杂，文本输入字段叠加在绘制表面上，则需要自定义应用。

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

`EditText`

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

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

Input field with surrounding rectangle indicating the bounds for detection of stylus motion events. — **图 2.** `EditText` 字段的手写边界。

输入委托

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

图 3. 输入从静态 UI 元素委托给文本输入字段。

触控笔输入委托

使用手写委托 API 支持占位符输入字段的触控笔手写输入（请参阅 setHandwritingDelegatorCallback() 和 setIsHandwritingDelegate()）。占位符 UI 元素配置为将手写委托给功能性输入字段，例如

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

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

图 4. 触控笔输入从静态 UI 元素委托给文本输入字段。

Material Design

com.google.android.material.search 库提供了 SearchBar 和 SearchView 类，以便于实现占位符 UI 模式。

占位符搜索视图和功能性搜索视图通过 setUpWithSearchBar() 关联。

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

与绘制表面重叠

如果您的应用有绘制表面，并且文本字段叠加在该表面上，您可能需要停用触控笔手写功能以允许用户绘制。请参阅 setAutoHandwritingEnabled()。

测试

支持 Android 14 触控笔手写 API 的 Android 14 及更高版本设备，只要其配备兼容的触控笔输入设备和输入法编辑器 (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 版进行测试。

其他资源

Material Design — 文本字段
自定义文本编辑器