Elementos de Formulário

Visão geral dos elementos de formulário padrão.

addText (string|int $name, $label=null, ?int $cols=null, ?int $maxLength=null): TextInput

Adiciona um campo de texto de linha única (classe TextInput). Se o usuário não preencher o campo, retorna uma string vazia '', ou usando setNullable() pode-se especificar que retorne null.

$form->addText('name', 'Nome:')
	->setRequired()
	->setNullable();

Valida automaticamente UTF-8, remove espaços à esquerda e à direita e remove quebras de linha que um invasor poderia enviar.

O comprimento máximo pode ser limitado usando setMaxLength(). Modificar o valor inserido pelo usuário é possível com addFilter().

Usando setHtmlType(), é possível alterar o caractere visual do campo de texto para tipos como search, tel ou url, veja a especificação. Lembre-se que a alteração do tipo é apenas visual e não substitui a função de validação. Para o tipo url, é apropriado adicionar uma regra URL de validação específica.

Para outros tipos de entrada, como number, range, email, date, datetime-local, time e color, use métodos especializados como addInteger, addFloat, addEmail addDate, addTime, addDateTime e addColor, que garantem a validação do lado do servidor. Os tipos month e week ainda não são totalmente suportados em todos os navegadores.

Ao elemento pode ser definido o chamado empty-value, que é algo como um valor padrão, mas se o usuário não o alterar, o elemento retorna uma string vazia ou null.

$form->addText('phone', 'Telefone:')
	->setHtmlType('tel')
	->setEmptyValue('+55');

addTextArea (string|int $name, $label=null): TextArea

Adiciona um campo para inserir texto multilinha (classe TextArea). Se o usuário não preencher o campo, retorna uma string vazia '', ou usando setNullable() pode-se especificar que retorne null.

$form->addTextArea('note', 'Nota:')
	->addRule($form::MaxLength, 'A nota é muito longa', 10000);

Valida automaticamente UTF-8 e normaliza os separadores de linha para \n. Ao contrário do campo de entrada de linha única, não ocorre remoção de espaços.

O comprimento máximo pode ser limitado usando setMaxLength(). Modificar o valor inserido pelo usuário é possível com addFilter(). É possível definir o chamado empty-value usando setEmptyValue().

addInteger (string|int $name, $label=null): TextInput

Adiciona um campo para inserir um número inteiro (classe TextInput). Retorna um inteiro ou null se o usuário não inserir nada.

$form->addInteger('year', 'Ano:')
	->addRule($form::Range, 'O ano deve estar no intervalo de %d a %d.', [1900, 2023]);

O elemento é renderizado como <input type="number">. Usando o método setHtmlType(), é possível alterar o tipo para range para exibição na forma de um controle deslizante, ou para text, se preferir um campo de texto padrão sem o comportamento especial do tipo number.

addFloat (string|int $name, $label=null): TextInput

Adiciona um campo para inserir um número decimal (classe TextInput). Retorna um float ou null se o usuário não inserir nada.

$form->addFloat('level', 'Nível:')
	->setDefaultValue(0)
	->addRule($form::Range, 'O nível deve estar no intervalo de %d a %d.', [0, 100]);

Nette e o navegador Chrome aceitam tanto vírgula quanto ponto como separador decimal. Para que essa funcionalidade esteja disponível também no Firefox, é recomendado definir o atributo lang para o elemento específico ou para a página inteira, por exemplo, <html lang="pt-BR">.

addEmail (string|int $name, $label=null, int $maxLength=255): TextInput

Adiciona um campo para inserir um endereço de e-mail (classe TextInput). Se o usuário não preencher o campo, retorna uma string vazia '', ou usando setNullable() pode-se especificar que retorne null.

$form->addEmail('email', 'E-mail:');

Verifica se o valor é um endereço de e-mail válido. Não verifica se o domínio realmente existe, apenas a sintaxe é verificada. Valida automaticamente UTF-8, remove espaços à esquerda e à direita.

addPassword (string|int $name, $label=null, ?int $cols=null, ?int $maxLength=null): TextInput

