# Magic Form 実装ガイド（AI向け） このガイドは、AIアシスタントが Magic Form（https://form.magichtml.dev）につながるHTMLフォームを作るための仕様です。人向けの説明は https://form.magichtml.dev/docs にあります。 サイト運営者が管理画面の「AIへの指示」をコピーして渡している場合は、その指示に書かれた送信先・項目・設定を最優先してください。このガイドは、その指示を補う一般的な規則です。 ## 仕組み - Magic Form は、HTMLフォームの送信先（action）になるサービスです。サーバー側で、公開中のフォーム定義に照らして入力をチェックし、受け付けたら保存してメールで通知します。 - フォームの定義（項目のキー、型、必須、選択肢など）は管理画面で決まっています。HTMLは定義に合わせて作ります。HTMLだけで項目を増やすことはできません。 - フォームSDK（1行の script タグ）を読み込むと、送信前にブラウザで同じルールのチェックを行い、エラーを各項目の下に表示します。SDKがなくても送信はできます。 ## 必ずやること 1. `
` とする。サイトIDとキーは管理画面の指示の値を使う。 2. ファイル項目があるときは、form に `enctype="multipart/form-data"` を付ける。 3. 入力欄の `name` を、フォーム定義の項目のキーと完全に一致させる（大文字・小文字も同じ）。 4. 複数選択（チェックボックスの組）とファイルの入力欄は、`name` の末尾に `[]` を付ける（例：`interests[]`、`attachment[]`）。 5. フォームの中に、迷惑送信対策の非表示欄 `` を入れる。 6. 各項目の直後に `

` を置く。 7. ページの `` 直前に、SDKを次のとおり読み込む（URL、integrity、crossorigin を変えない）： ```html ``` ## やってはいけないこと - フォーム定義にない `name` を持つ入力欄を作る。送信ボタンにも `name` を付けない。定義にない値が1つでもあると、送信全体が拒否されます。 - `fetch` や `XMLHttpRequest` で送信処理を独自に書く、または既存の送信処理を残す。送信はブラウザの通常の送信とSDKに任せます。 - `_` で始まる名前の入力欄を、`_hp` 以外に追加する（`_` で始まる名前は予約されています）。 - SDKのファイルを自分のサイトにコピーして読み込む、または integrity を外す。 - 管理APIのトークンや、管理画面のURLをページに書く。公開ページに必要なのは送信先URLとSDKだけです。 ## 既存のフォームを置き換える場合 1. form の action・method・enctype を、このガイドまたは管理画面の指示の値に書き換える。 2. 入力欄の `name` を、フォーム定義のキーに付け替える。日本語の `name` は使えません。選択肢の `value` も定義の値に合わせる。 3. 既存の送信処理を削除する。たとえば submit イベントで `preventDefault()` して `alert()` を出すだけの処理、`fetch` で別の送信先に送る処理などです。 4. それまで使っていたフォームサービスの script タグ、専用の属性（`data-` で始まる独自属性など）、専用の隠し入力欄を削除し、`_hp` の非表示欄に置き換える。 5. エラー表示の要素を `

