プレビュー画面で、郵便番号欄に「520-3041」と入れました。何も起きません。フォーカスを次の欄に移しても、住所欄は空のまま。エラーも出ない。Contact Form 7 に zipaddr-jp を入れて、郵便番号を打てば住所が自動で埋まる、はずでした。先に答えを書きます。原因は、id 命名規則の area を1行書き忘れていたこと。しかもこれは、プラグイン作者自身が「誤って定義する方が多い」と注記しているくらい、誰もがハマる場所でした。受託案件で踏んだので、その「動かない」をどう切り分けたかと一緒に残しておきます。
確認日：2026年5月8日。検証環境は Local by Flywheel / WordPress 6.9.4 / PHP 8.3.21 / Contact Form 7・zipaddr-jp（2026年5月時点の最新版）。本番投入したクライアントサイトは2025年から稼働中で、月数十件の問い合わせが滞りなく送信されています。情報は WordPress.org の zipaddr-jp プラグインページと zipaddr-jp 公式サイトに基づきます。
受けたのは、郵便番号から住所を埋める依頼だった
依頼ははっきりしていました。すでに Contact Form 7 で動いている問い合わせフォームに、郵便番号欄と住所欄を足して、郵便番号を入れると都道府県・市区町村・町域まで自動で埋まるようにしてほしい。番地と建物名はユーザーが自分で入力する想定です。
住所の自動入力を自前で作ると、対応データの取得、更新、通信失敗時のフォールバックと、見積もりの何倍も時間がかかります。だから、プラグインやライブラリの選定が作業の半分以上を占めます。WordPress.org で郵便番号から住所自動入力を探すと、実用上の選択肢は zipaddr-jp に絞られていきました。Welcart、Contact Form 7、MW WP Form、WooCommerce、WPForms など、主要な日本語フォームをほぼ網羅しています。仕組みは、郵便番号欄に値が入るとプラグインの JavaScript が zipaddr 側へ jsonp で問い合わせ、返ってきた都道府県・市区町村・町域を、対応する input に書き込む、というものです。
郵便番号を拾って問い合わせ、返ってきた住所を input に書き込む。ここまでは正しく動いていました。
id 規則を、4項目だと思い込んでいた
Contact Form 7 は標準サポートで、フォームタグに決められた id を付けるだけで連携します。私のフォームは、郵便番号・都道府県・市区町村・町域・以降の住所、と分ける構成でした。
| 1 2 3 4 5 | [text* your-postcode id:zip] [text* your-pref id:pref] [text* your-city id:city] [text* your-area id:area] [text* your-addr id:addr] |
id は zip / pref / city / area / addr の5項目で、郵便番号・都道府県・市区町村・町域・以降の住所に対応します（2グループ目以降は zip2 / pref2 のように末尾に番号を付け、最大6グループまで）。ところが私は、最初に「住所の自動入力」と聞いて、都道府県・市区町村・住所詳細の3つに分けるイメージで設計していました。pref / city / addr の3つで完結する、と思い込んで、町域用の area を丸ごと飛ばしていたのです。
途中までは正常、最後だけ無音だった
プレビューで「520-3041」と入れて、何も起きない。最初に疑ったのはプラグインの読み込み失敗でした。コンソールにエラーはなし。Network タブを見ると、zipaddr 側の API へのリクエストは飛んでいて、200 で返っている。レスポンスを覗くと、ちゃんと「滋賀県」「栗東市」「出庭」のデータが入っている。つまり、プラグインは動いていて、郵便番号も拾えていて、住所データも返ってきている。なのに input には何も書き込まれない。こういう、途中までは正常で最後だけ無音、というケースは、たいてい書き込み先の指定がずれています。プラグインが書き込もうとしている input が、フォーム上に存在しないか、別の名前になっているか。そこでフォームタグの id を読み返して、ようやく気づきました。area が抜けている。
左が私のミス。右が正解。差は area の1行だけでした。
この境界を、1つの欄に押し込めようとしてつまずきました。
area と addr は、役割が分かれていた
zipaddr-jp の area と addr は、設計として役割がきっちり分かれています。area は、郵便番号から特定できる町域。「520-3041」なら「出庭」が入ります。zipaddr 側は都道府県・市区町村・町域までを返してくれますが、その先の番地や建物名は郵便番号から特定できません。だから addr は、ユーザー自身が入力する欄として別に用意されている。言い換えると、area は自動補完される最後の input、addr はユーザーが自分で書く最初の input、というコントラクトです。
両者を重ねると、自動補完の結果とユーザー入力の番地が同じ input に同居して、補完のタイミングや値の置き換えで挙動が崩れます。zipaddr-jp 公式ドキュメントの一番上にも、「※この部分を誤って定義する方が多いようです」と太字で書かれている。私はそれを読み流して、4項目だけ書いていました。area 用の input を1行足したら、すんなり動きました。「520-3041」で、滋賀県 / 栗東市 / 出庭 が一瞬で埋まり、カーソルが番地欄に移ります。
1件で動いても、すぐ本番に入れなかった
郵便番号と住所の対応には、思ったよりエッジケースがあります。本番前に最低限テストしたのは、まず政令指定都市（横浜市中区のように「市」と「区」が両方入るか）。それから合併で表記が変わった市町村（zipaddr 側のデータが追従しているか）。同じ郵便番号で町域が複数あるケース（一意に決まらない番号での挙動。zipaddr-jp はデフォルトで一意な範囲だけ自動入力します）。北海道・東京都のように「都」「道」が付く都道府県名。最後に離島・遠隔地。これらをまとめてテストして、すべてで自然に補完されることを確認してから引き渡しました。
選択肢としては、HTML / CSS だけの静的ページなら microformats のクラス名で動く yubinbango.js が定番ですし、自前で持つなら日本郵便の KEN_ALL.csv、手軽な zipcloud、商用 SLA のある postcode-jp もあります。ただ、Contact Form 7 のようにプラグイン側が HTML を組み立てる仕組みでは、form 要素にクラスを付ける yubinbango より、id 規則だけで完結する zipaddr-jp のほうが扱いやすい。月額コストを足さず WordPress 内で完結する、という受託の落としどころにも合っていました。
仕上げに、郵便番号欄へ inputmode:numeric（スマホで数字キーボードが出る）と autocomplete:postal-code（ブラウザの保存値で補完）を Contact Form 7 のタグに足しています。未知のオプションは HTML 属性として出力されるので、inputmode=”numeric” や autocomplete=”postal-code” として反映されます。
次の自分に渡すメモ
もう一度「520-3041」を入れてみます。あのときは空のままでしたが、いまは滋賀県 / 栗東市 / 出庭 が一瞬で埋まる。差は area の1行だけでした。今回いちばん効いたのは、インストールするだけで動くと書かれたプラグインでも、id 命名規則のような小さなコントラクトは存在する、という当たり前の事実です。それを読み飛ばすと、API は動いていて、レスポンスも返っていて、エラーも出ない、という無音のデバッグに小一時間吸い取られます。公式ドキュメントの太字注記は、飛ばさない。自分は気をつけるから大丈夫、と思った瞬間に、誤って定義する方の一人になります。
もうひとつ残しておきたいのは、area と addr のように、機械が埋める欄と人が埋める欄を分ける、という発想です。郵便番号に限らず、姓と名、メールと確認用、検索キーワードと絞り込み条件。自動化を扱うときは、この境界が必ず出てきます。次にライブラリを選ぶときは、データの流れとユーザー操作の流れを、フォーム設計に持ち込む前に分けて考える。同じく Contact Form 7 と zipaddr-jp で動かないと詰まっているなら、まず id 命名規則の area が抜けていないか、そこを見てみてください。私と同じ理由でハマっている可能性が、それなりに高いと思います。
関連記事
- 日本語入力の Enter でフォームが誤送信される問題を直した話｜Safari・React・Vue 対応。同じ WordPress フォーム実装で、IME 確定の Enter による誤送信を直した記録です。
- 姓名フォームのフリガナ自動入力を composition イベントで自前実装した話。IME の composition イベントで、姓名フォームのフリガナ自動入力を組んだ話です。
- 日本語フォームの半角カナ・全角英数を input と blur で使い分けて自動変換する話。半角カナや全角英数を、input と blur で役割分担して自動変換する話です。
本記事の情報は2026年5月8日時点のものです。zipaddr-jp や Contact Form 7 のバージョンアップで設定方法が変わる可能性があります。最新情報は WordPress.org の zipaddr-jp プラグインページと zipaddr-jp 公式サイトで確認してください。
コメント