Adiciona um campo para inserir uma senha (classe TextInput).

$form->addPassword('password', 'Senha:')
	->setRequired()
	->addRule($form::MinLength, 'A senha deve ter pelo menos %d caracteres', 8)
	->addRule($form::Pattern, 'Deve conter um dígito', '.*[0-9].*');

Ao reexibir o formulário, o campo estará vazio. Valida automaticamente UTF-8, remove espaços à esquerda e à direita e remove quebras de linha que um invasor poderia enviar.

addCheckbox (string|int $name, $caption=null): Checkbox

Adiciona uma caixa de seleção (classe Checkbox). Retorna o valor true ou false, dependendo se está marcada.

$form->addCheckbox('agree', 'Concordo com os termos')
	->setRequired('É necessário concordar com os termos');

addCheckboxList (string|int $name, $label=null, ?array $items=null): CheckboxList

Adiciona caixas de seleção para escolher vários itens (classe CheckboxList). Retorna um array das chaves dos itens selecionados. O método getSelectedItems() retorna os valores em vez das chaves.

$form->addCheckboxList('colors', 'Cores:', [
	'r' => 'vermelho',
	'g' => 'verde',
	'b' => 'azul',
]);

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método setItems().

Usando setDisabled(['r', 'g']), é possível desativar itens individuais.

O elemento verifica automaticamente se não houve falsificação e se os itens selecionados estão realmente entre os oferecidos e não foram desativados. O método getRawValue() permite obter os itens enviados sem essa importante verificação.

Ao definir os itens selecionados padrão, também verifica se eles estão entre os oferecidos, caso contrário, lança uma exceção. Essa verificação pode ser desativada usando checkDefaultValue(false).

Se você enviar o formulário pelo método GET, pode escolher um método de transmissão de dados mais compacto, que economiza o tamanho da query string. Ele é ativado definindo o atributo HTML do formulário:

$form->setHtmlAttribute('data-nette-compact');

addRadioList (string|int $name, $label=null, ?array $items=null): RadioList

Adiciona botões de opção (classe RadioList). Retorna a chave do item selecionado, ou null se o usuário não selecionou nada. O método getSelectedItem() retorna o valor em vez da chave.

$sex = [
	'm' => 'masculino',
	'f' => 'feminino',
];
$form->addRadioList('gender', 'Sexo:', $sex);

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método setItems().

Usando setDisabled(['m', 'f']), é possível desativar itens individuais.

O elemento verifica automaticamente se não houve falsificação e se o item selecionado está realmente entre os oferecidos e não foi desativado. O método getRawValue() permite obter o item enviado sem essa importante verificação.

Ao definir o item selecionado padrão, também verifica se ele está entre os oferecidos, caso contrário, lança uma exceção. Essa verificação pode ser desativada usando checkDefaultValue(false).

addSelect (string|int $name, $label=null, ?array $items=null, ?int $size=null): SelectBox

Adiciona uma caixa de seleção (classe SelectBox). Retorna a chave do item selecionado, ou null se o usuário não selecionou nada. O método getSelectedItem() retorna o valor em vez da chave.

$countries = [
	'BR' => 'Brasil',
	'PT' => 'Portugal',
	'GB' => 'Reino Unido',
];

$form->addSelect('country', 'País:', $countries)
	->setDefaultValue('BR');

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método setItems(). Os itens também podem ser um array bidimensional:

$countries = [
	'Europa' => [
		'CZ' => 'República Tcheca',
		'SK' => 'Eslováquia',
		'GB' => 'Reino Unido',
	],
	'CA' => 'Canadá',
	'US' => 'EUA',
	'?'  => 'outro',
];

Nas caixas de seleção, o primeiro item geralmente tem um significado especial, servindo como um prompt para ação. Para adicionar tal item, use o método setPrompt().

$form->addSelect('country', 'País:', $countries)
	->setPrompt('Escolha um país');

Usando setDisabled(['CZ', 'SK']), é possível desativar itens individuais.

addMultiSelect (string|int $name, $label=null, ?array $items=null, ?int $size=null): MultiSelectBox