` に置き換える。エラーの文言はサービス側が表示するので、HTMLに書いておく必要はありません。 6. デザイン（class、レイアウト、ラベルの文言）はそのまま残してかまいません。 ## WordPress の場合 - フォームのHTMLは、テーマのテンプレート（例：`page-contact.php`）か、ブロックエディターの「カスタムHTML」ブロックに置きます。それまで使っていたフォームプラグインのショートコードは削除します。 - SDKの script タグは本文に書かず、テーマの `functions.php` で読み込みます。WordPress は `integrity` と `crossorigin` を自動では付けないため、`script_loader_tag` フィルターで付けます。 ```php add_action('wp_enqueue_scripts', function () { if (is_page('contact')) { wp_enqueue_script('magic-form', 'https://cdn.jsdelivr.net/npm/@magichtml/form@0.1.1/magic-form.js', [], null, ['in_footer' => true, 'strategy' => 'defer']); } }); add_filter('script_loader_tag', function ($tag, $handle) { if ($handle !== 'magic-form') { return $tag; } return str_replace(' src=', ' integrity="sha384-jSxe35HuXAjr/zPizWoeOFtWrvkIShOoXAQc6OWUyXGDtZ6OIfCaepb97ddWluev" crossorigin="anonymous" src=', $tag); }, 10, 2); ``` - `is_page('contact')` の `contact` は、フォームを置くページのスラッグです。すべてのページで読み込む場合は条件を外します。 - 送信データは Magic Form に保存され、WordPress のデータベースには保存されません。受付内容は Magic Form の管理画面で確認します。 ## 項目の型と入力欄 | 型 | 入力欄 | 送られる値 | |---|---|---| | text | `` | 文字列 | | textarea | `` | 文字列 | | email | `` | メールアドレス | | url | `` | http(s) のURL | | tel | `` | 文字列 | | number | `` | 数値 | | date | `` | YYYY-MM-DD | | select | `` | 選択肢の値の1つ | | checkboxes | 選択肢ごとに `` | 選択肢の値のリスト | | checkbox | ``（同意など） | チェックの有無 | | boolean | `` | はい／いいえ | | hidden | `` | 文字列 | | file | ``（2件以上なら `multiple`） | ファイル | - `option` や `value` には、定義の「値」を使います。画面に出す文字（ラベル）は自由に決めてかまいません。 - 必須の checkbox は、チェックしないと送信できません（同意欄に使います）。 - 定義に `same_as` がある項目は、指定された項目と同じ値を入れる確認欄です（例：メールアドレスの確認入力）。 ## 送信後 - 定義に移動先が設定されていれば、送信完了後にそのURLへ移動します。「/」で始まる移動先は、フォームを置いたサイト内のパスです。 - 移動先がなければ、サービス側の送信完了ページに移動します。 - `data-magic-mode="fetch"` を form に付けると、ページを移動せずに、`` に完了メッセージを表示します（ファイルも送れます）。 ## サイト運営者に伝えること - フォームを置くサイトのURL（例：`https://example.com`）を、管理画面の「サイト設定・接続元」に登録する必要があります。未登録のままだと送信が拒否されます。 - フォームを管理画面で公開していないと送信できません。 ## 完成後の確認 1. 何も入力せずに送信し、必須項目の下にエラーが表示されること。 2. 正しく入力して送信し、送信後の画面に進むこと。 3. 管理画面の受付一覧に、送信した内容が届いていること。 ## うまくいかないとき | 症状 | 原因と直し方 | |---|---| | 「このページからの送信は許可されていません」 | フォームを置いたサイトのURLが接続元に未登録。運営者に登録を依頼する | | 「フォームが見つかりません」 | action のサイトIDかキーが違う、またはフォームが未公開 | | 「定義にない項目「…」が含まれています」 | その name の入力欄を削除するか、name をキーに合わせる。送信ボタンの name も外す | | 「…フォームに enctype="multipart/form-data" を指定してください」 | form に enctype を付ける | | 「フォームが更新されています。再読み込みしてください」 | 管理画面でフォームが更新された。ページを再読み込みする | | エラーが項目の下に出ない | `data-magic-error` の値がキーと一致しているか、SDKの script が読み込まれているかを確認する | ## 完成形の例 ```html

