Processar entrada do usuário

TextField permite que os usuários insiram e modifiquem o texto. Esta página descreve como implementar TextField, estilizar a entrada TextField e configurar outras opções de TextField, como opções de teclado e transformar visualmente a entrada do usuário.

Escolher a implementação do TextField

Há dois níveis de implementação de TextField:

1. TextField é a implementação do Material Design. Recomendamos que você escolha essa implementação, conforme segue o Material Design diretrizes:
   • O estilo padrão é sólido
   • OutlinedTextField é a versão de estilo delineado.
2. O BasicTextField permite que os usuários editem texto usando hardware ou software. mas não fornece decorações como dicas ou espaços reservados.

@Composable
fun SimpleFilledTextFieldSample() {
    var text by remember { mutableStateOf("Hello") }

    TextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}
TextSnippets.kt

@Composable
fun SimpleOutlinedTextFieldSample() {
    var text by remember { mutableStateOf("") }

    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}
TextSnippets.kt

Estilo TextField

TextField e BasicTextField têm vários parâmetros em comum para personalização. A lista completa do TextField está disponível no código-fonte do TextField (em inglês). Veja uma lista não exaustiva de alguns parâmetros úteis:

• singleLine
• maxLines
• textStyle

@Composable
fun StyledTextField() {
    var value by remember { mutableStateOf("Hello\nWorld\nInvisible") }

    TextField(
        value = value,
        onValueChange = { value = it },
        label = { Text("Enter text") },
        maxLines = 2,
        textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
        modifier = Modifier.padding(20.dp)
    )
}
TextSnippets.kt

Recomendamos usar TextField em vez de BasicTextField quando seu design exige uma TextField ou OutlinedTextField do Material Design. No entanto, BasicTextField precisa ser usado ao criar designs que não precisam das decorações da especificação do Material Design.

Dar estilo à entrada com a API Brush

Você pode usar a API Brush para criar estilos mais avançados no TextField. A seção a seguir descreve como usar um pincel para adicionar um gradiente colorido à entrada TextField.

Para mais informações sobre como usar a API Brush para definir o estilo de textos, consulte Ative o estilo avançado com a API Brush.

Cuidado: o uso atual da API Brush em TextStyle é experimental. As APIs experimentais podem mudar no futuro.

Implementar gradientes coloridos usando TextStyle

Para implementar um gradiente colorido enquanto você digita em um TextField, defina o pincel de sua escolha como um TextStyle para o TextField. Neste exemplo, usamos um pincel integrado com um linearGradient para conferir o efeito de gradiente do arco-íris conforme o texto é digitado no TextField.

var text by remember { mutableStateOf("") }
val brush = remember {
    Brush.linearGradient(
        colors = rainbowColors
    )
}
TextField(
    value = text, onValueChange = { text = it }, textStyle = TextStyle(brush = brush)
)
TextSnippets.kt

Observação: use a função remember para manter o pincel na horizontal recomposições, quando o estado TextField muda em cada novo caractere digitado.

Figura 3. Usar buildAnnotatedString e SpanStyle, junto com linearGradient, para personalizar apenas um trecho de texto.

Definir opções do teclado

O TextField permite definir opções de configuração do teclado, como o layout dele, ou ativar a correção automática, caso haja suporte. Algumas opções podem não ser garantidas se o teclado de software não estiver de acordo com as opções apresentadas aqui. Esta é a lista de teclados compatíveis opções:

• capitalization
• autoCorrect
• keyboardType
• imeAction

Formatar entrada

O TextField permite definir uma VisualTransformation no valor de entrada, como substituir caracteres por * para senhas ou inserir hifens a cada quatro (4) dígitos em número de cartão de crédito:

@Composable
fun PasswordTextField() {
    var password by rememberSaveable { mutableStateOf("") }

    TextField(
        value = password,
        onValueChange = { password = it },
        label = { Text("Enter password") },
        visualTransformation = PasswordVisualTransformation(),
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password)
    )
}
TextSnippets.kt

Mais exemplos estão disponíveis no código-fonte de VisualTransformationSamples.

Limpar entrada

Uma tarefa comum ao editar o texto é remover os caracteres iniciais ou transformar a string de entrada sempre que ela mudar.

Como modelo, suponha que o teclado possa fazer edições grandes e arbitrárias em cada onValueChange. Isso pode acontecer, por exemplo, se o usuário usar a correção automática, substituir uma palavra por um emoji ou usar outros recursos de edição inteligentes. Para processar a ação corretamente, programe qualquer lógica de transformação com o pressuposto de que o texto atual transmitido para o método onValueChange não está relacionado aos valores anteriores ou aos próximos que vão ser transmitidos para onValueChange.

Para implementar um campo de texto que não aceita zeros à esquerda, remova todos esses zeros sempre que o valor mudar.

@Composable
fun NoLeadingZeroes() {
    var input by rememberSaveable { mutableStateOf("") }
    TextField(
        value = input,
        onValueChange = { newText ->
            input = newText.trimStart { it == '0' }
        }
    )
}
TextSnippets.kt

Para controlar a posição do cursor ao limpar o texto, use a sobrecarga TextFieldValue da função TextField como parte do estado.

Práticas recomendadas com estado

Confira a seguir uma série de práticas recomendadas para definir e atualizar o estado TextField e evitar problemas de entrada no app.

• Use MutableState para representar o estado TextField: evite usar streams reativos, como StateFlow, para representar o estado TextField, porque essas estruturas podem introduzir atrasos assíncronos.

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}
TextSnippets.kt

• Evitar atrasos para atualizar o estado: ao chamar onValueChange, atualize seu TextField de forma síncrona e imediata:

// SignUpViewModel.kt

class SignUpViewModel(private val userRepository: UserRepository) : ViewModel() {

    var username by mutableStateOf("")
        private set

    fun updateUsername(input: String) {
        username = input
    }
}

// SignUpScreen.kt

@Composable
fun SignUpScreen(/*...*/) {

    OutlinedTextField(
        value = viewModel.username,
        onValueChange = { username -> viewModel.updateUsername(username) }
        /*...*/
    )
}
TextSnippets.kt

• Onde definir o estado: se o estado TextField exigir que a empresa validações lógicas à medida que digita, é correto elevar o estado para sua ViewModel. Caso contrário, use elementos combináveis ou uma classe detentora de estado como a fonte da verdade. Para saber mais sobre onde elevar seu estado, consulte a documentação de elevação de estado.

Observação: para mais informações sobre essas práticas recomendadas, consulte a postagem do blog Gerenciamento de estado eficaz para TextField no Compose.