Adiciona uma caixa de seleção para escolher vários itens (classe MultiSelectBox). Retorna um array das chaves dos itens selecionados. O método getSelectedItems() retorna os valores em vez das chaves.

$form->addMultiSelect('countries', 'Países:', $countries);

O array de itens oferecidos é passado como terceiro parâmetro ou pelo método setItems(). Os itens também podem ser um array bidimensional.

Usando setDisabled(['CZ', 'SK']), é possível desativar itens individuais.

addUpload (string|int $name, $label=null): UploadControl

Adiciona um campo para upload de arquivo (classe UploadControl). Retorna um objeto FileUpload, mesmo que o usuário não tenha enviado nenhum arquivo, o que pode ser verificado pelo método FileUpload::hasFile().

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'O avatar deve ser JPEG, PNG, GIF, WebP ou AVIF.')
	->addRule($form::MaxFileSize, 'O tamanho máximo é 1 MB.', 1024 * 1024 /* 1 MB em bytes */);

Se o arquivo não for carregado corretamente, o formulário não é enviado com sucesso e um erro é exibido. Ou seja, em caso de envio bem-sucedido, não é necessário verificar o método FileUpload::isOk().

Nunca confie no nome original do arquivo retornado pelo método FileUpload::getName(), o cliente pode ter enviado um nome de arquivo malicioso com a intenção de danificar ou hackear sua aplicação.

As regras MimeType e Image detectam o tipo necessário com base na assinatura do arquivo e não verificam sua integridade. Se a imagem está danificada pode ser verificado, por exemplo, tentando carregá-la.

addMultiUpload (string|int $name, $label=null): UploadControl

Adiciona um campo para upload de vários arquivos de uma vez (classe UploadControl). Retorna um array de objetos FileUpload. O método FileUpload::hasFile() em cada um deles retornará true.

$form->addMultiUpload('files', 'Arquivos:')
	->addRule($form::MaxLength, 'No máximo %d arquivos podem ser enviados', 10);

Se algum arquivo não for carregado corretamente, o formulário não é enviado com sucesso e um erro é exibido. Ou seja, em caso de envio bem-sucedido, não é necessário verificar o método FileUpload::isOk().

Nunca confie nos nomes originais dos arquivos retornados pelo método FileUpload::getName(), o cliente pode ter enviado um nome de arquivo malicioso com a intenção de danificar ou hackear sua aplicação.

addDate (string|int $name, $label=null): DateTimeControl

Adiciona um campo que permite ao usuário inserir facilmente uma data composta por ano, mês e dia (classe DateTimeControl).

Como valor padrão, aceita objetos que implementam a interface DateTimeInterface, uma string com a hora, ou um número representando um timestamp UNIX. O mesmo se aplica aos argumentos das regras Min, Max ou Range, que definem a data mínima e máxima permitida.

$form->addDate('date', 'Data:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'A data deve ter pelo menos um mês.', new DateTime('-1 month'));

Por padrão, retorna um objeto DateTimeImmutable, com o método setFormat() você pode especificar o formato de texto ou timestamp:

$form->addDate('date', 'Data:')
	->setFormat('Y-m-d');

addTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Adiciona um campo que permite ao usuário inserir facilmente uma hora composta por horas, minutos e opcionalmente segundos (classe DateTimeControl).

Como valor padrão, aceita objetos que implementam a interface DateTimeInterface, uma string com a hora, ou um número representando um timestamp UNIX. Desses inputs, apenas a informação de tempo é utilizada, a data é ignorada. O mesmo se aplica aos argumentos das regras Min, Max ou Range, que definem a hora mínima e máxima permitida. Se o valor mínimo definido for maior que o máximo, cria-se um intervalo de tempo que ultrapassa a meia-noite.

$form->addTime('time', 'Hora:', withSeconds: true)
	->addRule($form::Range, 'A hora deve estar no intervalo de %d a %d.', ['12:30', '13:30']);

Por padrão, retorna um objeto DateTimeImmutable (com a data de 1º de janeiro do ano 1), com o método setFormat() você pode especificar o formato de texto:

$form->addTime('time', 'Hora:')
	->setFormat('H:i');

addDateTime (string|int $name, $label=null, bool $withSeconds=false): DateTimeControl

Adiciona um campo que permite ao usuário inserir facilmente data e hora compostas por ano, mês, dia, horas, minutos e opcionalmente segundos (classe DateTimeControl).

$form->addDateTime('datetime', 'Data e hora:')
	->setDefaultValue(new \DateTime)
	->addRule($form::Min, 'A data deve ter pelo menos um mês.', new \DateTime('-1 month'));

Por padrão, retorna um objeto DateTimeImmutable, com o método setFormat() você pode especificar o formato de texto ou timestamp:

$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);

