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

Jetpack androidx.compose.material3 库允许用户向任意 TextField 组件写入数据， 使用触控笔创建任意应用。

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

要默认启用触控笔输入，请将库依赖项添加到应用的 build.gradle 文件：

Kotlin

dependencies {
    implementation("androidx.compose.foundation:foundation:LATEST_COMPOSE_VERSION")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "LATEST_EXTENSION_VERSION"
    }

    kotlinOptions {
        jvmTarget = "LATEST_JVM_VERSION"
    }
}

Groovy

dependencies {
    implementation 'androidx.compose.foundation:foundation:LATEST_COMPOSE_VERSION'
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = 'LATEST_EXTENSION_VERSION'
    }

    kotlinOptions {
        jvmTarget = 'LATEST_JVM_VERSION'
    }
}

TextField

默认情况下，系统会为所有 TextField 组件启用触控笔手写功能 Android 14 及更高版本 androidx.compose.foundation:foundation:1.7.0 依赖项。当触控笔移动时，TextField 会启动手写模式 事件触发。

手写边界包括 40 dp 的垂直内边距和 10 dp 的水平内边距 输入字段周围的内边距。

图 2. TextField 组件的手写边界。

使用输入法时，TextField 字段不支持触控笔手写 KeyboardType.Password 请求编辑器。

输入委托

应用可以显示占位符界面元素，这些元素看起来像是文本输入字段， 实际上只是没有文本输入功能的静态界面元素。搜索 就是一个常见的例子点按静态界面元素会触发转场 一个新界面，其中包含一个专注于输入的功能文本输入字段。

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

触控笔输入委托

使用手写委托 API 支持触控笔手写输入 占位符输入字段（请参阅 handwritingDetector 和 handwritingHandler)。占位符界面元素是 将手写内容委托给功能输入字段。示例 请参阅 HandwritingDetectorSample.kt。

当功能输入字段获得焦点时，系统会启动触控笔手写模式 会创建 InputConnection。

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

测试

搭载 Android 14 及更高版本且符合以下条件的设备支持触控笔手写功能： 兼容的触控笔输入设备和输入法 编辑器 (IME) 支持 Android 14 触控笔手写 API。

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

// 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，请使用 Gboard Beta 版进行测试 触控笔。

其他资源

• Material Design - 文本字段
• 处理用户输入