> For the complete documentation index, see [llms.txt](https://docs.nubrick.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nubrick.app/editor/forms.md).

# フォームを利用する

フォームコンポーネントを利用することで、ユーザーに入力を促す簡単なサーベイを作成することが出来ます。

## フォームコンポーネント

現在は以下の4種類のコンポーネントが利用可能です。

* **Text Input** — 短文テキスト
* **Select** — 単一選択
* **Multi-select** — 複数選択
* **Switch** — True / False

## フォームキー

フォームコンポーネントはキーを持ちます。 キーは後述するコンポーネント内での入力値の展開と、入力必須項目のバリデーションに利用することが出来ます。

## 入力値の展開

利用可能な箇所で `{{ form.email }}` のように書くことで、変数を展開することが出来ます。詳細は [変数を利用する](https://docs.nubrick.app/editor/variables.md) を参照してください。 これによって、ユーザーの入力値をテキストとして表示したり、HTTPリクエストのBodyに埋め込むことが出来ます。

キーは基本的にコンポーネント全体で一意であることを推奨します。 同じキーのinputが複数存在すると入力値が競合したり、異なる種類のフォームコンポーネントに同一のキーが指定されることで、予期しない動作を招く可能性があるためです。

ただし例外として、異なるページに同じキーを持つ同じフォームコンポーネントを配置することは可能です。ページをまたいで値を引き継ぐことが出来ます。

## 入力必須項目

ボタンや画像などのブロックの **タップ時の処理** で **入力必須項目を設定** することでバリデーションができます。 指定したキーの値が適切に入力されるまで、そのタップアクションは実行できません（ボタンがDisabledになります）。

※存在しないキーを必須項目に指定した場合、ボタンは常にDisabledになります。施策の内容によっては進行不能となってしまう場合があるため注意してください。

### 判定条件

入力必須項目に指定すると、以下の通り入力が適切かどうかが判定されます。

| コンポーネント      | 有効な状態                          |
| ------------ | ------------------------------ |
| Text Input   | 空欄ではないこと。正規表現を指定している場合はマッチすること |
| Select       | 値が選択されていること                    |
| Multi-select | 値が1つ以上選択されていること                |
| Switch       | 値がOn (True) であること。             |

### Text Inputの正規表現

Text Inputには入力値を正規表現で検証することができます。

* 例: `^\S+@\S+$`（メールアドレスの簡易チェック）
* 入力が一致しないとき、任意のエラーメッセージを表示できます

#### Switch

Switchを必須項目に指定すると、**On であること** を確認します。利用規約への同意など、「入れるまで先に進めない」用途向けです。 Yes / No のように Off も有効な回答にする場合は、必須項目に含めないでください。