addColor (string|int $name, $label=null): ColorPicker

Adiciona um campo para seleção de cor (classe ColorPicker). A cor é uma string no formato #rrggbb. Se o usuário não fizer a escolha, retorna a cor preta #000000.

$form->addColor('color', 'Cor:')
	->setDefaultValue('#3C8ED7');

addHidden (string|int $name, ?string $default=null): HiddenField

Adiciona um campo oculto (classe HiddenField).

$form->addHidden('userid');

Usando setNullable(), pode-se definir que retorne null em vez de uma string vazia. Modificar o valor enviado é possível com addFilter().

Embora o elemento esteja oculto, é importante notar que o valor ainda pode ser modificado ou falsificado por um invasor. Sempre verifique e valide cuidadosamente todos os valores recebidos no lado do servidor para evitar riscos de segurança associados à manipulação de dados.

addSubmit (string|int $name, $caption=null): SubmitButton

Adiciona um botão de envio (classe SubmitButton).

$form->addSubmit('submit', 'Enviar');

No formulário, é possível ter vários botões de envio:

$form->addSubmit('register', 'Registrar');
$form->addSubmit('cancel', 'Cancelar');

Para descobrir qual deles foi clicado, use:

if ($form['register']->isSubmittedBy()) {
  // ...
}

Se você não quiser validar o formulário inteiro ao pressionar o botão (por exemplo, para botões Cancelar ou Visualizar), use setValidationScope().

addButton (string|int $name, $caption): Button

Adiciona um botão (classe Button) que não tem função de envio. Pode ser usado para alguma outra função, por exemplo, chamar uma função JavaScript ao clicar.

$form->addButton('raise', 'Aumentar salário')
	->setHtmlAttribute('onclick', 'raiseSalary()');

addImageButton (string|int $name, ?string $src=null, ?string $alt=null): ImageButton

Adiciona um botão de envio na forma de uma imagem (classe ImageButton).

$form->addImageButton('submit', '/path/to/image');

Ao usar vários botões de envio, é possível descobrir qual foi clicado usando $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Adiciona um subformulário (classe Container), ou seja, um contêiner, ao qual é possível adicionar outros elementos da mesma forma que os adicionamos ao formulário. Os métodos setDefaults() ou getValues() também funcionam.

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Seu nome:');
$sub1->addEmail('email', 'Email:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Seu nome:');
$sub2->addEmail('email', 'Email:');

Os dados enviados retornam como uma estrutura multidimensional:

[
	'first' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
	'second' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
]

Visão geral das configurações

Para todos os elementos, podemos chamar os seguintes métodos (visão geral completa na documentação da API):

`setDefaultValue($value)`	define o valor padrão
`getValue()`	obtém o valor atual
`setOmitted()`	Omissão de valor
`setDisabled()`	Desativação de elementos

Renderização:

`setCaption($caption)`	altera o rótulo do elemento
`setTranslator($translator)`	define o tradutor
`setHtmlAttribute($name, $value)`	define o atributo HTML do elemento
`setHtmlId($id)`	define o atributo HTML `id`
`setHtmlType($type)`	define o atributo HTML `type`
`setHtmlName($name)`	define o atributo HTML `name`
`setOption($key, $value)`	configurações para renderização

Validação:

`setRequired()`	elemento obrigatório
`addRule()`	define a regra de validação
`addCondition()`, `addConditionOn()`	define a condição de validação
`addError($message)`	passagem de mensagem de erro

