Android Academy · Aula

TextField e entrada do usuário

Capture texto do usuário no Compose.

TextField e entrada do usuário é uma aula grátis de Android Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Android Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Android Academy inclui 4 aulas no total.

Capturando a entrada do usuário

Quase todo aplicativo real precisa solicitar algo ao usuário: um nome, um e-mail, uma consulta de pesquisa. No Jetpack Compose, o bloco básico para inserir texto é TextField.

Nesta lição, você aprenderá a exibir um campo de texto, ler o que o usuário digita e manter o campo sincronizado com o estado do aplicativo. Essa é a base de todo formulário que você criar.

Seu primeiro TextField

Um TextField precisa de duas coisas: um value (o texto atual a ser exibido) e um retorno de chamada onValueChange (o que fazer quando o usuário digita).

O Compose é declarativo, portanto o campo não armazena o próprio texto. Você mantém o texto no estado e o fornece novamente ao campo. Esse padrão é chamado de elevação de estado.

@Composable
fun NameField() {
    var name by remember { mutableStateOf("") }

    TextField(
        value = name,
        onValueChange = { name = it }
    )
}

Como funciona o ciclo do valor

A ideia mais importante: um TextField exibe exatamente o que você passa para value. Quando o usuário pressiona uma tecla, o Compose chama onValueChange com o novo texto.

Você salva esse novo texto no estado.
As mudanças de estado acionam a recomposição.
O campo é desenhado novamente com o value atualizado.

Se você esquecer de atualizar o estado dentro de onValueChange, o campo parecerá congelado, pois value nunca mudará.

var name by remember { mutableStateOf("") }

TextField(
    value = name,
    onValueChange = { newText -> name = newText }
)

Adicionando um rótulo e um texto de dica

Um campo de texto vazio não dá ao usuário nenhuma indicação do que digitar. Adicione um label (que flutua acima do campo) e um placeholder (uma dica exibida quando o campo está vazio).

Esses pequenos detalhes tornam os formulários muito mais fáceis de entender.

var email by remember { mutableStateOf("") }

TextField(
    value = email,
    onValueChange = { email = it },
    label = { Text("Email") },
    placeholder = { Text("you@example.com") }
)

OutlinedTextField

O Material Design oferece dois estilos principais. O TextField tem um plano de fundo preenchido, enquanto o OutlinedTextField desenha uma borda ao redor do campo. Eles compartilham a mesma API, portanto trocar de um para o outro é muito simples.

Campos contornados são populares em formulários porque ficam visualmente organizados quando empilhados verticalmente.

var username by remember { mutableStateOf("") }

OutlinedTextField(
    value = username,
    onValueChange = { username = it },
    label = { Text("Username") },
    singleLine = true
)

Ícones no início e no fim

Você pode decorar um campo com ícones. Um leadingIcon aparece no início, sendo ótimo para um símbolo de pesquisa ou e-mail, e um trailingIcon aparece no fim, geralmente como um botão para limpar.

Os ícones tornam a finalidade de um campo evidente à primeira vista.

var query by remember { mutableStateOf("") }

OutlinedTextField(
    value = query,
    onValueChange = { query = it },
    label = { Text("Search") },
    leadingIcon = {
        Icon(Icons.Default.Search, contentDescription = null)
    }
)

Um botão para limpar

Um padrão comum de experiência do usuário é um pequeno "x" que limpa o campo. Mostre-o somente quando houver texto, usando o espaço trailingIcon e um IconButton.

Observe que limpar consiste apenas em definir o estado novamente como uma string vazia.

var text by remember { mutableStateOf("") }

OutlinedTextField(
    value = text,
    onValueChange = { text = it },
    label = { Text("Note") },
    trailingIcon = {
        if (text.isNotEmpty()) {
            IconButton(onClick = { text = "" }) {
                Icon(Icons.Default.Clear, contentDescription = "Clear")
            }
        }
    }
)

Uma linha versus várias linhas

Por padrão, um TextField pode crescer para várias linhas. Para itens como nome ou e-mail, defina singleLine = true para impedir que o usuário insira uma quebra de linha.

Para observações mais longas, deixe o campo com várias linhas e, opcionalmente, limite a altura com maxLines.

var bio by remember { mutableStateOf("") }

OutlinedTextField(
    value = bio,
    onValueChange = { bio = it },
    label = { Text("Bio") },
    maxLines = 4
)

Reagindo à entrada em tempo real

Como você controla o estado do texto, pode reagir a ele instantaneamente. Um exemplo clássico é mostrar abaixo do campo uma contagem de caracteres em tempo real.

Cada tecla atualiza text, que recompõe tanto o campo quanto a contagem abaixo dele.

var text by remember { mutableStateOf("") }

Column {
    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Tweet") }
    )
    Text("${text.length} / 280")
}

Transformando a entrada

Às vezes, você quer normalizar o que o usuário digita antes de armazená-lo. Dentro de onValueChange, você pode transformar o novo valor primeiro.

Aqui, forçamos um nome de usuário para letras minúsculas e removemos os espaços. Como você controla o ciclo, o campo sempre exibe a versão limpa.

var handle by remember { mutableStateOf("") }

OutlinedTextField(
    value = handle,
    onValueChange = { input ->
        handle = input.lowercase().filterNot { it.isWhitespace() }
    },
    label = { Text("Handle") },
    singleLine = true
)

Kotlin puro: limpando um identificador

A lógica de transformação acima é apenas Kotlin puro. Você pode testá-la isoladamente, sem precisar do Android. Aqui está a mesma regra de limpeza sendo executada de forma independente.

Manter uma lógica como essa em funções puras facilita a execução de testes unitários.

fun cleanHandle(input: String): String =
    input.lowercase().filterNot { it.isWhitespace() }

fun main() {
    println(cleanHandle("  John Doe "))
    println(cleanHandle("ADA Lovelace"))
}

Verificação rápida

O que acontece se o retorno de chamada onValueChange de um TextField nunca atualizar o estado passado para value?

Recapitulação

Agora você conhece os fundamentos da entrada de texto no Compose:

TextField e OutlinedTextField recebem um value e um retorno de chamada onValueChange.
Você mantém o texto em remember { mutableStateOf(...) } e o atualiza a cada mudança (elevação de estado).
label, placeholder, os ícones no início e no fim e singleLine definem a aparência e o comportamento.
Como você controla o estado, pode reagir em tempo real ou transformar a entrada enquanto o usuário digita.

A seguir: gerenciamento do estado de um formulário inteiro, não apenas de um campo.

Perguntas Frequentes

A aula “TextField e entrada do usuário” é grátis?

Sim — o texto completo de “TextField e entrada do usuário” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Android Academy, atualize para CoddyKit PRO. O curso de Android Academy inclui 4 aulas no total.

O que vou aprender em “TextField e entrada do usuário”?

Capture texto do usuário no Compose. Você pratica Android Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Android Academy?

Nenhuma experiência prévia é necessária. Android Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “TextField e entrada do usuário”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Android Academy?

Sim. Cada aula de Android Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Android Academy