form 0.0.3+1 form: ^0.0.3+1 copied to clipboard
Uma forma simples e poderosa para manipulação de formulários em flutter.
Form #
Uma forma simples e poderosa para manipulação de formulários em flutter. 🚀 ⚡
ATENÇÃO: API Experimental #
O form
atualmente está em sua versão beta. As API disnibilizadas são totalmente funcionais, mas como foram recém lançadas, não tem testes e nem maturidade o suficiente para garantir sua estabilidade. Essas APIs podem sofrer muitas alterações até que uma versão estável seja lançada. Qualquer ajuda será muito bem vinda, seja através de issues ou de PRs.
Criar um formulário com validação #
Os aplicativos geralmente exigem que os usuários insiram informações em um campo de texto. Por exemplo, você pode exigir que os usuários efetuem login com uma combinação de endereço de email e senha.
Para tornar os aplicativos seguros e fáceis de usar, verifique se as informações que o usuário forneceu são válidas. Se o usuário tiver preenchido corretamente o formulário, processe as informações. Se o usuário enviar informações incorretas, exiba uma mensagem de erro amigável informando o que deu errado.
Neste exemplo, saiba como adicionar validação a um formulário que possui um único campo de texto usando as seguintes etapas:
- Crie um
FormInput
com uma tag única para identifica-lo. - Adicione um
Input
com as validações necessárias - Crie um botão para validar e enviar o formulário
1. Crie um FormInput
com uma tag única para identifica-lo.
Primeiro, crie um FormInput
. O FormInput
widget atua como um contêiner para agrupar e validar vários campos de formulário.
Ao criar o formulário, forneça uma tag. Isso identifica exclusivamente o FormInput
e permite a validação do formulário em uma etapa posterior.
// Define a custom FormInput widget.
class MyCustomForm extends StatelessWidget {
@override
Widget build(BuildContext context) {
// Build a FormInput widget.
return FormInput(
// This tag uniquely identifies the FormInput
// widget and allows validation of the form.
tag: "myCustomForm",
child: Column(
children: <Widget>[
// Add Inputs and RaisedButton here.
],
),
);
}
}
2. Adicione um Input
com as validações necessárias
Embora FormInput
esteja no lugar, não há como os usuários digitarem texto nele. Esse é o trabalho de um Input
. O Input
renderiza um campo de texto no estilo material design e pode exibir erros de validação quando eles ocorrem.
Valide a entrada fornecendo uma lista de Validator
para o Input
.
Input(
validators: [
Validators.required,
],
);
💡 Dica: Você pode personalizar a mensagem de erro usando o método
Validator.msg(errorText)
Validators.required..msg("Please enter some text")
3. Crie um botão para validar e enviar o formulário
Agora que você possui um formulário com um campo de texto, forneça um botão no qual o usuário possa tocar para enviar as informações.
Quando o usuário tentar enviar o formulário, verifique se o formulário é válido. Se estiver, exiba uma mensagem de sucesso. Se não estiver (o campo de texto não possui conteúdo), exibir a mensagem de erro.
RaisedButton(
onPressed: () {
// validate returns true if the form is valid, otherwise false.
if (FormInput.get("myCustomForm").validate()) {
// If the form is valid, display a snackbar. In the real world,
// you'd often call a server or save the information in a database.
Scaffold.of(context)
.showSnackBar(SnackBar(content: Text('Processing Data')));
}
},
child: Text('Submit'),
);
Veja esse exemplo para mais informações
Recuperar o valor de um campo de texto #
Recuperar o texto que um usuário inseriu em um campo de texto usando o form
é muito simples, basta adicionar uma tag
ao widget Input
e usar Input.get(tag).text
para recuperar este valor.
Algumas informações sobre a propriedade tag
:
- A
tag
pode ser qualquer valor e será usada para identificar o input. - A
tag
informada deve ser única. - Usar a mesma
tag
em mais de umInput
resultará em um erro.
Input(
tag: "username", // Defina uma tag ao input para identifica-lo
);
// Retorna o texto que o usuário inseriu no input
// Note que o parametro passado para o método `Input.get` deve ser
// o mesmo que o informado na tag do input.
Input.get("username").text;
Veja esse exemplo para mais informações
Manipular alterações em um campo de texto #
Em alguns casos, é útil executar uma função de callback sempre que o texto em um campo de texto for alterado. Por exemplo, convém criar uma tela de pesquisa com funcionalidade de preenchimento automático, na qual deseja atualizar os resultados conforme o usuário digita.
Como você executa uma função de callback toda vez que o texto muda? Com o form
, você tem duas opções:
- Forneça um
onChanged()
retorno de chamada para oInput
. - Usando
Input.get()
.
1. Forneça um onChanged()
retorno de chamada para o Input
A abordagem mais simples é fornecer um onChanged()
retorno de chamada para o Input
. Sempre que o texto muda, o retorno de chamada é invocado.
Neste exemplo, imprima o valor atual do campo de texto no console sempre que o texto for alterado.
Input(
onChanged: (text) {
print("First input: $text");
},
);
2. Usando Input.get()
Para ser notificado quando o texto for alterado, ouça o controlador usando o addListener()
método, seguindo as seguintes etapas:
- Crie uma
tag
para oInput
. - Crie uma função para imprimir o valor mais recente.
- Ouça o controlador para alterações.
Crie uma tag
para o Input
Input(tag: "search");
Crie uma função para imprimir o valor mais recente
Você precisa de uma função para executar sempre que o texto for alterado. Crie um método que imprima o valor atual do campo de texto.
_printLatestValue(String text) {
print("Second input: $text");
}
Ouça o controlador para alterações
Por fim, ouça as alterações chamando o método _printLatestValue()
. Use o addListener()
método para esse fim. Se desejar, pode parar de ouvir as alterações a qualquer momento usando o método removeListener()
, porém, o form
cuida de de descartar esse ouvinte automaticamente quando não for mais necessário, assim como anexa-lo novamente caso seja requisitado.
⚠️ Atenção: Garanta que o
Input
já tenha sido montado antes de chamaraddListener()
. Normalmente, seaddListener
for chamado dentro de um callback na ação de um botão, ou algo semelhante, oInput
já estará montado, porém, se deseja chamaraddListener
em uminitState
, por exemplo, deverá coloca-lo dentro deWidgetsBinding.instance.addPersistentFrameCallback()
.
@override
void initState() {
super.initState();
WidgetsBinding.instance.addPersistentFrameCallback((_) {
Input.get("search").addListener(_printLatestValue);
});
}
Veja esse exemplo para mais informações
Validators #
Validator | Description |
---|---|
Validators.alpha | Check if the string contains only letters (a-zA-Z) |
Validators.alphanumeric | Check if the string str contains only letters and numbers |
Validators.ascii | Check if the string contains ASCII chars only |
Validators.base64 | Check if a string is base64 encoded |
Validators.creditCard | Check if the string is a credit card |
Validators.date | Check if the string is a date |
Validators.email | Check if the string is an email |
Validators.fullWidth | Check if the string contains any full-width chars |
Validators.halfWidth | Check if the string contains any half-width chars |
Validators.hexadecimal | Check if the string is a hexadecimal number |
Validators.hexColor | Check if the string str is a hexadecimal color |
Validators.isFloat | Check if the string is a float |
Validators.isInt | Check if the string is an integer |
Validators.json | Check if the string is valid JSON |
Validators.lowercase | Check if the string is lowercase |
Validators.mongoId | Check if the string is a valid hex-encoded representation of a MongoDB ObjectId |
Validators.multibyte | Check if the string contains one or more multibyte chars |
Validators.numeric | Check if the string contains only numbers |
Validators.required | Check if the input has some value |
Validators.surrogatePair | Check if the string contains any surrogate pairs chars |
Validators.uppercase | Check if the string is uppercase |
Validators.variableWidth | Check if the string contains a mixture of full and half-width chars |
Validators.after(dynamic date) | Check if the string is a date that's after the specified date |
Validators.byteLength(int min, [int max]) | Check if the string is a date that's before the specified date |
Validators.contains(dynamic seed) | Check if the string contains the seed |
Validators.divisibleBy(dynamic n) | Check if the string is a number that's divisible by another |
Validators.equals(dynamic comparison) | Check if the string matches the comparison |
Validators.fqnd({bool requireTld: true, bool allowUnderscores: false}) | Check if the string is a fully qualified domain name (e.g. domain.com) |
Validators.inValues(List values) | Check if the string is in a array of allowed values |
Validators.ip([dynamic version]) | Check if the string is IP version 4 or 6 |
Validators.isBefore(dynamic date) | Check if the string is a date that's before the specified date |
Validators.isbn([dynamic version]) | Check if the string is an ISBN (version 10 or 13) |
Validators.length(int min, [int max]) | Check if the length of the string str falls in a range |
Validators.matches(dynamic pattern) | Check if string matches the pattern |
Validators.maxLength(int max) | Check if the length of the input value is more than or equal to max |
Validators.minLength(int min) | Check if the length of the input value is less than or equal to min |
Validators.uuid([dynamic version]) | Check if the string is a UUID (version 3, 4 or 5) |