項目と入力ルール

フォームの項目には、識別キー・項目名・型・必須のほか、文字数、数値の範囲、選択肢、入力形式、確認入力、選択数、ファイルの条件などのルールを設定できます。これらのルールは公開版に固定され、送信のたびにサーバーで検証されます。このページでは、使える型、各プロパティの意味と制限、エラーのコードとメッセージを説明します。

管理画面で設定できる内容

フォーム画面の「項目・設定」の表で、次の内容を設定できます。

列	内容
識別キー	HTMLの `name` 属性やAPIで使う名前。英字で始まり、英数字・`_`・`-` を使えます（128文字まで）。フォーム内で重複できません
項目名	エラーメッセージやメールに表示される名前（255文字まで）
説明	任意の説明文（1000文字まで）
型	下の「型」の表を参照
必須	チェックすると必須項目になります
選択候補	選択・単一選択・複数選択の選択肢。1行に `値 \| 表示名` の形式で書きます。`\|` がない行は値と表示名が同じになります

1つのフォームに置ける項目は100個までです。

上の表にないルール（文字数、数値の範囲、入力形式、確認入力、選択数、ファイルの条件）は、管理API またはデプロイAPI で項目の定義に含めて設定します。管理画面で保存しても、識別キーと型が変わらない項目では、画面に表示されないこれらのルールはそのまま保持されます。型を変更した項目では保持されません。

型

管理画面の表示	型（API）	HTMLの例	保存される値
テキスト	`text`	`<input name="キー">`	文字列
複数行	`textarea`	`<textarea name="キー">`	文字列
メール	`email`	`<input type="email" name="キー">`	文字列
URL	`url`	`<input type="url" name="キー">`	文字列
数値	`number`	`<input type="number" name="キー">`	数値
はい／いいえ	`boolean`	`<input type="checkbox" name="キー" value="1">`	真偽値
日付	`date`	`<input type="date" name="キー">`	`YYYY-MM-DD` の文字列
選択	`select`	`<select name="キー">`	選択肢の値
単一選択	`radio`	`<input type="radio" name="キー" value="…">`	選択肢の値
同意	`checkbox`	`<input type="checkbox" name="キー" value="1">`	真偽値
複数選択	`checkboxes`	`<input type="checkbox" name="キー[]" value="…">`	選択肢の値の一覧
ファイル	`file`	`<input type="file" name="キー[]">`	添付ファイルの一覧
電話番号	`tel`	`<input type="tel" name="キー">`	文字列
非表示	`hidden`	`<input type="hidden" name="キー" value="…">`	文字列

文字列の値は100,000文字までです。
メールは、サーバーのメールアドレス形式のチェックを通る値だけを受け付けます。
URLは http:// または https:// で始まり、空白を含まない値だけを受け付けます。
日付は YYYY-MM-DD の形式で、実在する日付だけを受け付けます。
選択・単一選択は、選択肢の値のどれかと一致する必要があります。
電話番号の型だけでは書式をチェックしません。書式を制限するには入力形式 tel を設定します。

必須

型	必須のときに求められること	満たさないときのコード
文字列の型（テキスト、メールなど）	空でない値	`required`
数値	値があること	`required`
選択、単一選択	選択肢を選ぶこと	`required_choice`
複数選択、ファイル	1件以上	`required_choice`
同意	チェックされていること	`consent`

必須でない項目は、空のまま、または値を送らなくても受け付けます。
「はい／いいえ」は、必須にしても「いいえ」（チェックなし）で受け付けます。チェックを必須にしたい場合（個人情報の取り扱いへの同意など）は「同意」型を使います。

文字数（minlength / maxlength）

文字列の値の文字数の下限と上限です（0〜100,000の整数）。文字数は1文字ずつ数えます。
minlength は空の値には適用しません。必須でない項目は、空のままなら下限に関係なく受け付けます。

数値の範囲（min / max）