Para os elementos addText(), addPassword(), addTextArea(), addEmail(), addInteger(), podem ser chamados os seguintes métodos:

`setNullable()`	define se getValue() retorna `null` em vez de string vazia
`setEmptyValue($value)`	define um valor especial que é considerado uma string vazia
`setMaxLength($length)`	define o número máximo de caracteres permitidos
`addFilter($filter)`	modificação da entrada

Omissão de valor

Se o valor preenchido pelo usuário não nos interessa, podemos omiti-lo do resultado do método $form->getValues() ou dos dados passados para os handlers usando setOmitted(). Isso é útil para várias senhas de verificação, elementos antispam, etc.

$form->addPassword('passwordVerify', 'Senha para verificação:')
	->setRequired('Por favor, digite a senha novamente para verificação')
	->addRule($form::Equal, 'As senhas não coincidem', $form['password'])
	->setOmitted();

Desativação de elementos

Elementos podem ser desativados usando setDisabled(). Tal elemento não pode ser editado pelo usuário.

$form->addText('username', 'Nome de usuário:')
	->setDisabled();

Elementos desativados não são enviados pelo navegador para o servidor, portanto, você não os encontrará nos dados retornados pela função $form->getValues(). No entanto, se você definir setOmitted(false), o Nette incluirá seu valor padrão nesses dados.

Ao chamar setDisabled(), por razões de segurança, o valor do elemento é apagado. Se você estiver definindo um valor padrão, é necessário fazê-lo após desativá-lo:

$form->addText('username', 'Nome de usuário:')
	->setDisabled()
	->setDefaultValue($userName);

Uma alternativa aos elementos desativados são elementos com o atributo HTML readonly, que o navegador envia para o servidor. Embora o elemento seja apenas para leitura, é importante notar que seu valor ainda pode ser modificado ou falsificado por um invasor.

Elementos personalizados

Além da ampla gama de elementos de formulário embutidos, você pode adicionar elementos personalizados ao formulário desta forma:

$form->addComponent(new DateInput('Data:'), 'date');
// sintaxe alternativa: $form['date'] = new DateInput('Data:');

O formulário é um descendente da classe Container e os elementos individuais são descendentes de Component.

Existe uma maneira de definir novos métodos de formulário para adicionar elementos personalizados (por exemplo, $form->addZip()). São os chamados métodos de extensão. A desvantagem é que a sugestão nos editores não funcionará para eles.

use Nette\Forms\Container;

// adicionamos o método addZip(string $name, ?string $label = null)
Container::extensionMethod('addZip', function (Container $form, string $name, ?string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::Pattern, 'Pelo menos 5 números', '[0-9]{5}');
});

// uso
$form->addZip('zip', 'CEP:');

Elementos de baixo nível

Também é possível usar elementos que escrevemos apenas no template e não os adicionamos ao formulário com algum dos métodos $form->addXyz(). Por exemplo, ao listar registros do banco de dados sem saber antecipadamente quantos serão e quais serão seus IDs, e queremos exibir uma caixa de seleção ou botão de opção para cada linha, basta codificá-lo no template:

{foreach $items as $item}
	<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}

E após o envio, obtemos o valor:

$data = $form->getHttpData($form::DataText, 'sel[]');
$data = $form->getHttpData($form::DataText | $form::DataKeys, 'sel[]');

onde o primeiro parâmetro é o tipo do elemento (DataFile para type=file, DataLine para entradas de linha única como text, password, email, etc. e DataText para todos os outros) e o segundo parâmetro sel[] corresponde ao atributo HTML name. O tipo do elemento pode ser combinado com o valor DataKeys, que preserva as chaves dos elementos. Isso é especialmente útil para select, radioList e checkboxList.

O essencial é que getHttpData() retorna um valor sanitizado, neste caso, será sempre um array de strings UTF-8 válidas, independentemente do que um invasor tente enviar ao servidor. É análogo ao trabalho direto com $_POST ou $_GET, mas com a diferença essencial de que sempre retorna dados limpos, como você está acostumado com os elementos padrão dos formulários Nette.