``` --- # はじめに Magic Form Cloud は、静的サイトに置いたHTMLフォームの送信先になるホスト型のフォームサービスです。`
` を書き換えるだけで使え、送信内容は公開中のフォーム定義でサーバー側で検証してから保存し、通知メールと自動返信を送ります。このページでは、アカウントの作成からフォームを設置して受付を確認するまでの流れを説明します。 ## できること - **HTMLフォームの受付**: `method="post"` の素のHTMLフォームをそのまま受け付けます。JavaScript は不要です。 - **サーバー側の検証**: 必須・文字数・形式・選択肢・ファイル形式などを、公開中のフォーム定義に基づいて毎回サーバーで確認します。 - **受付データと添付ファイルの保存**: 管理画面の受付一覧で確認・ダウンロードできます。 - **メール**: 管理者への通知メールと、送信者への自動返信を送ります。 - **フォームSDK（任意）**: スクリプトを1行読み込むと、送信前にサーバーと同じルールで入力チェックします。詳しくは [フォームSDK](/docs/sdk) を参照してください。 - **API**: フォーム定義の取得、JSONでの送信、管理API、デプロイAPIがあります。詳しくは [API](/docs/api) を参照してください。 ## 利用の流れ | 手順 | 操作する場所 | |---|---| | 1. 招待からログイン | 招待URL、ログイン画面 | | 2. サイトを作成 | 管理画面のサイト一覧 | | 3. 接続元（Origin）を登録 | サイト画面の「サイト設定・接続元」 | | 4. フォームを作成し、項目を設定 | サイト画面の「＋ フォームを作成」、フォーム画面の「項目・設定」 | | 5. 公開 | フォーム画面の「保存済みの下書きを公開」 | | 6. HTMLに設置 | フォーム画面の「接続・公開履歴」 | | 7. 受付一覧で確認 | フォーム画面の「受付」 | ### 1. 招待からログイン アカウントは招待制で、誰でも登録できる新規登録画面はありません。利用はサービス管理者から届く招待URLから始まります。 - 招待URLを開き、お名前・メールアドレス・パスワードを入力してアカウントを作成します。 - パスワードは英字と数字を含む12文字以上です。 - 招待URLは1回だけ使えます。有効期限（既定は24時間）を過ぎたURLや使用済みのURLは開けません。その場合は管理者に再発行を依頼してください。 - 2回目以降は `https://form.magichtml.dev/login` からログインします。ログイン後の管理画面は `https://form.magichtml.dev/app` です。 - パスワードの再設定は、サービス管理者へ連絡してください。ログイン中であれば「アカウント・API」画面から変更できます。 ### 2. サイトを作成 管理画面（`https://form.magichtml.dev/app`）のサイト一覧で「＋ サイトを作成」を押し、サイト名（100文字まで）を入力します。サイトはフォームをまとめる単位で、接続元や受付データの保存期間をサイトごとに設定します。 ### 3. 接続元（Origin）を登録 フォームを設置するWebサイトのオリジンを、サイト画面の「サイト設定・接続元」にある「許可する接続元（1行に1件）」に登録します。登録していないページからの送信は拒否されます。 - `https://example.com` のように、スキームとホスト（必要ならポート）だけを入力します。パスやクエリは含めません。 - `https://example.com` と `https://www.example.com` は別の接続元です。両方で使う場合は両方を登録します。 - `http://localhost:8000` のような開発環境も登録できます。 - 登録できるのは20件までです。 同じ画面の「フォーム受付データの保存期間（日）」で、受付データを残す日数（1〜3650日、既定は90日）を設定します。期間を過ぎた受付は添付ファイルとともに毎日自動で削除されます。 ### 4. フォームを作成し、項目を設定 サイト画面の「＋ フォームを作成」で、名前と識別キーを入力します。 - 識別キーは送信先URLの一部になります（例: `contact`）。英小文字で始まり、英小文字・数字・`_`・`-` を使えます（80文字まで）。 - 作成直後のフォームには「お名前（`name`）」「メールアドレス（`email`）」「お問い合わせ内容（`message`）」の3項目が必須項目として入っています。 フォーム画面の「項目・設定」で、項目、通知・自動返信、送信完了後の動作を設定し、「項目・設定の下書きを保存」を押します。項目の型とルールは [項目と入力ルール](/docs/fields)、メールは [メール通知と自動返信](/docs/mail) を参照してください。 ### 5. 公開 フォーム画面上部の「保存済みの下書きを公開」を押すと、保存済みの下書きが公開され、送信を受け付けるようになります。公開中のフォームには「公開中」、まだ公開していないフォームには「未公開」と表示されます。 ### 6. HTMLに設置 フォーム画面の「接続・公開履歴」に、設置に必要な情報があります。 | 表示 | 内容 | |---|---| | フォーム送信先（HTMLのaction） | `https://form.magichtml.dev/f/SITE_ID/contact` の形式のURL | | フォーム定義API | 公開中の項目定義を返すURL | | JSON送信先 | JavaScript からJSONで送信する場合のURL | | HTMLサンプル | 保存済みの項目から作ったフォームのHTML（SDKの読み込みタグ付き） | `SITE_ID` はサイトごとのID（UUID）、`contact` はフォームの識別キーです。HTMLサンプルを貼り付けて、デザインを整えるのが手早い方法です。公開サイトのHTMLに管理用のAPIトークンを入れる必要はありません。 ### 7. 受付一覧で確認 フォーム画面の「受付」に、受付日時・受付ID・メールの配信状況が新しい順に30件ずつ表示されます。「詳細 →」から、入力値、添付ファイルのダウンロード、送信されたメールの内容と配信状況を確認でき、配信に失敗したメールの再送もここから予約できます。受付データは詳細画面から削除することもできます。 ## 下書きと公開版 フォームの内容は「下書き」と「公開版」に分かれています。 - 「項目・設定の下書きを保存」で保存されるのは下書きです。保存しても、公開中のフォームの動作は変わりません。 - 「保存済みの下書きを公開」を押すと、その時点の下書き（フォーム名・項目・メール設定・完了後の設定）が新しい公開版として固定されます。画面上で未保存の変更は公開されないので、先に保存してください。 - 送信の検証、保存、メールの内容は、受付時点の公開版の定義と設定で決まります。メール設定を変更した場合も、公開するまで反映されません。 - 公開版にはそれぞれID（UUID）があり、フォーム定義APIの `version` として返されます。 - 「接続・公開履歴」に公開履歴（直近20件）が表示されます。過去の版の「この版を公開」を押すと、その版に切り替わります。この操作で下書きは変わりません。 - 「公開停止」を押すと、フォーム定義の取得と送信ができなくなります（送信すると「フォームが見つかりません」と表示されます）。 項目を追加・削除・改名して公開したときは、設置したHTMLの `name` 属性も合わせて更新してください。定義にない名前の入力欄が送られると、送信は受け付けられません。 ## 最小のHTML例 作成直後の3項目のまま公開したフォームは、次のHTMLで送信できます。`SITE_ID` を管理画面に表示されたサイトIDに置き換えてください。 ```html
``` - `name` 属性はフォームの項目の識別キーと一致させます。 - `_hp` はスパム対策のハニーポット（人には見えない入力欄）です。 - 送信が受け付けられると、完了ページ（またはフォームで設定した移動先）に移動します。入力に誤りがあると、エラーの一覧ページが表示されます。 送信前に入力チェックをしたい場合は、`
` に `data-magic-form` を付けてSDKを読み込みます。 ```html
``` ## 次に読むページ - [HTMLフォームで送信する](/docs/html-forms): 送信先、`name` 属性、完了・エラー時の動作、制限 - [フォームSDK](/docs/sdk): 送信前チェック、JSON送信モード、JavaScript API - [項目と入力ルール](/docs/fields): 項目の型、入力ルール、エラーメッセージ - [メール通知と自動返信](/docs/mail): 通知先、差し込み、再送 - [API](/docs/api): 公開API、管理API、デプロイAPI、書き出し --- # HTMLフォームで送信する Magic Form Cloud は、JavaScript を使わない素のHTMLフォームの送信（ネイティブPOST）を受け付けます。送信内容は公開中のフォーム定義でサーバー側で検証され、受け付けると完了ページか指定した移動先へ、受け付けられないとエラーページへ移動します。このページでは、送信先URL、`name` 属性の付け方、予約フィールド、接続元の確認、完了・エラー時の動作、各種制限を説明します。 ## 送信先URL | メソッドとパス | 用途 | |---|---| | `POST https://form.magichtml.dev/f/SITE_ID/contact` | 現在の公開版に送信します。通常はこちらを使います | | `POST https://form.magichtml.dev/f/SITE_ID/releases/RELEASE_ID/contact` | デプロイAPIで作成したリリースに固定された公開版に送信します | - `SITE_ID` はサイトのID、`contact` はフォームの識別キーです。正確なURLはフォーム画面の「接続・公開履歴」にある「フォーム送信先（HTMLのaction）」に表示されます。 - リリース用のURLは、ツールから [デプロイAPI](/docs/api) でフォームを配置する場合に使います。手作業で設置する場合は使いません。 - 送信先URLをブラウザで直接開く（GET）と、「このURLはフォームの送信先です。フォームから送信してください。」と表示されます。 ## formタグ ```html
``` - `method="post"` を指定します。 - ファイル項目があるフォームでは `enctype="multipart/form-data"` が必須です。指定しないとブラウザはファイル名だけを文字列で送るため、「（項目名）のファイルを受け取れませんでした。フォームに enctype="multipart/form-data" を指定してください。」というエラーになります。 - ファイル項目がなければ `enctype` の指定は不要です。 ## name属性 入力欄の `name` 属性には、フォームの項目の識別キーをそのまま使います（大文字と小文字は区別されます）。 | 項目の型（管理画面の表示） | HTMLの例 | 受け取る値 | |---|---|---| | テキスト、複数行、メール、URL、電話番号、日付、非表示 | ``、`

``` `action` は実際の送信先URLなので、SDKを読み込めなかった場合も同じHTMLのまま送信できます。 ## 属性 | 属性 | 付ける場所 | 意味 | |---|---|---| | `data-magic-form` | `
` | このフォームをSDKの対象にします。`action` から定義とJSON送信先のURLを求めます | | `data-magic-mode="native"` | `` | 既定。チェック後にブラウザが通常どおりPOSTします | | `data-magic-mode="fetch"` | `` | JSONで送信し、ページを移動せずに完了表示します | | `data-magic-error="キー"` | フォーム内の要素 | その項目のエラーメッセージの表示先。なければ入力欄の後ろに自動で追加します | | `data-magic-form-error` | フォーム内の要素 | 項目に属さないメッセージ（定義にない項目、通信エラー、サーバーのエラー）の表示先。なければフォームの先頭に自動で追加します | | `data-magic-success` | ページ内の要素 | `fetch` モードで完了メッセージを表示する場所 | | `data-magic-submitting-text` | 送信ボタン | 送信中にボタンに表示する文字 | - `data-magic-error` の要素を省略した場合、メッセージの要素は入力欄を囲む `
`、`