Controles de formulário

Visão geral dos controles de formulário incorporados.

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

Adiciona campo de texto de linha única (classe TextInput). Se o usuário não preencher o campo, retorna uma string vazia '', ou usa setNullable() para alterá-lo para retornar null.

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

Ela valida automaticamente UTF-8, apara os espaços em branco à esquerda e à direita e remove quebras de linha que poderiam ser enviadas por um atacante.

O comprimento máximo pode ser limitado usando setMaxLength(). O addFilter() permite alterar o valor inserido pelo usuário.

Você pode alterar o caractere visual de um campo de texto para tipos como search, tel, ou url usando setHtmlType(), como visto na especificação. Lembre-se de que a alteração do tipo é apenas visual e não executa funções de validação. Para o tipo url, é apropriado adicionar uma regra de URL 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 compatíveis com todos os navegadores.

O chamado valor vazio pode ser definido para o elemento, que é algo como o valor padrão, mas se o usuário não o sobrescrever, retorna uma string vazia ou null.

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

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

Adiciona um campo de texto com várias linhas (classe TextArea). Se o usuário não preencher o campo, ele retorna uma string vazia '', ou use setNullable() para alterá-lo para retornar null.

$form->addTextArea('note', 'Note:')
	->addRule($form::MaxLength, 'Your note is way too long', 10000);

Valida automaticamente o UTF-8 e normaliza as quebras de linha para \n. Ao contrário de um campo de entrada de linha única, ele não apara o espaço em branco.

O comprimento máximo pode ser limitado usando setMaxLength(). O addFilter() permite alterar o valor inserido pelo usuário. Você pode definir o chamado valor vazio usando setEmptyValue().

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

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

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

O elemento é renderizado como <input type="numeric">. Ao usar o método setHtmlType(), você pode alterar o tipo para range para exibição como controle deslizante ou para text se preferir um campo de texto padrão sem o comportamento especial de numeric.

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

Adds a field for entering a decimal number (TextInput class). Returns either float or null, if the user does not specify anything.

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

O Nette e o navegador Chrome aceitam tanto uma vírgula quanto um ponto como separadores decimais. Para disponibilizar essa funcionalidade no Firefox, é recomendável definir o atributo lang para o elemento específico ou para a página inteira, por exemplo, <html lang="cs">.

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

Adiciona campo de endereço de e-mail com verificação de validade (classe TextInput). Se o usuário não preencher o campo, devolve uma string vazia '', ou usa setNullable() para alterá-lo para retornar null.

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

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

O comprimento máximo pode ser limitado usando setMaxLength(). O addFilter() permite alterar o valor inserido pelo usuário. Você pode definir o chamado valor vazio usando setEmptyValue().

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

Adiciona o campo de senha (classe TextInput).

$form->addPassword('password', 'Password:')
	->setRequired()
	->addRule($form::MinLength, 'Password has to be at least %d characters long', 8)
	->addRule($form::Pattern, 'Password must contain a number', '.*[0-9].*');

Quando você reenviar o formulário, a entrada estará em branco. Ela valida automaticamente o UTF-8, apara os espaços em branco à esquerda e à direita e remove quebras de linha que poderiam ser enviadas por um atacante.

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

Acrescenta uma caixa de seleção ( caixa de seleção de classe). O campo retorna ou true ou false, dependendo se está marcado.

$form->addCheckbox('agree', 'I agree with terms')
	->setRequired('You must agree with our terms');

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

Adiciona lista de caixas de seleção para selecionar vários itens (classe CheckboxList). Retorna a matriz de chaves dos itens selecionados. O método getSelectedItems() retorna valores em vez de chaves.

$form->addCheckboxList('colors', 'Colors:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);

Passamos o conjunto de itens como o terceiro parâmetro, ou pelo método setItems().

Você pode usar setDisabled(['r', 'g']) para desativar itens individuais.

O elemento verifica automaticamente que não houve falsificação e que os itens selecionados são realmente um dos oferecidos e não foram desativados. O método getRawValue() pode ser usado para recuperar os itens submetidos sem esta importante verificação.

Quando os valores padrão são definidos, ele também verifica se eles são um dos itens oferecidos, caso contrário, ele lança uma exceção. Esta verificação pode ser desativada com checkDefaultValue(false).

Se estiver enviando um formulário usando o método GET, você poderá escolher um método de transferência de dados mais compacto que economize o tamanho da string de consulta. Isso é ativado pela configuração do atributo HTML do formulário:

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

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

Acrescenta botões de rádio (classe RadioList). Devolve a chave do item selecionado, ou null caso o usuário não tenha selecionado nada. O método getSelectedItem() retorna um valor em vez de uma chave.

$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);

Passamos o conjunto de itens como o terceiro parâmetro, ou pelo método setItems().

Você pode usar setDisabled(['m']) para desativar itens individuais.

O elemento verifica automaticamente que não houve falsificação e que o item selecionado é realmente um dos oferecidos e não foi desativado. O método getRawValue() pode ser usado para recuperar o item submetido sem esta importante verificação.

