フォームの要素

標準のフォームの要素の一覧です。

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

1 行のテキストの入力欄を足します（クラス 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 の種類は、まだすべてのブラウザが十分に対応していません。

要素には「空の値」を設定できます。これは既定値のように振る舞いますが、利用者がそれを変えなければ、要素は空の文字列か null を返します。

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

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

複数行のテキストの入力欄を足します（クラス TextArea）。利用者がその項目を埋めなければ空の文字列 '' を返します。setNullable() を使えば代わりに null を返させられます。

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

UTF-8 を自動的に検証し、改行を \n にそろえます。1 行の入力欄と違って、空白の切り詰めは起きません。

長さの上限は setMaxLength() で決められます。addFilter()メソッドで、利用者が入力した値を変えられます。空の値は setEmptyValue() で設定できます。

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

整数を入力する欄を足します（クラス TextInput）。整数を返すか、利用者が何も入力しなければ null を返します。

$form->addInteger('year', '年:')
	->addRule($form::Range, '年は %d から %d のあいだでなければなりません。', [1900, 2023]);

この要素は <input type="number"> として描かれます。setHtmlType() メソッドで、種類を range にしてスライダーとして表示させたり、number の種類の特別な振る舞いのないふつうのテキストの項目がよければ text にしたりできます。

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

浮動小数点数を入力する欄を足します（クラス TextInput）。float を返すか、利用者が何も入力しなければ null を返します。

$form->addFloat('level', 'レベル:')
	->setDefaultValue(0)
	->addRule($form::Range, 'レベルは %d から %d のあいだでなければなりません。', [0, 100]);

Nette と Chrome のブラウザは、小数点としてコンマもドットも受け付けます。Firefox でもこれを働かせるには、その要素かページ全体に lang 属性を設定するとよいでしょう。たとえば <html lang="en"> です。

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

メールアドレスを入力する欄を足します（クラス TextInput）。利用者がその項目を埋めなければ空の文字列 '' を返します。setNullable() を使えば代わりに null を返させられます。

$form->addEmail('email', 'メール:');

値が正しいメールアドレスかを検証します。そのドメインが実在するかは調べず、書式だけを確かめます。UTF-8 を自動的に検証し、前後の空白を取り除きます。

長さの上限は setMaxLength() で決められます。addFilter()メソッドで、利用者が入力した値を変えられます。空の値は setEmptyValue() で設定できます。

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

パスワードの入力欄を足します（クラス TextInput）。

$form->addPassword('password', 'パスワード:')
	->setRequired()
	->addRule($form::MinLength, 'パスワードは %d 文字以上でなければなりません', 8)
	->addRule($form::Pattern, 'パスワードには数字を含めてください', '.*[0-9].*');

フォームがもう一度表示されるとき、この項目は空になります。UTF-8 を自動的に検証し、前後の空白を取り除き、攻撃者が送るかもしれない改行を取り除きます。

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

チェックボックスを足します（クラス Checkbox）。入っているかどうかに応じて true か false を返します。

$form->addCheckbox('agree', '利用条件に同意します')
	->setRequired('利用条件に同意していただく必要があります');

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

複数の項目を選ぶためのチェックボックスの一覧を足します（クラス CheckboxList）。選ばれた項目のキーの配列を返します。getSelectedItems() メソッドは、選ばれた項目をキーと値の組として返します。

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

提示する項目の配列は第 3 パラメータで渡すか、setItems() メソッドで渡します。setItems() の第 2 引数に false を渡すと、値がキーとしても使われます。

個々の項目を無効にするには setDisabled(['r', 'g']) を使います。

この要素は、偽造がなかったこと、そして選ばれた項目が本当に提示されたものの中にあって無効にされていないことを自動的に確かめます。この大事な検査なしに送信された項目を取り出したいなら getRawValue() メソッドを使えます。

既定で選ばれる項目を設定するときも、それが提示されたものの中にあるかを確かめ、なければ例外を投げます。この検査は checkDefaultValue(false) で切れます。

フォームを GET メソッドで送信しているなら、クエリ文字列の大きさを節約する、もっとこぢんまりしたデータの送り方を選べます。フォームに HTML の属性を設定して有効にします。

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

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

ラジオボタンを足します（クラス RadioList）。選ばれた項目のキーを返し、利用者が何も選ばなければ null を返します。getSelectedItem() メソッドはキーではなく値を返します。

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

提示する項目の配列は第 3 パラメータで渡すか、setItems() メソッドで渡します。

個々の項目を無効にするには setDisabled(['m']) を使います。

