フォーム要素

標準的なフォーム要素の概要。

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

一行テキストフィールド（クラスTextInput）を追加します。ユーザーがフィールドを空にした場合、空の文字列 '' を返します。または、setNullable() を使用して null を返すように指定できます。

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

自動的にUTF-8を検証し、左右の空白をトリミングし、攻撃者が送信する可能性のある改行を削除します。

最大長は setMaxLength() で制限できます。ユーザーが入力した値を変更するには、addFilter() を使用します。

setHtmlType() を使用して、テキストフィールドの視覚的な特性を search、tel、url などのタイプに変更できます（仕様を参照）。タイプの変更は視覚的なものであり、検証機能を代替するものではないことに注意してください。url タイプの場合、特定の検証URLルールを追加することをお勧めします。

number、range、email、date、datetime-local、time、color などの他の入力タイプについては、addInteger、addFloat、addEmail、addDate、addTime、addDateTime、addColor などの専用メソッドを使用してください。これらはサーバーサイドの検証を保証します。month および week タイプは、まだすべてのブラウザで完全にサポートされているわけではありません。

要素には、いわゆる空の値（empty-value）を設定できます。これはデフォルト値のようなものですが、ユーザーが変更しない場合、要素は空の文字列または null を返します。

$form->addText('phone', '電話番号:')
	->setHtmlType('tel')
	->setEmptyValue('+81');

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

複数行テキストを入力するためのフィールド（クラスTextArea）を追加します。ユーザーがフィールドを空にした場合、空の文字列 '' を返します。または、setNullable() を使用して null を返すように指定できます。

$form->addTextArea('note', '備考:')
	->addRule($form::MaxLength, '備考が長すぎます', 10000);

自動的にUTF-8を検証し、改行区切り文字を \n に正規化します。一行入力フィールドとは異なり、空白のトリミングは行われません。

最大長は setMaxLength() で制限できます。ユーザーが入力した値を変更するには、addFilter() を使用します。setEmptyValue() を使用して、いわゆる空の値を設定できます。

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

整数を入力するためのフィールド（クラスTextInput）を追加します。ユーザーが何も入力しない場合は、整数または null を返します。

$form->addInteger('year', '年:')
	->addRule($form::Range, '年は %d から %d の範囲である必要があります。', [1900, 2023]);

要素は <input type="numeric"> としてレンダリングされます。setHtmlType() メソッドを使用して、タイプを range に変更してスライダーとして表示したり、numeric タイプの特別な動作なしで標準のテキストフィールドを好む場合は text に変更したりできます。

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

浮動小数点数を入力するためのフィールド（クラスTextInput）を追加します。ユーザーが何も入力しない場合は、浮動小数点数または null を返します。

$form->addFloat('level', 'レベル:')
	->setDefaultValue(0)
	->addRule($form::Range, 'レベルは %d から %d の範囲である必要があります。', [0, 100]);

NetteとChromeブラウザは、小数点区切り文字としてカンマとピリオドの両方を受け入れます。Firefoxでもこの機能を利用できるようにするには、特定の要素またはページ全体に lang 属性を設定することをお勧めします。例：<html lang="ja">。

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

メールアドレスを入力するためのフィールド（クラスTextInput）を追加します。ユーザーがフィールドを空にした場合、空の文字列 '' を返します。または、setNullable() を使用して null を返すように指定できます。

$form->addEmail('email', 'メールアドレス:');

値が有効なメールアドレスであるかどうかを検証します。ドメインが実際に存在するかどうかは検証されず、構文のみが検証されます。自動的にUTF-8を検証し、左右の空白をトリミングします。

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

パスワードを入力するためのフィールド（クラスTextInput）を追加します。

$form->addPassword('password', 'パスワード:')
	->setRequired()
	->addRule($form::MinLength, 'パスワードは少なくとも %d 文字必要です', 8)
	->addRule($form::Pattern, '数字を含める必要があります', '.*[0-9].*');

フォームを再表示すると、フィールドは空になります。自動的にUTF-8を検証し、左右の空白をトリミングし、攻撃者が送信する可能性のある改行を削除します。

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

チェックボックス（クラスCheckbox）を追加します。チェックされているかどうかに応じて、true または false の値を返します。

$form->addCheckbox('agree', '利用規約に同意します')
	->setRequired('利用規約に同意する必要があります');

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

複数の項目を選択するためのチェックボックス（クラスCheckboxList）を追加します。選択された項目のキーの配列を返します。getSelectedItems() メソッドはキーの代わりに値を返します。

