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

试试 Compose 方式
Jetpack Compose 是推荐用于 Android 的界面工具包。了解如何在 Compose 中使用触控笔。
文本字段中的触控笔输入 →

借助 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 库中配置的，您无需在应用中进行额外的开发工作。

与绘制表面重叠

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

测试

Android 14 及更高版本的设备支持触控笔手写功能，前提是设备配备兼容的触控笔输入设备，并且 input method editor (IME) 支持 Android 14 触控笔手写 API。

如果您没有触控笔输入设备，请使用以下 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 版进行测试。

其他资源