addSelect (string $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 次元の配列にもできます（optgroup を表します）。

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

セレクトボックスでは、最初の項目が特別な意味を持ち、操作を促す役目を果たすことがよくあります。そうした項目を足すには setPrompt() メソッドを使います。

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

個々の項目を無効にするには setDisabled(['CZ', 'SK']) を使います。

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

複数の項目を選ぶためのセレクトボックスを足します（クラス MultiSelectBox）。選ばれた項目のキーの配列を返します。getSelectedItems() メソッドは、選ばれた項目をキーと値の組として返します。

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

提示する項目の配列は第 3 パラメータで渡すか、setItems() メソッドで渡します。項目は 2 次元の配列にもできます。

個々の項目を無効にするには setDisabled(['CZ', 'SK']) を使います。

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

ファイルのアップロードの項目を足します（クラス UploadControl）。利用者がファイルをアップロードしなかった場合も FileUploadオブジェクトを返します。それは FileUpload::hasFile() メソッドで確かめられます。setNullable() を使うと、ファイルがアップロードされなかったときに FileUpload オブジェクトではなく null を返させられます。

$form->addUpload('avatar', 'アバター:')
	->addRule($form::Image, 'アバターは JPEG、PNG、GIF、WebP、AVIF でなければなりません。')
	->addRule($form::MaxFileSize, '大きさの上限は 1 MB です。', 1024 * 1024);

ファイルが正しくアップロードされなければ、フォームの送信は成功せず、エラーが表示されます。つまり送信が成功したなら、FileUpload::isOk() メソッドを確かめる必要はありません。

FileUpload::getName() メソッドが返すもとのファイル名は決して信じないでください。クライアントは、あなたのアプリケーションを壊したり乗っ取ったりするつもりで、悪意のあるファイル名を送っているかもしれません。

MimeType と Image の規則は、求める種類をファイルの署名から見分けるもので、その健全さは確かめません。画像が壊れているかどうかは、たとえば読み込んでみることで判断できます。

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

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

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

どれかのファイルが正しくアップロードされなければ、フォームの送信は成功せず、エラーが表示されます。つまり送信が成功したなら、ファイルごとに FileUpload::isOk() メソッドを確かめる必要はありません。

addDate (string $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 $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 月 1 日になります）。setFormat() メソッドでテキストの書式を指定できます。

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

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

年、月、日、時、分、そして必要なら秒から成る日付と時刻の両方を簡単に入力できる項目を足します（クラス DateTimeControl）。

既定値としては、DateTimeInterface を実装するオブジェクト、時刻を含む文字列、UNIX タイムスタンプを表す数を受け取ります。許される最小と最大の日付と時刻を定める Min、Max、Range の規則の引数も同じです。

$form->addDateTime('datetime', '日付と時刻:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, '日付は少なくとも 1 か月前でなければなりません。', new DateTime('-1 month'));

既定では DateTimeImmutable オブジェクトを返します。setFormat() メソッドで、テキストの書式やタイムスタンプを指定できます。

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

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

色を選ぶ項目を足します（クラス ColorPicker）。色は #rrggbb の書式の文字列として返されます。利用者が何も選ばなければ、黒 #000000 を返します。

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

addHidden (string $name, mixed $default=null): HiddenField

隠しの項目を足します（クラス HiddenField）。

$form->addHidden('userid');

setNullable() を使うと、空の文字列ではなく null を返させられます。addFilter()メソッドで、送信された値を変えられます。

この要素は隠れていますが、その値は攻撃者に書き換えられたり偽られたりしうることを忘れないでください。データの改ざんにまつわるセキュリティリスクを防ぐために、受け取ったすべての値をサーバー側でいつも入念に確かめ、検証してください。

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

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

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

ハンドラは onClick イベントに結び付ける代わりに、第 3 パラメータ $onSubmit としてボタンに直接渡せます。

$form->addSubmit('submit', '送信', function (SubmitButton $button, $data): void {
	// ...
});

フォームには送信ボタンを 2 つ以上置けます。

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

どれが押されたかを判断するには次のようにします。

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

ボタンを押したときにフォーム全体を検証したくないなら（たとえば キャンセル や プレビュー のボタン）、setValidationScope()を使ってください。

addButton (string $name, $caption=null): Button

送信の働きを持たないボタンを足します（クラス Button）。ですからほかの用途に、たとえばクリックしたときに JavaScript の関数を呼ぶのに使えます。

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

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

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

$form->addImageButton('submit', '/path/to/image.png', '送信');

送信ボタンを複数使うときは、$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` 属性を設定します
`setOption($key, $value)`	描画のオプションを設定します

検証:

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

addText()、addPassword()、addTextArea()、addEmail()、addInteger()、addFloat() の要素では、次のメソッドを呼べます。

`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('日付:');

そうした要素を、送信されたデータの読み出しや検証、描画も含めてどう書くかは、独立した章で説明しています。そこでは $form->addZip() のような独自の追加のメソッドを作れる拡張のメソッドについても学べます。

低水準の項目

テンプレートにだけ書かれ、$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[]');

第 1 パラメータは要素の種類（type=file なら DataFile、text、password、email などの 1 行の入力なら DataLine、そのほかはすべて DataText）で、第 2 パラメータの sel[] は HTML の name 属性に対応します。要素の種類は DataKeys の値と組み合わせられ、そうすると要素のキーが保たれます。これは select、radioList、checkboxList でとりわけ便利です。

大事なのは、getHttpData() が清められた値を返すことです。この場合、攻撃者がサーバーへ何を送ろうとしても、結果はいつも正しい UTF-8 の文字列の配列になります。これは $_POST や $_GET を直接扱うのに似ていますが、Nette の標準のフォームの要素で慣れているのと同じく、いつもきれいなデータが返るという大きな違いがあります。