Quando o valor padrão é definido, ele também verifica se ele é um dos itens oferecidos, caso contrário, ele lança uma exceção. Esta verificação pode ser desativada com checkDefaultValue(false).

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

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

$countries = [
	'CZ' => 'Czech republic',
	'SK' => 'Slovakia',
	'GB' => 'United Kingdom',
];

$form->addSelect('country', 'Country:', $countries)
	->setDefaultValue('SK');

Passamos o conjunto de itens como o terceiro parâmetro, ou pelo método setItems(). A matriz de itens também pode ser bidimensional:

$countries = [
	'Europe' => [
		'CZ' => 'Czech republic',
		'SK' => 'Slovakia',
		'GB' => 'United Kingdom',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'other',
];

Para caixas seletas, o primeiro item muitas vezes tem um significado especial, serve como uma chamada para ação. Use o método setPrompt() para adicionar tal entrada.

$form->addSelect('country', 'Country:', $countries)
	->setPrompt('Pick a country');

Você pode usar setDisabled(['CZ', 'SK']) para desativar itens individuais.

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

Adiciona caixa de seleção de múltipla escolha (classe MultiSelectBox). Devolve a matriz de chaves dos itens selecionados. O método getSelectedItems() retorna valores em vez de chaves.

$form->addMultiSelect('countries', 'Countries:', $countries);

Passamos o conjunto de itens como o terceiro parâmetro, ou pelo método setItems(). A matriz de itens também pode ser bidimensional.

Você pode usar setDisabled(['CZ', 'SK']) para desativar itens individuais.

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

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

$form->addUpload('avatar', 'Avatar:')
	->addRule($form::Image, 'Avatar must be JPEG, PNG, GIF or WebP')
	->addRule($form::MaxFileSize, 'Maximum size is 1 MB', 1024 * 1024);

Se o arquivo não foi carregado corretamente, o formulário não foi enviado com sucesso e um erro é exibido. Ou seja, não é necessário verificar o método FileUpload::isOk().

Não confie no nome do arquivo original devolvido pelo método FileUpload::getName(), um cliente poderia enviar um nome de arquivo malicioso com a intenção de corromper ou invadir seu aplicativo.

As regras MimeType e Image detectam o tipo de arquivo ou imagem exigida por sua assinatura. A integridade do arquivo inteiro não é verificada. Você pode descobrir se uma imagem não está corrompida, por exemplo, ao tentar carregá-la.

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

Adiciona o campo de carregamento de múltiplos arquivos (classe UploadControl). Retorna um array de objetos FileUpload. O método FileUpload::hasFile() retornará true para cada um deles.

$form->addMultiUpload('files', 'Files:')
	->addRule($form::MaxLength, 'A maximum of %d files can be uploaded', 10);

Se um dos arquivos não for carregado corretamente, o formulário não foi enviado com sucesso e um erro é exibido. Ou seja, não é necessário verificar o método FileUpload::isOk().

Não confie nos nomes originais dos arquivos devolvidos pelo método FileUpload::getName(), um cliente poderia enviar um nome de arquivo malicioso com a intenção de corromper ou invadir 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).

Para o valor padrão, ele aceita objetos que implementam o DateTimeInterface, uma cadeia de caracteres com a hora ou um número que representa um carimbo de data/hora do UNIX. O mesmo se aplica aos argumentos de regra Min, Max ou Range, que definem a data mínima e máxima permitida.

$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Por padrão, ele retorna um objeto DateTimeImmutable. Usando o método setFormat(), você pode especificar um formato de texto ou um carimbo de data/hora:

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

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

Adiciona um campo que permite que o usuário insira facilmente o tempo composto por horas, minutos e, opcionalmente, segundos (classe DateTimeControl).

Para o valor padrão, ele aceita objetos que implementam o DateTimeInterface, uma cadeia de caracteres com a hora ou um número que representa um carimbo de data/hora do UNIX. Somente as informações de hora dessas entradas são usadas; a data é ignorada. O mesmo se aplica aos argumentos de regra Min, Max ou Range, que definem o tempo mínimo e máximo permitido. Se o valor mínimo definido for maior que o máximo, será criado um intervalo de tempo que vai até a meia-noite.

$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);

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

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

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

Adiciona um campo que permite que o usuário insira facilmente data e hora, consistindo em ano, mês, dia, horas, minutos e, opcionalmente, segundos (classe DateTimeControl).