数値型の値の下限と上限です。片方だけでも指定できます。範囲外は range になります。

選択肢（options）

選択・単一選択・複数選択では、選択肢が1つ以上必要です。
各選択肢は値（value）と表示名（label）を持ち、どちらも255文字までです。値は重複できません。選択肢は100個までです。
送信されるのは値です。メールや受付一覧にも値が表示されます。

入力形式（format）

文字列の書式を制限します。空の値はチェックしません（必須かどうかは「必須」で決まります）。

`format`	使える型	受け付ける値
`tel`	電話番号、テキスト	半角数字と `(`、`)`、`+`、`-` だけからなる6文字以上の値（例: `03-1234-5678`）
`postal_code_jp`	テキスト	半角数字3桁、省略可能な `-`、半角数字4桁（例: `123-4567`、`1234567`）
`katakana`	テキスト、複数行	全角カタカナ（`ァ` から `ヴ` まで）、長音記号 `ー`、中点（`・` と半角の `･`）、`=`、`＝`、縦棒、全角・半角スペースだけからなる値

全角数字は tel と postal_code_jp で受け付けません。
ひらがなや半角カタカナ（･ を除く）は katakana で受け付けません。

確認入力（same_as）

メールアドレスの再入力のように、別の項目と同じ値であることを求めます。

{ "key": "email_confirmation", "label": "メールアドレス（確認）", "type": "email", "required": true, "public": false, "same_as": "email" }

使える型は、テキスト・メール・URL・電話番号です。確認先は同じフォームにある同じ型の項目である必要があります。
自分自身や、same_as を持つ項目は確認先にできません。
値が一致しないと same_as（「（項目名）が一致しません。」）になります。どちらかの項目にほかのエラーがある間は、一致のチェックはしません。
確認用の項目も通常の項目として保存され、メールの {{all_fields}} にも含まれます。

複数選択の件数（min_items / max_items）

複数選択で選べる件数の下限と上限です。0から選択肢の数までの整数で、下限は上限以下にします。
1件以上選ばれているときだけ適用します。「任意だが、答えるなら2つ以上」は、必須にせず min_items: 2 とします。
件数が範囲外だと items になります。選んだ値自体に問題がある間は、件数のチェックはしません。

ファイル（accept / max_size / max_items）

プロパティ	意味	既定と上限
`max_items`	1項目で送れるファイル数の上限	既定1、最大5
`min_items`	1件以上送るときの最小数	0〜5
`max_size`	1ファイルの上限（バイト）	既定・最大とも10MB（10,485,760バイト）
`accept`	受け付けるファイル形式（MIMEタイプの一覧）	既定は下の表のすべて。この中から絞り込めます

max_items を省略したファイル項目は1件だけ受け付けます。min_items を2以上にするときは、max_items も指定してください。指定しないと、項目の保存時に「〇〇でファイルを2件以上求める場合は、最大ファイル数も指定してください。」というエラーになります。

受け付けるファイル形式は次のとおりです。形式はファイル名や拡張子ではなく、ファイルの中身から判定します。

形式	MIMEタイプ
PDF	`application/pdf`
PNG	`image/png`
JPEG	`image/jpeg`
GIF	`image/gif`
WebP	`image/webp`
HEIC	`image/heic`
テキスト	`text/plain`
CSV	`text/csv`
Word（.docx）	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel（.xlsx）	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint（.pptx）	`application/vnd.openxmlformats-officedocument.presentationml.presentation`

SVG、HTML、スクリプト、圧縮ファイル、実行ファイルなど、上の表にない形式は受け付けません。
サイト全体の添付ファイルの保存容量には上限があります（既定は1GB）。上限に達すると「ファイルの保存容量が上限に達しているため受け付けできません。」になります。
ファイルは受付データとして非公開で保存され、管理画面の受付詳細からサイトの所有者だけがダウンロードできます。メールには添付しません。

