郵便番号 → 住所自動入力 — ライブラリ版

このコンポーネントについて

住所自動入力を自作で実装する場合、fetch によるAPI呼び出しやステータス管理のJSコードが必要になります（自作版は郵便番号自動入力（Zip Code Lookup）を参照）。一方 YubinBango.js は、フォーム要素にmicroformats2準拠のクラス名（h-adr / p-postal-code / p-region 等）を付けるだけで、JS記述をほとんど書かずに同じ機能を実現できるライブラリです。会員登録・配送先入力フォームなど、住所自動入力を手早く組み込みたい場面で使えます。このページでは、YubinBango.jsを使った実装と、既存の自作版・AjaxZip3という3つの方式を比較し、業務の要件に応じてどれを選ぶべきかを整理します。

クラス名を付けるだけで動作 — <script> タグを読み込み、フォームに規定のクラス名を付与するだけで自動入力が有効になる。呼び出しコードの記述が不要
全角数字・ハイフン入り入力に対応 — 全角で入力しても自動的に半角変換され、ハイフンの有無を問わず動作する
3桁＋4桁の分割入力欄に対応 — 郵便番号を1つの入力欄にまとめず、分割したUIでも動作する
方式比較表 — YubinBango.js／fetch自作（zipcloud API）／AjaxZip3の3方式を、導入の手軽さ・カスタマイズ性・メンテ状況・オフライン可否で比較する

方式比較

観点	YubinBango.js	fetch自作（zipcloud API）	AjaxZip3
導入の手軽さ	◎ クラス名を付けるだけ	△ APIコード・ステータス管理を自前実装	○ スクリプト読み込み＋属性指定
カスタマイズ性	△ 表示ロジックはライブラリ任せ	◎ 通信・表示を自由に制御できる	△ YubinBangoよりさらに古い設計
メンテ状況	GitHub最終更新2020年・issue13件放置。活発なメンテではない	zipcloud API自体は稼働中（form-zipcode で動作確認済み）	GitHub最終更新2023年・issue3件。YubinBangoより新しいが同様に停滞気味
オフライン可否	不可（外部スクリプトの読み込みが必要）	不可（外部API通信が必須）	不可（外部API通信が必須）

「ajaxzip3代替」として使われることが多いYubinBango.jsですが、GitHubの最終更新は2020年でありAjaxZip3（2023年）より古いまま止まっています。どちらも活発なメンテとは言えないため、採用前にリポジトリの状況を確認しておくと安心です。通信処理を自分で制御したい場合は自作版（form-zipcode）を選ぶ方が向いています。

実装のポイント・注意点

YubinBango.jsを動かすには、フォーム要素に class="h-adr" を付け、内部に非表示の <span class="p-country-name">Japan</span> を含める必要があります。これはmicroformats2という住所データの標準フォーマットの仕様で、国名の指定が必須になっているためです。ユーザーには見せませんが、これを省略するとライブラリ自体が動作しません。

郵便番号欄には class="p-postal-code" を付与します。公式の実装例に合わせて3桁欄・4桁欄の2つに分割していますが、どちらの欄にも同じクラスを付ければライブラリ側が結合して判定してくれます。住所欄（都道府県・市区町村・町域）にはそれぞれ p-region / p-locality / p-street-address クラスを付けるだけで、値のセットまで自動で行われます。

番地・建物名は郵便番号からは特定できない情報のため、p-extended-address クラスの欄を専用に用意し、常に手動入力を促します。自動入力された都道府県・市区町村・町域の欄も readonly にはせず、そのまま手動で修正できるようにしておくと、マンション名の表記揺れなどに対応しやすくなります。

HTML・CSS・JavaScriptで実装しており、YubinBango.jsライブラリ（CDN）を1本追加するだけで動きます。フレームワーク不要でコピペすぐに使えます。

デモ

サンプルソース

3つのファイルを同じフォルダに保存し、index.html をブラウザで開くとすぐに動作確認できます。
ファイル名：index.html / style.css / script.js — 保存時の文字コードは UTF-8 を指定してください（Shift-JISだと日本語が文字化けします）。

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>郵便番号→住所自動入力（YubinBango.js版）サンプル</title>
  <link rel="stylesheet" href="./style.css">
  <script src="https://yubinbango.github.io/yubinbango/yubinbango.js" charset="UTF-8"></script>
</head>
<body>

<form class="h-adr yb-form">

  <span class="p-country-name yb-hidden">Japan</span>

  <div class="yb-field">
    <label class="yb-label" for="yb-postal-1">郵便番号</label>
    <div class="yb-postal-group">
      <input type="text" id="yb-postal-1" class="yb-input yb-input-postal p-postal-code"
             inputmode="numeric" size="3" maxlength="3" placeholder="123">
      <span class="yb-postal-hyphen">-</span>
      <input type="text" id="yb-postal-2" class="yb-input yb-input-postal p-postal-code"
             inputmode="numeric" size="4" maxlength="4" placeholder="4567">
    </div>
  </div>

  <div class="yb-field">
    <label class="yb-label" for="yb-pref">都道府県</label>
    <input type="text" id="yb-pref" class="yb-input p-region">
  </div>

  <div class="yb-field">
    <label class="yb-label" for="yb-city">市区町村</label>
    <input type="text" id="yb-city" class="yb-input p-locality">
  </div>

  <div class="yb-field">
    <label class="yb-label" for="yb-town">町域</label>
    <input type="text" id="yb-town" class="yb-input p-street-address">
  </div>

  <div class="yb-field">
    <label class="yb-label" for="yb-detail">番地・建物名</label>
    <input type="text" id="yb-detail" class="yb-input p-extended-address" placeholder="例：1-2-3 ○○ビル101">
    <span class="yb-hint">※ 番地・建物名は自動入力されません。手動で入力してください</span>
  </div>