$form->addCheckboxList('colors', '色:', [
	'r' => '赤',
	'g' => '緑',
	'b' => '青',
]);

提供される項目の配列は、3番目のパラメータまたは setItems() メソッドで渡します。

setDisabled(['r', 'g']) を使用して、個々の項目を無効にできます。

要素は、改ざんが発生していないこと、選択された項目が実際に提供されたものの1つであり、無効にされていないことを自動的にチェックします。getRawValue() メソッドを使用すると、この重要なチェックなしで送信された項目を取得できます。

デフォルトで選択された項目を設定する場合も、それらが提供されたものの1つであることを確認します。そうでない場合は例外をスローします。このチェックは checkDefaultValue(false) で無効にできます。

GET メソッドでフォームを送信する場合、クエリ文字列のサイズを節約する、よりコンパクトなデータ転送方法を選択できます。これは、フォームのHTML属性を設定することで有効になります：

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

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

ラジオボタン（クラスRadioList）を追加します。選択された項目のキーを返します。ユーザーが何も選択しない場合は null を返します。getSelectedItem() メソッドはキーの代わりに値を返します。

$sex = [
	'm' => '男性',
	'f' => '女性',
];
$form->addRadioList('gender', '性別:', $sex);

提供される項目の配列は、3番目のパラメータまたは setItems() メソッドで渡します。

setDisabled(['m', 'f']) を使用して、個々の項目を無効にできます。

デフォルトで選択された項目を設定する場合も、それが提供されたものの1つであることを確認します。そうでない場合は例外をスローします。このチェックは checkDefaultValue(false) で無効にできます。

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

セレクトボックス（クラスSelectBox）を追加します。選択された項目のキーを返します。ユーザーが何も選択しない場合は null を返します。getSelectedItem() メソッドはキーの代わりに値を返します。

$countries = [
	'CZ' => 'チェコ共和国',
	'SK' => 'スロバキア',
	'GB' => 'イギリス',
];

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

提供される項目の配列は、3番目のパラメータまたは setItems() メソッドで渡します。項目は2次元配列にすることもできます：

$countries = [
	'Europe' => [
		'CZ' => 'チェコ共和国',
		'SK' => 'スロバキア',
		'GB' => 'イギリス',
	],
	'CA' => 'カナダ',
	'US' => 'アメリカ合衆国',
	'?'  => 'その他',
];

セレクトボックスでは、最初の項目が特別な意味を持つことがよくあります。アクションを促すために使用されます。このような項目を追加するには setPrompt() メソッドを使用します。

$form->addSelect('country', '国:', $countries)
	->setPrompt('国を選択してください');

setDisabled(['CZ', 'SK']) を使用して、個々の項目を無効にできます。

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

複数の項目を選択するためのセレクトボックス（クラスMultiSelectBox）を追加します。選択された項目のキーの配列を返します。getSelectedItems() メソッドはキーの代わりに値を返します。

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

提供される項目の配列は、3番目のパラメータまたは setItems() メソッドで渡します。項目は2次元配列にすることもできます。

setDisabled(['CZ', 'SK']) を使用して、個々の項目を無効にできます。

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

ファイルアップロード用のフィールド（クラスUploadControl）を追加します。ユーザーがファイルを送信しなかった場合でも、FileUpload オブジェクトを返します。これは FileUpload::hasFile() メソッドで確認できます。

$form->addUpload('avatar', 'アバター:')
	->addRule($form::Image, 'アバターはJPEG、PNG、GIF、WebP、またはAVIFである必要があります。')
	->addRule($form::MaxFileSize, '最大サイズは1MBです。', 1024 * 1024);

ファイルが正しくアップロードされなかった場合、フォームは正常に送信されず、エラーが表示されます。つまり、正常に送信された場合、FileUpload::isOk() メソッドを確認する必要はありません。

FileUpload::getName() メソッドによって返される元のファイル名を決して信用しないでください。クライアントは、アプリケーションを破損またはハッキングする意図で悪意のあるファイル名を送信した可能性があります。

MimeType および Image ルールは、ファイルのシグネチャに基づいて要求されたタイプを検出し、その整合性を検証しません。画像が破損していないかどうかは、たとえば読み込みを試みることで確認できます。

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

複数のファイルを一度にアップロードするためのフィールド（クラスUploadControl）を追加します。FileUpload オブジェクトの配列を返します。それぞれの FileUpload::hasFile() メソッドは true を返します。

