Entrada da stylus em campos de texto

A biblioteca androidx.compose.material3 do Jetpack permite que os usuários escrevam em qualquer componente TextField em qualquer app usando uma stylus.

Figura 1. Entrada manuscrita com uma stylus.

Para ativar a entrada de stylus por padrão, adicione a dependência da biblioteca ao arquivo build.gradle do app:

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

A escrita à mão com stylus é ativada por padrão em todos os componentes TextField no Android 14 e versões mais recentes e na dependência androidx.compose.foundation:foundation:1.7.0. O modo de escrita à mão é iniciado para um TextField quando um evento de movimento de stylus é detectado nos limites de escrita à mão do componente.

Os limites da escrita à mão incluem 40 dp de padding vertical e 10 dp de padding horizontal ao redor do campo de entrada.

Campo de entrada com retângulo ao redor indicando os limites para detecção de eventos de movimento da stylus.
Figura 2. Limites de escrita à mão de componentes TextField.

A escrita à mão com a stylus não é compatível com campos TextField quando o editor de método de entrada é solicitado com KeyboardType.Password.

Delegação de entrada

Os apps podem mostrar elementos de interface do usuário de marcador de posição que parecem campos de entrada de texto, mas são apenas elementos estáticos sem capacidade de entrada de texto. Os campos de pesquisa são um exemplo comum. Tocar no elemento estático da interface aciona uma transição para uma nova interface que contém um campo de entrada de texto funcional focado para entrada.

Figura 3. Delegação de entrada de um elemento estático da interface para um campo de entrada de texto.

Delegação de entrada da stylus

Use as APIs de delegação de escrita à mão para oferecer suporte à entrada de escrita à mão com caneta stylus em campos de entrada de marcador de posição (consulte handwritingDetector e handwritingHandler). O elemento de interface do marcador de posição é configurado para delegar a escrita à mão a um campo de entrada funcional. Para conferir um exemplo de implementação, consulte HandwritingDetectorSample.kt.

O modo de escrita à mão com stylus é iniciado quando o campo de entrada funcional ganha foco e cria um InputConnection.

Figura 4. Delegação de entrada da stylus de um elemento estático da interface para um campo de entrada de texto.

Teste

A escrita à mão com stylus é compatível com dispositivos Android 14 e versões mais recentes que têm um dispositivo de entrada de stylus compatível e um editor de método de entrada (IME) que oferece suporte às APIs de escrita à mão com stylus do Android 14.

Se você não tiver um dispositivo de entrada de stylus, simule a entrada de stylus em qualquer dispositivo com acesso root (incluindo emuladores) usando os seguintes comandos do Android Debug Bridge (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

Use a versão Beta do Gboard para testar se você estiver usando um dispositivo que não seja compatível com stylus.

Outros recursos

Anterior
Visão geral
Avançar
Recursos avançados da stylus