Snow Monkey Forms Validation

Snow Monkey Forms に、フロントエンドの必須チェックと15種類の入力・ファイル検証ルールを追加する WordPress 拡張プラグインです。 必須かどうかは本体の設定を参照し、入力形式の追加設定はブロックエディターで管理します。

導入

1. Snow Monkey Forms 本体をインストールして有効にします。
2. このプラグインのディレクトリーに snow-monkey-forms-validation.php とビルド済みの assets/ を配置し、有効にします。
3. フォームの入力ブロックを選び、「拡張バリデーション」で必要なルールを有効にして保存します。
4. 必須にする項目は、本体の「バリデーション → 必須」も有効にします。

PHP 7.4 以上が必要です。公開サーバーに Node.js は不要です。 assets/ は生成物として Git の管理対象から除外しているため、ソースから導入する場合は次のビルドを実行してください。

開発・ビルド

開発には Node.js と npm を使用します。現在のテスト依存関係は Node.js 20.19.x 以降の20系、22.13.x 以降の22系、または 24以上 に対応しています。

npm ci
npm run build
npm test

JavaScript と JSON の変更は src/ の編集元で行い、assets/ を直接編集しないでください。 型検査や生成に失敗した場合は、生成物の書き出しを開始しません。監視中はエラー後も監視を続けます。 配布時はビルド後の assets/ 一式を含めます。WordPress / React の実装は本体が提供するものを利用し、ビルド成果物には同梱しません。

ファイルの役割

項目を追加・変更する場合

src/validations.ts の VALIDATIONS にキーと label・message・validate・displayOrder を定義します。 parameters は追加設定欄、kinds は表示対象の種別です。kinds を省略するとテキスト用になります。 エディターは displayOrder の昇順、形式ルールの検証は定義順です。表示順の変更は検証の優先順位に影響しません。新しい項目の初期値は無効（false）です。 対象ブロックは同ファイルの BLOCK_KINDS で管理します。

npm run build でエディター・フロント・PHP 用 JSON へ反映されます。型は共通定義から推論されます。 ルール追加時は tests/validation.test.mjs に許容値・不許可値・境界値を追加してください。 保存済みフォームがルールのキーを利用するため、既存キーを変更・削除する場合は設定の移行も検討してください。

設定と保存形式

独自の設定パネルは Text / Email / Tel / Textarea / URL に追加し、URL を含む13種類のテキスト用ルールを選べます。 File には「ファイル形式」「ファイルサイズ上限」の2種類を追加します。 テキスト用の表示順は、文字種（全角・ひらがな・カタカナ・ひらがなとカタカナ・半角数字・半角英字・半角英数字）、URL・メールアドレス・電話番号・郵便番号、文字数範囲・他の項目と一致の順です。 Select / Checkboxes / Radio buttons は本体の必須設定による検査だけを行い、独自パネルは追加しません。 フォーム固有の条件付き必須や、項目ごとのエラーメッセージ編集機能はありません。

例えば smfValidation に { "between": true }、smfValidationParams に { "between": { "min": 2, "max": 20 } } を保存すると、前後空白を除いた長さが2〜20の入力を許可します。空欄を禁止するには本体の「必須」も設定します。 独自キーは本体の validations 属性に追加せず、本体の PHP Validator のルールを変更しません。

読み込みと画面遷移

フロントの JavaScript は snow_monkey_forms/form/prepend で読み込みを登録し、フォームが実際に描画された公開ページのフッターで本体スクリプトの後に読み込みます。 テンプレートや同期パターン内で描画されたフォームも対象です。管理画面・REST 応答ではこのフロント用読み込みを登録しません。 エディター用 JavaScript はブロックエディターで読み込み、スクリプトのキャッシュ更新にはファイルの更新時刻を使います。

検証用 HTML 属性は snow_monkey_forms/control/attributes でコントロール生成時に付与するため、確認画面から戻った場合やエラー後の再描画でも出力されます。 イベントは document で受け取るため、入力欄の DOM が差し替わってもフロント検証の登録をやり直す必要はありません。 初期ページにフォームがなく、後から独自の JavaScript でフォームだけを追加する構成のスクリプト読み込みは、この仕組みの対象外です。

yubinbango との連携

テーマなどで yubinbango.js を読み込んでいる場合、smf.back・smf.invalid 後に YubinBango.MicroformatDom を再生成し、差し替わった郵便番号欄へイベントを再登録します。 同じフォームで郵便番号欄の要素が変わっていない場合は再登録を省きます。 初期表示は yubinbango 自身の初期化に任せ、この拡張から住所の再検索は行いません。

.h-adr・.p-country-name・.p-postal-code など、yubinbango 用のマークアップが必要です。 ライブラリー自体は同梱・自動読込しません。 未読込でもエラーにはせず連携処理を保留し、その後の script の load 時にライブラリーが利用できれば再登録します。 郵便番号欄がないフォームや、DOM から取り除かれたフォームは対象外です。

判定とエラー表示

本体が出力する data-validations="required" を参照し、独自形式を設定していない項目もフロントで必須チェックします。 必須判定の後、共通定義の順番で有効な形式ルールを検証します。複数ルールを有効にすると、すべての条件を満たす必要があります。 前後の空白は除いて判定しますが、入力欄の値そのものは書き換えません。

エラーメッセージは各項目の .smf-placeholder を優先して配置し、本体の表示用クラスと拡張の識別クラスを付けます。 削除するのは拡張が作成したエラーだけです。本体が出力するサーバー側エラーの表示・解除は本体の処理に従います。 確認画面から戻った後や、本体のエラー後の再描画でも同じタイミングで動作します。