$form->addMultiUpload('files', 'ファイル:')
	->addRule($form::MaxLength, '最大 %d ファイルまでアップロードできます', 10);

いずれかのファイルが正しくアップロードされなかった場合、フォームは正常に送信されず、エラーが表示されます。つまり、正常に送信された場合、FileUpload::isOk() メソッドを確認する必要はありません。

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

ユーザーが年、月、日で構成される日付を簡単に入力できるフィールド（クラスDateTimeControl）を追加します。

デフォルト値として、DateTimeInterface インターフェースを実装するオブジェクト、時間を含む文字列、またはUNIXタイムスタンプを表す数値を受け入れます。最小および最大許容日付を定義する Min、Max、または Range ルールの引数についても同様です。

$form->addDate('date', '日付:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, '日付は少なくとも1か月前である必要があります。', new DateTime('-1 month'));

デフォルトでは DateTimeImmutable オブジェクトを返します。setFormat() メソッドを使用して、テキスト形式またはタイムスタンプを指定できます：

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

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

ユーザーが時、分、およびオプションで秒で構成される時間を簡単に入力できるフィールド（クラスDateTimeControl）を追加します。

デフォルト値として、DateTimeInterface インターフェースを実装するオブジェクト、時間を含む文字列、またはUNIXタイムスタンプを表す数値を受け入れます。これらの入力からは時間情報のみが使用され、日付は無視されます。最小および最大許容時間を定義する Min、Max、または Range ルールの引数についても同様です。最小値が最大値より大きい場合、深夜を超える時間範囲が作成されます。

$form->addTime('time', '時間:', withSeconds: true)
	->addRule($form::Range, '時間は %d から %d の範囲である必要があります。', ['12:30', '13:30']);

デフォルトでは DateTimeImmutable オブジェクト（日付は1月1日）を返します。setFormat() メソッドを使用して、テキスト形式を指定できます：

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

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

ユーザーが年、月、日、時、分、およびオプションで秒で構成される日付と時間を簡単に入力できるフィールド（クラスDateTimeControl）を追加します。

$form->addDateTime('datetime', '日時:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, '日付は少なくとも1か月前である必要があります。', new DateTime('-1 month'));

デフォルトでは DateTimeImmutable オブジェクトを返します。setFormat() メソッドを使用して、テキスト形式またはタイムスタンプを指定できます：

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

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

色を選択するためのフィールド（クラスColorPicker）を追加します。色は #rrggbb 形式の文字列です。ユーザーが選択しない場合、黒色 #000000 が返されます。

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

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

隠しフィールド（クラスHiddenField）を追加します。

$form->addHidden('userid');

setNullable() を使用して、空の文字列の代わりに null を返すように設定できます。送信された値を変更するには、addFilter() を使用します。

要素は隠されていますが、値は依然として攻撃者によって変更または偽造される可能性があることを認識することが重要です。データの操作に関連するセキュリティリスクを回避するために、サーバー側で受信したすべての値を常に徹底的に検証および検証してください。

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

送信ボタン（クラスSubmitButton）を追加します。

$form->addSubmit('submit', '送信');

フォームには複数の送信ボタンを含めることができます：

$form->addSubmit('register', '登録');
$form->addSubmit('cancel', 'キャンセル');

どちらがクリックされたかを確認するには、次を使用します：

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

ボタンを押したときにフォーム全体を検証したくない場合（たとえば、キャンセルまたはプレビューボタンの場合）、setValidationScope() を使用します。

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

送信機能を持たないボタン（クラスButton）を追加します。したがって、クリック時にJavaScript関数を呼び出すなど、他の機能に使用できます。

$form->addButton('raise', '給与を上げる')
	->setHtmlAttribute('onclick', 'raiseSalary()');

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

画像形式の送信ボタン（クラスImageButton）を追加します。

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

複数の送信ボタンを使用する場合、$form['submit']->isSubmittedBy() を使用してどちらがクリックされたかを確認できます。

addContainer (string|int $name): Container

サブフォーム（クラスContainer）、つまりコンテナを追加します。これには、フォームに追加するのと同じ方法で他の要素を追加できます。setDefaults() または getValues() メソッドも機能します。

$sub1 = $form->addContainer('first');
$sub1->addText('name', 'あなたの名前:');
$sub1->addEmail('email', 'メールアドレス:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'あなたの名前:');
$sub2->addEmail('email', 'メールアドレス:');

送信されたデータは、多次元構造として返されます：

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

設定の概要

すべての要素で、次のメソッドを呼び出すことができます（完全な概要はAPIドキュメントを参照）：

`setDefaultValue($value)`	デフォルト値を設定します
`getValue()`	現在の値を取得します
`setOmitted()`	#値の省略
`setDisabled()`	#要素の無効化

レンダリング：

`setCaption($caption)`	要素のキャプションを変更します
`setTranslator($translator)`	トランスレータを設定します
`setHtmlAttribute($name, $value)`	要素のHTML属性を設定します
`setHtmlId($id)`	HTML属性 `id` を設定します
`setHtmlType($type)`	HTML属性 `type` を設定します
`setHtmlName($name)`	HTML属性 `name` を設定します
`setOption($key, $value)`	レンダリング設定

検証：

`setRequired()`	必須要素
`addRule()`	検証ルールを設定します
`addCondition()`, `addConditionOn()`	検証条件を設定します
`addError($message)`	エラーメッセージの受け渡し

addText()、addPassword()、addTextArea()、addEmail()、addInteger() 要素では、次のメソッドを呼び出すことができます：

`setNullable()`	getValue() が空の文字列の代わりに `null` を返すかどうかを設定します
`setEmptyValue($value)`	空の文字列と見なされる特別な値を設定します
`setMaxLength($length)`	許可される最大文字数を設定します
`addFilter($filter)`	入力の変更

値の省略

ユーザーが入力した値に関心がない場合は、setOmitted() を使用して $form->getValues() メソッドの結果またはハンドラに渡されるデータから省略できます。これは、さまざまな確認用パスワード、アンチスパム要素などに役立ちます。

$form->addPassword('passwordVerify', '確認用パスワード:')
	->setRequired('確認のため、もう一度パスワードを入力してください')
	->addRule($form::Equal, 'パスワードが一致しません', $form['password'])
	->setOmitted();

要素の無効化

要素は setDisabled() で無効にできます。このような要素はユーザーが編集できません。

$form->addText('username', 'ユーザー名:')
	->setDisabled();

無効化された要素はブラウザによってサーバーに送信されないため、$form->getValues() 関数によって返されるデータには含まれません。ただし、setOmitted(false) を設定すると、Netteはこれらのデータにデフォルト値を含めます。

setDisabled() を呼び出すと、セキュリティ上の理由から要素の値が削除されます。デフォルト値を設定する場合は、無効化した後に行う必要があります：

$form->addText('username', 'ユーザー名:')
	->setDisabled()
	->setDefaultValue($userName);

無効化された要素の代替として、HTML属性 readonly を持つ要素があります。これはブラウザによってサーバーに送信されます。要素は読み取り専用ですが、その値は依然として攻撃者によって変更または偽造される可能性があることを認識することが重要です。

カスタム要素

組み込みの幅広いフォーム要素に加えて、次の方法でフォームにカスタム要素を追加できます：

$form->addComponent(new DateInput('日付:'), 'date');
// 代替構文: $form['date'] = new DateInput('日付:');

フォームはContainerクラスの子であり、個々の要素はComponentの子です。

カスタム要素を追加するための新しいフォームメソッド（例：$form->addZip()）を定義する方法があります。これは拡張メソッドと呼ばれます。欠点は、エディタでの補完が機能しないことです。

use Nette\Forms\Container;

// メソッド 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, '少なくとも5桁の数字', '[0-9]{5}');
});

// 使用法
$form->addZip('zip', '郵便番号:');

低レベル要素

テンプレートにのみ記述し、$form->addXyz() メソッドのいずれかでフォームに追加しない要素を使用することもできます。たとえば、データベースからレコードを出力し、事前にいくつあり、どのようなIDを持つかわからず、各行にチェックボックスまたはラジオボタンを表示したい場合、テンプレートでコーディングするだけで十分です：

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

そして、送信後に値を確認します：

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

ここで、最初のパラメータは要素のタイプ（type=file の場合は DataFile、text、password、email などの一行入力の場合は DataLine、その他すべての場合は DataText）であり、2番目のパラメータ sel[] はHTML属性 name に対応します。要素のタイプは、要素のキーを保持する DataKeys 値と組み合わせることができます。これは、特に select、radioList、checkboxList に役立ちます。

重要なのは、getHttpData() がサニタイズされた値を返すことです。この場合、攻撃者がサーバーに何を送信しようとしても、常に有効なUTF-8文字列の配列になります。これは、$_POST または $_GET を直接操作するのと似ていますが、重要な違いは、常にクリーンなデータを返すことです。これは、標準のNetteフォーム要素で慣れているとおりです。