$form->addDateTime('datetime', 'Date and Time:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));

Por padrão, ele retorna um objeto DateTimeImmutable. Usando o método setFormat(), você pode especificar um formato de texto ou um carimbo de data/hora:

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

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

Adiciona um campo de seleção de cores (classe ColorPicker). A cor é uma cadeia de caracteres no formato #rrggbb. Se o usuário não fizer uma seleção, a cor padrão retornada será o preto #000000.

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

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

Adiciona campo oculto (classe HiddenField).

$form->addHidden('userid');

Use setNullable() para mudá-lo para retornar null ao invés de um fio vazio. O addFilter() permite que você altere o valor submetido.

Embora o elemento esteja oculto, é importante perceber que seu valor ainda pode ser modificado ou falsificado por um invasor. Sempre verifique e valide minuciosamente 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 botão submeter (classe SubmitButton).

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

É possível ter mais de um botão de envio no formulário:

$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');

Para descobrir qual deles foi clicado, use:

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

Se você não quiser validar o formulário quando um botão de envio for pressionado (como Cancelar ou Pré-visualizar botões), você pode desligá-lo com setValidationScope().

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

Adiciona botão ( Botão de classe) sem função de submissão. É útil para vincular outras funcionalidades à identificação, por exemplo, uma ação JavaScript.

$form->addButton('raise', 'Raise salary')
	->setHtmlAttribute('onclick', 'raiseSalary()');

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

Adiciona botão submeter em forma de uma imagem (classe ImageButton).

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

Ao usar vários botões de envio, você pode descobrir qual deles foi clicado com $form['submit']->isSubmittedBy().

addContainer (string|int $name): Container

Adiciona um subforma ( Container classe), ou um recipiente, que pode ser tratado da mesma forma que um formulário. Isso significa que você pode usar métodos como setDefaults() ou getValues().

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

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

Os dados enviados são então devolvidos 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 (ver documentação API para uma visão geral completa):

`setDefaultValue($value)`	define o valor padrão
`getValue()`	obter valor atual
`setOmitted()`	valores omitidos
`setDisabled()`	desabilitando entradas

Renderização:

`setCaption($caption)`	altere o título do item
`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)`	define os dados de renderização

Validação:

`setRequired()`	campo obrigatório
`addRule()`	estabelecer regra de validação
`addCondition()`, `addConditionOn()`	estabelecer condição de validação
`addError($message)`	passando mensagem de erro

Os seguintes métodos podem ser chamados para o addText(), addPassword(), addTextArea(), addEmail(), addInteger() itens:

`setNullable()`	define se getValue() retorna `null` em vez de string vazia
`setEmptyValue($value)`	define o valor especial que é tratado como cadeia vazia
`setMaxLength($length)`	define o número máximo de caracteres permitidos
`addFilter($filter)`	modificando os valores de entrada

Valores omitidos

Se você não estiver interessado no valor inserido pelo usuário, podemos usar setOmitted() para omiti-lo do resultado fornecido pelo método $form->getValues() ou passado para os manipuladores. Isto é adequado para várias senhas de verificação, campos antispam, etc.

$form->addPassword('passwordVerify', 'Password again:')
	->setRequired('Fill your password again to check for typo')
	->addRule($form::Equal, 'Password mismatch', $form['password'])
	->setOmitted();

Desativação de entradas

As entradas podem ser desativadas usando setDisabled(). Uma entrada desativada não pode ser editada pelo usuário.

$form->addText('username', 'User name:')
	->setDisabled();

As entradas desabilitadas não são enviadas ao servidor pelo navegador, portanto, você não as encontrará nos dados retornados pela função $form->getValues(). Entretanto, se você definir setOmitted(false), a Nette incluirá o valor padrão nesses dados.

Quando setDisabled() é chamada, o valor da entrada é apagado por motivos de segurança. Se estiver definindo um valor padrão, é necessário fazê-lo após sua desativação:

$form->addText('username', 'User name:')
	->setDisabled()
	->setDefaultValue($userName);

Uma alternativa às entradas desabilitadas são os campos com o atributo HTML readonly, que são enviados ao servidor pelo navegador. Embora o campo seja apenas legível, é importante perceber que seu valor ainda pode ser modificado ou falsificado por um invasor.

Controles personalizados

Além de uma ampla gama de controles embutidos no formulário, você pode adicionar controles personalizados ao formulário da seguinte forma:

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

A forma é um descendente da classe Container e os elementos são descendentes de Componente.

Há uma maneira de definir novos métodos de formulário para adicionar elementos personalizados (por exemplo, $form->addZip()). Estes são os chamados métodos de extensão. O lado negativo é que as dicas de código nos editores não funcionarão para eles.

use Nette\Forms\Container;

// adiciona 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, 'At least 5 numbers', '[0-9]{5}');
});

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

Campos de baixo nível

Para adicionar um item ao formulário, você não precisa ligar para $form->addXyz(). Os itens do formulário podem ser introduzidos exclusivamente em modelos. Isto é útil se você, por exemplo, precisar gerar itens dinâmicos:

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

Após a apresentação, você pode recuperar os valores:

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

No primeiro parâmetro, você especifica o tipo de elemento (DataFile para type=file, DataLine para entradas de uma linha como text, password ou email e DataText para o resto). O segundo parâmetro corresponde ao atributo HTML name. Se você precisar preservar chaves, você pode combinar o primeiro parâmetro com DataKeys. Isto é útil para select, radioList ou checkboxList.

O getHttpData() retorna entrada higienizada. Neste caso, será sempre um conjunto de cordas UTF-8 válidas, não importando o que o atacante tenha enviado pelo formulário. É uma alternativa ao trabalho com $_POST ou $_GET diretamente, se você quiser receber dados seguros.