A TextField
permite que os usuários insiram e modifiquem texto. Esta página descreve como você
pode implementar TextField
, estilizar a entrada TextField
e configurar
outras opções de TextField
, como opções de teclado e recursos de transformação visual
entrada do usuário.
Escolher a implementação de TextField
Há dois níveis de implementação de TextField
:
TextField
é a implementação do Material Design. Recomendamos que você escolha essa implementação, conforme segue o Material Design diretrizes:- 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") } ) }
@Composable fun SimpleOutlinedTextFieldSample() { var text by remember { mutableStateOf("") } OutlinedTextField( value = text, onValueChange = { text = it }, label = { Text("Label") } ) }
Estilo TextField
TextField
e BasicTextField
têm vários parâmetros em comum
para personalização. A lista completa de TextField
está disponível na origem TextField
código.
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) ) }
Recomendamos usar TextField
em vez de BasicTextField
quando seu design exige uma
TextField
ou OutlineTextField
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.
Entrada de estilo com a API Brush
Você pode usar a API Brush para ter um estilo mais avançado no TextField
. O
seção a seguir descreve como usar o 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.
Implementar gradientes coloridos usando TextStyle
Para implementar um gradiente colorido enquanto você digita em uma TextField
, defina o pincel
de sua escolha como TextStyle
para a TextField
. Neste exemplo, usamos
pincel integrado com um linearGradient
para conferir o efeito de gradiente de arco-íris
o texto é digitado na TextField
.
var text by remember { mutableStateOf("") } val brush = remember { Brush.linearGradient( colors = rainbowColors ) } TextField( value = text, onValueChange = { text = it }, textStyle = TextStyle(brush = brush) )
![Uso de buildAnnotationdString e SpanStyle, junto com linearGradient, para personalizar apenas um pedaço de texto.](https://developer.android.com/static/develop/ui/compose/images/text-textfieldgradient.gif?authuser=6&hl=pt)
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) ) }
Mais exemplos estão disponíveis no código-fonte do 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' } } ) }
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 TextField
.
para evitar problemas de entrada no app.
- Use
MutableState
para representar o estadoTextField
: evite usando streams reativos, comoStateFlow
, para representarTextField
, já que essas estruturas podem introduzir atrasos assíncronos.
class SignUpViewModel : ViewModel() { var username by mutableStateOf("") private set /* ... */ }
- Evitar atrasos para atualizar o estado: ao chamar
onValueChange
, atualize seuTextField
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) } /*...*/ ) }
- Onde definir o estado: se o estado
TextField
exigir que a empresa validações lógicas à medida que digita, é correto elevar o estado para suaViewModel
. 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.
Recomendados para você
- Observação: o texto do link aparece quando o JavaScript está desativado.
- Como arquitetar a interface do Compose
- Estado e Jetpack Compose
- Salvar o estado da interface no Compose