文本字段中的手写笔输入

Jetpack 的 androidx.compose.material3 库使用户能够使用触控笔在任何应用程序中的任何 TextField 组件中进行书写。

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

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

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "LATEST_EXTENSION_VERSION"
    }

    kotlinOptions {
        jvmTarget = "LATEST_JVM_VERSION"
    }
}

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

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = 'LATEST_EXTENSION_VERSION'
    }

    kotlinOptions {
        jvmTarget = 'LATEST_JVM_VERSION'
    }
}

TextField

在 Android 14 及更高版本和 androidx.compose.foundation:foundation:1.7.0 依赖项上，默认情况下所有 TextField 组件都启用了触控笔手写功能。当在组件的手写边界内检测到触控笔运动事件时，将为 TextField 启动手写模式。

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

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

输入委托

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

触控笔输入委托

使用手写委托 API 为占位符输入字段支持触控笔手写输入（请参阅 handwritingDetector 和 handwritingHandler）。占位符 UI 元素配置为将手写功能委托给功能性输入字段。有关示例实现，请参阅 HandwritingDetectorSample.kt。

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

测试

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

其他资源

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