ファイルの受け取り時には、次のメッセージで拒否されることがあります。HTMLフォームからの送信では、この場合ほかの項目のエラーより先にこのメッセージだけが表示されます。

メッセージ	理由
このファイル形式は受け付けていません。	許可されていない形式
ファイルサイズが上限を超えています。	`max_size` または1ファイルの上限を超えた
ファイルを受け付けない項目です。	ファイル型でない項目にファイルを送った
ファイルの保存容量が上限に達しているため受け付けできません。	サイトの保存容量の上限

説明（description）

項目の補足説明です（1000文字まで、プレーンテキスト）。フォーム定義APIで項目と一緒に返されるので、サイト側で入力欄の説明として表示できます。検証には影響しません。

定義の例

管理APIやデプロイAPIでは、項目を次のようなJSONで指定します。key・label・type・required・public は必須です。public はフォームの動作には影響しないため、通常は false を指定します（管理画面で追加した項目も false です）。

[
  { "key": "name", "label": "お名前", "type": "text", "required": true, "public": false, "maxlength": 50 },
  { "key": "kana", "label": "フリガナ", "type": "text", "required": false, "public": false, "format": "katakana", "description": "全角カタカナで入力してください" },
  { "key": "email", "label": "メールアドレス", "type": "email", "required": true, "public": false },
  { "key": "topics", "label": "興味のある分野", "type": "checkboxes", "required": false, "public": false,
    "options": [{ "value": "web", "label": "Web制作" }, { "value": "print", "label": "印刷物" }], "max_items": 2 },
  { "key": "files", "label": "資料", "type": "file", "required": false, "public": false, "max_items": 3, "max_size": 5242880, "accept": ["application/pdf"] },
  { "key": "agree", "label": "個人情報の取り扱い", "type": "checkbox", "required": true, "public": false }
]

エラーのコードとメッセージ

{label} には項目名が入ります（unknown_field では送られた名前が入ります）。

コード	メッセージ	params
`unknown_field`	定義にない項目「{label}」が含まれています。	なし
`required`	{label}を入力してください。	なし
`required_choice`	{label}を選択してください。	なし
`consent`	{label}にチェックを入れてください。	なし
`type`	{label}の値の型が不正です。	なし
`minlength`	{label}の文字数が不足しています。	`limit`
`maxlength`	{label}の文字数が上限を超えています。	`limit`
`email`	{label}のメール形式が不正です。	なし
`url`	{label}のURLが不正です。	なし
`date`	{label}の日付が不正です。	なし
`format`	{label}の入力形式が不正です。	`format`
`option`	{label}の選択肢が不正です。	なし
`option_duplicate`	{label}の選択肢が重複しています。	なし
`items`	{label}の件数が指定範囲外です。	`min`、`max`（指定なしは `null`）
`range`	{label}が指定範囲外です。	`min`、`max`（指定なしは `null`）
`same_as`	{label}が一致しません。	`other`（確認先のキー）
`file_type`	{label}のファイル形式は受け付けていません。	なし
`file_size`	{label}のファイルサイズが上限を超えています。	`max`（バイト）
`file_duplicate`	{label}のファイルが重複しています。	なし

エラーはすべて集めて返します。ただし1つの項目につき最初の1件だけです。
順序は、定義にない項目、定義の順の各項目、確認入力の不一致の順です。
メッセージはフォームSDKの MagicForm.setMessages で画面上の表示だけを変えられます（フォームSDK）。

サーバーは常に検証する

フォームSDKやHTMLの required 属性などによるブラウザ側のチェックは、入力の手間を減らすためのものです。Magic Form Cloud は、HTMLフォーム・SDK・JSON APIのどの経路の送信でも、公開版の定義ですべてのルールを毎回検証し、エラーがあれば保存もメール送信もしません。ブラウザ側のチェックを外したり、直接送信したりしても、ルールに合わない値は保存されません。