📨

【Laravel】郵便番号入力による住所自動補完：AjaxZip3より「Yubinbango」が快適だった話

に公開
Laravel
yubinbango
ajaxzip3
tech

はじめに

Laravelでユーザー登録フォームや配送先入力フォームを作成する際、UX向上のため、郵便番号から住所を自動で補完したいことがあります。長年使われている 「AjaxZip3」というライブラリもありますが、「Yubinbango」を使ってみたところ、圧倒的に快適だったと感じました。

この記事では、Laravelアプリケーションにおける住所自動補完の導入手段として「Yubinbango」を選んだ理由や導入方法について、具体的なコード例を交えながら紹介します。

対象者

  • Laravelでフォーム入力機能を開発しているエンジニア
  • Laravelに余計なJSコードを入れたくない方
  • 郵便番号から住所を自動補完したいが、AjaxZip3以外のライブラリを探している方

背景（AjaxZip3の課題とYubinBangoの発見）

以前は住所の入力補完といえば、AjaxZip3が定番でした。しかし、以下の点が気になっていました。

  • input要素の name 属性や onKeyUp に強く依存していて拡張性に乏しい
  • フォーム構造に対して柔軟性がない
  • jQueryベースで書かれた例も多く、モダンなLaravel開発では使いづらい

そんなときに、AjaxZip3の開発者が後継として公開していた「YubinBango」というライブラリの存在を発見しました。

YubinBango とは？

YubinBangoは、マイクロフォーマット（h-adr）に準拠したシンプルなJavaScriptライブラリで、フォームに class 属性をつけるだけで住所補完を実現できます。JavaScriptを書く必要はありません。郵便番号が全角数字で入力された場合は半角に自動変換され、ハイフンありでも問題なく動作します。

  • 軽量（1ファイル、CDNで配信）
  • バニラJSで動作
  • jQuery不要
  • microformats2の仕様に準拠

参考：https://yubinbango.github.io/yubinbango/

YubinBango の技術的背景

  • Google Code閉鎖に伴い、GitHubへ移行

  • TypeScriptベースに全面書き換え

  • 郵便番号データは GitHub Actions により自動更新

  • 構成は以下の3モジュール：

    • Coreモジュール
    • AjaxZip3互換モジュール
    • 新設計のYubinBangoモジュール

Laravelアプリへの導入手順

以下の手順で導入できます。
実装後は、郵便番号欄に郵便番号を入力するだけで自動的に住所が入力されるようになります。

1. CDNで読み込む

<!-- headタグ内に追記 -->
<script src="https://yubinbango.github.io/yubinbango/yubinbango.js" charset="UTF-8"></script>

2. フォームにh-adr構造を設定（基本）

<form class="h-adr">
  <span class="p-country-name" style="display:none;">Japan</span>

  <label>郵便番号
    <input type="text" class="p-postal-code" size="8" maxlength="8">
  </label>

  <label>都道府県
    <input type="text" class="p-region">
  </label>

  <label>市区町村
    <input type="text" class="p-locality">
  </label>

  <label>番地など
    <input type="text" class="p-street-address">
  </label>
</form>

3. 住所欄を1つにまとめる方法（簡易）

<form class="h-adr">
  <span class="p-country-name">Japan</span>

  <label>郵便番号
    <input type="text" class="p-postal-code" size="8" maxlength="8">
  </label>

  <label>住所
    <input type="text" class="p-region p-locality p-street-address p-extended-address">
  </label>
</form>

4. フィールドを分けて設定する場合（詳細）

<form class="h-adr">
  <span class="p-country-name" style="display:none;">Japan</span>

  <label>〒
    <input type="text" class="p-postal-code" size="3" maxlength="3">
  </label>
  -
  <label>
    <input type="text" class="p-postal-code" size="4" maxlength="4">
  </label>

  <label>都道府県
    <input type="text" class="p-region" readonly />
  </label>

  <label>市区町村
    <input type="text" class="p-locality" readonly />
  </label>

  <label>番地
    <input type="text" class="p-street-address" />
  </label>

  <label>建物名・部屋番号など
    <input type="text" class="p-extended-address" />
  </label>
</form>

5. 注意事項

YubinBangoが有効になるには、以下の条件がすべて満たされている必要があります。

条件 説明
scriptの読み込み CDNから yubinbango.js を読み込んでいること
例：<script src="https://yubinbango.github.io/yubinbango/yubinbango.js" charset="UTF-8"></script>
フォームに h-adr <form> タグに class="h-adr" が指定されていること
国名の指定 フォーム内に p-country-name が Japan として指定されていること
例：<span class="p-country-name" style="display:none;">Japan</span>
郵便番号欄の設定 郵便番号を入力する input に p-postal-code クラスがあること（分割入力も可）
住所欄の設定 都道府県（p-region）、市区町村（p-locality）、町域（p-street-address）、建物名等（p-extended-address）に対応するクラスがそれぞれ設定されていること

注意点

  • クラス名（p-postal-codeなど）は正確に指定してください。
  • JavaScriptで動的にフォームを生成する場合は、再レンダリング時に注意してください。
  • LivewireやInertia.jsとの併用時は、DOM再描画後に再度読み込まれるように工夫が必要です。
  • readonly 属性の使用可否も設計に応じて確認が必要です。

おわりに

Laravelで住所入力フォームを作るなら、YubinBangoはシンプルで導入も簡単、保守性も高い選択肢です。昔ながらのAjaxZip3も悪くはありませんが、モダンで保守性を重視する開発においては、YubinBangoを第一候補にするのがよいと感じました。
この記事が、同じようにフォームの自動補完で悩んでいる方の一助になれば幸いです。

株式会社ONE WEDGE

【Serverlessで世の中をもっと楽しく】
ONE WEDGEはServerlessシステム開発を中核技術としてWeb系システム開発、AWS/GCPを利用した業務システム・サービス開発、PWAを用いたモバイル開発、Alexaスキル開発など、元気と技術力を武器にお客様に真摯に向き合う価値創造企業です。
https://onewedge.co.jp/

GitHubで編集を提案

Discussion