文本字段中的手写笔输入

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 — 文本字段
• 处理用户输入