</form>

<script src="./script.js"></script>
</body>
</html>

:root {
  --yb-primary: #2B7FE8;
  --yb-text: #1a2332;
  --yb-text-muted: #5a6a7a;
  --yb-border: #d0d7e0;
}

.yb-form {
  max-width: 420px;
  font-family: sans-serif;
}

.yb-field {
  margin-bottom: 16px;
}

.yb-label {
  display: block;
  margin-bottom: 6px;
  font-size: 13px;
  font-weight: 600;
  color: var(--yb-text);
}

.yb-input {
  width: 100%;
  padding: 10px 12px;
  font-size: 14px;
  color: var(--yb-text);
  border: 1.5px solid var(--yb-border);
  border-radius: 6px;
  box-sizing: border-box;
}

.yb-input:focus {
  outline: none;
  border-color: var(--yb-primary);
}

/* 郵便番号の3桁欄・ハイフン・4桁欄を横並びにする */
.yb-postal-group {
  display: flex;
  align-items: center;
  gap: 8px;
}

.yb-input-postal {
  width: 88px;
}

.yb-postal-hyphen {
  color: var(--yb-text-muted);
}

/* p-country-name はmicroformats2の仕様上必須だが画面には表示しない */
.yb-hidden {
  display: none;
}

.yb-hint {
  display: block;
  margin-top: 4px;
  font-size: 12px;
  color: var(--yb-text-muted);
}

// YubinBango.jsは h-adr クラスを持つフォーム内の p-postal-code 欄を監視し、
// 7桁の郵便番号が入力されると自動的に p-region / p-locality / p-street-address へ
// 値をセットする。呼び出し用のコードは不要（ライブラリが自動で動作する）。

// このサンプルではリセット処理のみ記述する
function resetDemo() {
  document.querySelectorAll('.yb-input').forEach(function (input) {
    input.value = '';
  });
}

AI用プロンプト

以下のプロンプトをコピーしてAIに渡すと、同様のコンポーネントを生成できます。

ChatGPTやClaudeにこのプロンプトを渡すと、同様のコンポーネントをゼロから生成・カスタマイズできます。入力欄の構成変更など、要件を追記して使うのがおすすめです。

※ このプロンプトを使ってもデモとまったく同じ動作にならない場合があります。AIの解釈や生成タイミングによって差が出ることをご了承ください。

💡 jQuery・Vue・React など特定のライブラリで実装したい場合は、プロンプトの末尾に「〇〇を使って実装してください」と追記してください。

# 郵便番号→住所自動入力（YubinBango.js版）作成依頼

## 概要
YubinBango.jsライブラリを使い、郵便番号入力で都道府県・市区町村・町域を自動入力するフォームを実装してください。

## 要件
- 入力欄：郵便番号（3桁＋4桁の分割2欄）、都道府県、市区町村、町域、番地・建物名
- フォーム要素に `class="h-adr"` を付与する
- 非表示の `Japan` をフォーム内に含める（microformats2の仕様上必須）
- 郵便番号欄に `class="p-postal-code"` を付与する（3桁欄・4桁欄の両方）
- 都道府県欄に `class="p-region"`、市区町村欄に `class="p-locality"`、町域欄に `class="p-street-address"`、番地・建物名欄に `class="p-extended-address"` を付与する
- `` を読み込む
- 郵便番号入力に応じた住所自動入力の呼び出しコードは書かない（ライブラリがクラス名を監視して自動的に動作する）
- 自動入力された都道府県・市区町村・町域の欄は、その後も手動で編集できるようにする
- 番地・建物名はライブラリで取得できないため、専用の入力欄を用意し手動入力を促すヒントを添える

## 技術仕様
- HTML / CSS / バニラJavaScript で実装
- 外部ライブラリ：YubinBango.js（CDN: https://yubinbango.github.io/yubinbango/yubinbango.js）
- レスポンシブ対応：必要

## 動作詳細
YubinBango.jsは `h-adr` クラスを持つフォーム内の `p-postal-code` クラスが付いた入力欄を監視し、7桁の郵便番号が入力されると自動的に住所を取得して `p-region` / `p-locality` / `p-street-address` クラスの入力欄に値をセットする。
全角数字での入力やハイフンを含む入力にも対応済みのため、入力値の変換処理を自前で書く必要はない。
番地・建物名（`p-extended-address`）はAPIで取得できないため、常に空のまま手動入力を促す。

## 出力形式
HTML・CSS・JavaScriptを分けて出力してください。
各ファイルは単独でコピー&ペーストして使えるよう記述してください。

同じカテゴリーの事例

現在準備中です。

郵便番号 → 住所自動入力（Address Autofill）— ライブラリ版