借助 Android 14(API 级别 34)及更高版本,用户可以使用触控笔在任何应用的任何文本输入字段中写入内容。Android 文本输入字段(包括 EditText
组件和 WebView
文本 widget)默认支持触控笔输入。
不过,如果您的应用需要自定义文本输入字段(请参阅自定义文本编辑器),或者其布局较为复杂,其中文本输入字段叠加在绘图界面上,则您需要自定义应用。
EditText
在 Android 14 及更高版本中,系统默认为所有 EditText
字段启用触控笔手写功能。在视图的手写边界内检测到触控笔动作事件时,系统会针对 EditText
启动手写模式。
手写边界包括视图周围的 40 dp 的垂直内边距和 10 dp 的水平内边距。使用 setHandwritingBoundsOffsets()
调整手写边界。使用 setAutoHandwritingEnabled(false)
停用手写功能。
![输入字段,周围的矩形指示检测触控笔动作事件的边界。](https://developer.android.google.cn/static/images/develop/ui/compose/touch-input/stylus-input/shared/edittext_handwriting_bounds.png?authuser=5&hl=el)
EditText
字段的手写边界。
输入委托
应用可以显示看起来像文本输入字段,但实际上只是没有文本输入功能的静态界面元素的占位符界面元素。搜索字段就是一个常见的示例。点按静态界面元素会触发过渡到新界面,该界面包含用于输入焦点的功能文本输入字段。
触控笔输入委托
使用手写委托 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
时,触控笔手写模式便会启动。
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 版进行测试。