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

尝试使用 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 字段的手写边界。

注意：对于具有密码输入类型的 EditText 字段，不支持触控笔手写，例如：

<EditText
    ...
    android:inputType="textPassword"
    ... />

请参见android:inputType。

输入委托

应用可以显示看似是文本输入字段的占位界面元素，但实际上这些元素只是静态界面元素，不具备文本输入功能。搜索框就是一个常见的示例。点按静态界面元素会触发向新界面的过渡，新界面包含一个可用的文本输入字段，该字段已聚焦以供输入。

图 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 版进行测试。

其他资源

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