必須チェック

• テキスト・テキストエリアは空白だけの入力も未入力として扱います。
• セレクトは空値、チェックボックス・ラジオはグループ内に有効な選択がない場合にエラーにします。
• ファイルは新規選択、または同じ項目の .smf-file-control__value にある同名の有効な hidden 値でアップロード済みかを判断します。
• disabled の入力欄（無効な fieldset 内を含む）と、確認画面などの hidden は検証しません。

入力形式の一覧

すべての形式ルールは空欄を許可します。必須の場合は上記の必須チェックが先に働きます。 以下は前後の空白を除いた後の値に対する判定です。

「全角」は文字幅そのものを判定する機能ではなく、指定範囲の半角文字を除外する方式です。 「全角ひらがな・カタカナ」は漢字・英数字・半角カナ・中黒・途中の改行を許可しません。 混在を許可する場合は kana を有効にし、個別の hiragana・katakana は無効にしてください。 半角数字・半角英字・半角英数字は符号・小数点・途中の空白も許可しません。

文字数範囲

最小・最大の初期値は0〜100です。0以上の整数を指定し、最大を最小以上にしてください。 JavaScript の value.length（UTF-16 コード単位）で数えるため、絵文字などは見た目の1文字が複数として数えられる場合があります。

他の項目と一致

確認入力欄で有効にし、元の項目の name 属性（例：email）を指定します。 同じフォーム内で、自分以外かつ disabled でない最初の同名入力欄を比較先にします。両方の前後空白を除いて比較します。 確認欄が空でなければ、比較先の未指定・不存在もエラーにします。 一致先からフォーカスが離れた場合も、値が入っている、またはエラー表示中の確認欄を再検証します。

電話番号

ハイフンなしの半角数字10〜11桁、または 2-4-4 / 3-3-4 / 3-4-4 / 4-2-4 / 4-3-3 / 5-1-4 の桁区切りを許可します。 先頭が 0 かどうか、番号の実在、国際番号への対応は検査しません。

URL

https://example.com/path のように、HTTP / HTTPS のスキームとホスト名を含む URL を許可します。 日本語ドメイン・パス、ポート番号、クエリ、フラグメントも使用できます。 相対パス、スキーム省略、FTP・JavaScript など別のスキーム、途中の空白・改行・バックスラッシュは許可しません。 URL の構文を検査する機能で、アクセス先の実在や応答は確認しません。

ファイル形式

File ブロックの「ファイル形式」を有効にし、許可する拡張子をカンマ区切りで指定します。 初期値は pdf,jpg,jpeg,png です。先頭のドットは省略可能で、大文字・小文字を区別しません。 例えば .pdf,docx は 資料.PDF と 資料.docx を許可し、資料.pdf.exe を拒否します。 tar.gz のような複合拡張子も指定できます。空の一覧や image/* などの MIME タイプ・ワイルドカードは指定できません。 設定から accept 属性も生成し、ファイル選択画面を絞り込みます。例えば .pdf,docx は accept=".pdf,.docx" になります。初期表示と確認画面から戻った後の再描画の両方で付与します。 ファイル形式が無効、または設定が不正な場合は、この拡張から accept を付与しません。 accept は選択画面へのヒントであり、選択を完全に禁止するものではないため、フロントの拡張子チェックも引き続き行います。ファイル内容や MIME タイプの検査は行いません。

ファイルサイズ上限

File ブロックの「ファイルサイズ上限」を有効にし、0より大きい MB 値を指定します。初期値は5 MBで、小数（例：0.5）も使用できます。 このプラグインでは 1 MB = 1,048,576 バイト とし、上限ちょうどのサイズは許可します。 複数ファイルがある場合は合計ではなく1ファイルずつ検査します。ファイルを必須にする場合は、本体の「必須」も有効にしてください。

判定は他のルールと同じく blur または確認・送信時に行います。選択変更時にはエラーを再判定しません。 確認画面から戻った場合や本体のエラー後は、アップロード済みの hidden 値から拡張子を再検査します。 サイズは同じページ内で保持している選択ファイルの情報と名前が一致する場合に再検査します。 ページの再読込や本体によるファイル名の変更などでサイズ情報を取得できない保存済みファイルは、サイズ検査だけを省きます。新たに選択したファイルは常にそのファイルの情報で判定します。 本体や PHP・Web サーバーのアップロード制限は変更しません。

検証の範囲

独自形式の検証は JavaScript のみで、本体のサーバー側バリデーションも引き続き動作します。 この拡張のチェックはサーバー側入力検証の代替にはなりません。 自動テストは jsdom と WordPress・yubinbango API の代替を使用しており、実際の WordPress 上での画面遷移や外部ライブラリーの通信までは実行しません。

ライセンス

本プラグインは、GNU General Public License バージョン2、または利用者の選択によるそれ以降のバージョン（GPL-2.0-or-later）の条件で配布します。 ライセンス原文は LICENSE を参照してください。ライセンス文書は原文のまま収録し、翻訳やコメントの追記はしていません。

依存先の Snow Monkey Forms（作者: inc2734）も GPL バージョン2以降を採用しており、その公式ライセンス表記に合わせています。 この拡張の作者は ht-CODE です。第三者のライブラリーには、それぞれのライセンスが適用されます。

本プラグインは無保証で提供します。再配布・改変時の条件についてはライセンス原文を確認してください。