Reactで、郵便番号から住所を自動で入れる入力欄を作る方法

​​React​autocomplete,Playwright,TypeScript,住所入力

会員登録や通販の注文フォームで、郵便番号を7桁入れると、都道府県・市区町村・町域が自動で入る住所入力欄を React で作りました。住所のデータは外部の API に頼らず、日本郵便の郵便番号データを上3桁ごとの JSON ファイルに分けて、自分のサイトに置きます。1回の検索で読むのは、いちばん大きいものでも61KB(gzip で圧縮すると約9.7KB)のファイル1つです。

全角で打たれた「100-0001」も7桁の数字にそろえます。1つの番号に住所が2つ以上ある場合は、候補を選んでもらいます。郵便番号を打ち直したときに、前の番号の結果が後から届いて住所を上書きする問題も防ぎます。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。使ったのは React 19.3.1、TypeScript 7.0.2、esbuild 0.28.2 で、tsc で型チェックしてから開発用ビルドにし、<StrictMode> で包んで動かしました。ブラウザは Playwright 1.63.0 の Chromium 153 です。住所のデータには npm パッケージ jp-postal 4.0.1(README によると2025年12月12日時点の日本郵便のデータ)を使いました。zipcloud などの外部の郵便番号 API、日本郵便のサイトからのデータの直接のダウンロード、Firefox と Safari、スマホの実機、ブラウザの住所の自動入力(autofill)との組み合わせは試していません。

郵便番号の欄に 1、0、0、0、0、0、1 と1文字ずつ入り、7文字目で都道府県に東京都、市区町村に千代田区、町域・番地に千代田が入り、カーソルが町域・番地の欄に移る。郵便番号は 100-0001 の形に整う
郵便番号を1文字ずつ入れ、7桁そろった瞬間に住所が入る様子(右上の表示とピンクの枠は説明用に足したもの)

住所のデータを、上3桁ごとのファイルに分けて置く

郵便番号から住所を引くには、外部の API を呼ぶ方法と、データを自分で持つ方法があります。ここでは後者を選びました。外部のサービスが止まっても影響を受けず、入力された郵便番号をほかのサービスに送らずに済むからです。

ただ、全部を1つのファイルにすると大きくなります。jp-postal には12万665件の郵便番号が入っていました。そこで、郵便番号の上3桁ごとにファイルを分け、public/zip/100.json のように置きます。中身は、下4桁から「都道府県・市区町村・町域」の組の配列を引く形です。100.json の先頭は次のようになりました。

json
{"1100":[["東京都","三宅島三宅村",""]],"1101":[["東京都","三宅島三宅村","神着"]], …}

検証環境で書き出すと、ファイルは948個、合計で約6.5MBでした。いちばん大きい 969.json でも61KB(gzip で圧縮すると約9.7KB)、100.json は36KB(同じく約2.4KB)です。

ファイルを作るスクリプトは次のとおりです。jp-postal の既定のエクスポートは、7桁の郵便番号から [都道府県, 市区町村, 町域, …カナ] の配列の配列を引くオブジェクトです。

js
// build-zip-json.mjs
import postal from 'jp-postal';
import { mkdirSync, writeFileSync } from 'node:fs';

const files = new Map(); // '100' -> { '0001': [[都道府県, 市区町村, 町域], ...] }

for (const [code, rows] of Object.entries(postal)) {
  // 長い町域名は、カッコの途中で次の行に分かれている。カッコが閉じるまでつなぐ
  const joined = [];
  for (const [pref, city, town] of rows) {
    const last = joined.at(-1);
    if (last && last[2].split('(').length > last[2].split(')').length) {
      last[2] += town;
    } else {
      joined.push([pref, city, town]);
    }
  }
  // 「(1〜19丁目)」「(次のビルを除く)」などの注記は入力欄に入れない
  const seen = new Set();
  const list = [];
  for (const [pref, city, town] of joined) {
    const t = town.replace(/(.*?)/g, '');
    const key = pref + city + t;
    if (seen.has(key)) continue;
    seen.add(key);
    list.push([pref, city, t]);
  }
  const head = code.slice(0, 3);
  if (!files.has(head)) files.set(head, {});
  files.get(head)[code.slice(3)] = list;
}

mkdirSync('public/zip', { recursive: true });
for (const [head, data] of files) {
  writeFileSync(`public/zip/${head}.json`, JSON.stringify(data));
}

元のデータをそのまま入力欄に入れられない理由は2つあります。

1つは、長い町域名が途中で次の行に分かれていることです。たとえば 289-2605 は「琴田(85〜160、1386〜1815、2593〜2820、」と「3598〜3614番地)」の2行になっていて、このままだと、1つの住所が2つの候補として扱われます。こうした行(開きカッコと閉じカッコの数が合わない行)は、jp-postal のデータ全体で416行ありました。

もう1つは、町域に「大通西(1〜19丁目)」「渋谷(次のビルを除く)」のような注記が付いていることです。入力欄には要らないので、カッコごと消しました。注記を消すと、同じ住所が2つになる番号もあります(静岡県の 411-0001 は「桑原(茨ケ平)」と「桑原(箱根峠)」)。そこで、重なったものは1つにまとめています。

町域が空の番号もあります。539-0000 を入れると、都道府県に「大阪府」、市区町村に「大阪市中央区」が入り、町域・番地の欄は空のままでした。町域は利用者に入れてもらいます。

全角やハイフンが混じっても7桁にそろえる

郵便番号の欄には、「100-0001」「〒100−0001」のような書き方も入ってきます。そこで、検索の前に7桁の半角数字にそろえる関数を用意しました。

ts
// postal.ts(一部)
// 全角の数字やハイフン、空白、〒が混じっていても、7桁の半角数字に直す。
// 7桁にならなければ null を返す
export function toPostalDigits(input: string): string | null {
  const s = input.normalize('NFKC').replace(/[\s\-‐−ー〒]/g, '');
  return /^\d{7}$/.test(s) ? s : null;
}

normalize('NFKC') で、全角の数字は半角に、全角の「-」は半角の「-」になります。ただ、長音の「ー」、マイナス記号の「−」、ハイフンの「‐」は、NFKC を通しても残りました。郵便番号の区切りとして打たれることがあるので、正規表現でまとめて取り除いています。全角と半角の変換そのものは、このブログの記事「Reactで、全角と半角を変換する入力欄を作る方法」で詳しく試しています。

検証環境で、次の入力はどれも東京都千代田区千代田になりました。「100-000」のように6桁しかないときは、検索しません。

入力 結果
1000001(1文字ずつ入力) 東京都 千代田区 千代田
100-0001 東京都 千代田区 千代田
100ー0001 東京都 千代田区 千代田
〒100−0001 東京都 千代田区 千代田
100 0001 東京都 千代田区 千代田
100-000 検索しない

上3桁のファイルを読み、一度読んだら使い回す

検索の関数は、上3桁のファイルを fetch で読み、下4桁で引きます。同じ上3桁のファイルは、Promise ごと Map にしまって使い回します。

ts
// postal.ts(続き)
export type Address = { pref: string; city: string; town: string };
type ZipFile = Record<string, [string, string, string][]>;

// 上3桁ごとのファイルは、一度読んだら使い回す
const cache = new Map<string, Promise<ZipFile>>();

async function loadZipFile(head: string): Promise<ZipFile> {
  const res = await fetch(`/zip/${head}.json`);
  if (res.status === 404) return {}; // その上3桁の郵便番号はない
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

export async function lookupAddress(zip: string): Promise<Address[]> {
  const head = zip.slice(0, 3);
  let file = cache.get(head);
  if (!file) {
    file = loadZipFile(head);
    cache.set(head, file);
    file.catch(() => cache.delete(head)); // 失敗したら次はまた取りに行く
  }
  const rows = (await file)[zip.slice(3)] ?? [];
  return rows.map(([pref, city, town]) => ({ pref, city, town }));
}

100-0001 を引いたあとに 100-0004 へ打ち直すと、/zip/100.json へのリクエストは1回だけで、町域は「大手町」に変わりました。

上3桁のファイルがない番号もあります。書き出した948個のほかに、000 や 008 など52通りの上3桁にはファイルがありません。0000000 を入れると /zip/000.json が404になり、「この郵便番号の住所は見つかりませんでした。」と出ました。

失敗した Promise を cache に残すと、次の検索でもそれが使われます。そのため、失敗したときは cache から消しています。検証で1回目だけ500を返すようにすると、「住所を取得できませんでした。手で入力してください。」と出ました。番号を打ち直すと、/zip/100.json をもう一度取りに行き、住所が入りました。

フォームの部品を作る

郵便番号と住所の欄をまとめた部品 AddressForm です。郵便番号の欄の onChange で7桁になったかを調べ、なっていれば検索します。

tsx
// AddressForm.tsx
import { useId, useRef, useState } from 'react';
import { lookupAddress, toPostalDigits, type Address } from './postal';

export function AddressForm() {
  const id = useId();
  const [postal, setPostal] = useState('');
  const [pref, setPref] = useState('');
  const [city, setCity] = useState('');
  const [line1, setLine1] = useState(''); // 町域・番地
  const [line2, setLine2] = useState(''); // 建物名・部屋番号
  const [candidates, setCandidates] = useState<Address[]>([]);
  const [message, setMessage] = useState('');
  const latest = useRef('');
  const line1Ref = useRef<HTMLInputElement>(null);

  function fill(a: Address) {
    setPref(a.pref);
    setCity(a.city);
    setLine1(a.town); // 番地はこの後ろに続けて入れてもらう
    setCandidates([]);
    setMessage('');
    line1Ref.current?.focus();
  }

  async function handlePostalChange(value: string) {
    setPostal(value);
    setCandidates([]);
    const zip = toPostalDigits(value);
    latest.current = zip ?? '';
    if (!zip) {
      setMessage('');
      return;
    }
    setMessage('住所を探しています…');
    try {
      const found = await lookupAddress(zip);
      if (latest.current !== zip) return; // その間に番号が変わった
      if (found.length === 0) {
        setMessage('この郵便番号の住所は見つかりませんでした。');
      } else if (found.length === 1) {
        fill(found[0]);
      } else {
        setCandidates(found);
        setMessage(`候補が${found.length}件あります。選んでください。`);
      }
    } catch {
      if (latest.current === zip) {
        setMessage('住所を取得できませんでした。手で入力してください。');
      }
    }
  }

  function handlePostalBlur() {
    const zip = toPostalDigits(postal);
    if (zip) setPostal(`${zip.slice(0, 3)}-${zip.slice(3)}`);
  }

  return (
    <form>
      <label htmlFor={`${id}-postal`}>郵便番号</label>
      <input
        id={`${id}-postal`}
        name="postal-code"
        autoComplete="postal-code"
        inputMode="numeric"
        placeholder="100-0001"
        value={postal}
        onChange={(e) => handlePostalChange(e.target.value)}
        onBlur={handlePostalBlur}
        aria-describedby={`${id}-message`}
      />
      <p id={`${id}-message`} role="status">{message}</p>

      {candidates.length > 0 && (
        <select
          aria-label="住所の候補"
          defaultValue=""
          onChange={(e) => fill(candidates[Number(e.target.value)])}
        >
          <option value="" disabled>候補から選ぶ</option>
          {candidates.map((a, i) => (
            <option key={i} value={i}>{a.pref}{a.city}{a.town}</option>
          ))}
        </select>
      )}

      <label htmlFor={`${id}-pref`}>都道府県</label>
      <input id={`${id}-pref`} autoComplete="address-level1"
        value={pref} onChange={(e) => setPref(e.target.value)} />
      <label htmlFor={`${id}-city`}>市区町村</label>
      <input id={`${id}-city`} autoComplete="address-level2"
        value={city} onChange={(e) => setCity(e.target.value)} />
      <label htmlFor={`${id}-line1`}>町域・番地</label>
      <input id={`${id}-line1`} ref={line1Ref} autoComplete="address-line1"
        value={line1} onChange={(e) => setLine1(e.target.value)} />
      <label htmlFor={`${id}-line2`}>建物名・部屋番号</label>
      <input id={`${id}-line2`} autoComplete="address-line2"
        value={line2} onChange={(e) => setLine2(e.target.value)} />
    </form>
  );
}

町域と番地を1つの欄にする

欄の分け方と autoComplete の値は、MDN の autocomplete 属性の説明にある日本の住所の例に合わせました。都道府県が address-level1、市区町村が address-level2、町域と番地をまとめた1行が address-line1 です。建物名と部屋番号は、その次の行の address-line2 にしています。

住所が入ると、カーソルは町域・番地の欄に移ります。100-0001 を入れたあと、そのまま「1-1」と打つと、欄は「千代田1-1」になりました。カーソルが町域の後ろにあるので、利用者は続けて番地を打てます。郵便番号の欄からカーソルが離れると、onBlur で「100-0001」の形に整えます。

郵便番号の欄の inputMode="numeric" は、スマートフォンなどで、数字のキーボードを出すようブラウザに伝える指定です。

打ち直したときに、古い結果で上書きしない

latest は、いちばん新しく検索を始めた番号を覚えておくための useRef です。結果が届いたときに latest.current と比べ、違えば何もしません。

この確認がないと困るのは、前の番号の結果が後から届いたときです。検証では、100.json の応答だけを1.5秒遅らせ、100-0001 を入れた0.2秒後に 060-0042 へ打ち直しました。確認を外した版では、打ち直してから0.3秒後には「北海道 札幌市中央区 大通西」が入っていました。ところが2秒ほどたつと、「東京都 千代田区 千代田」に書き換わっていました。郵便番号の欄は 060-0042 のままです。確認を入れた版では、2秒ほどたっても北海道の住所のままでした。

1つの番号に住所が2つ以上あるとき

郵便番号の中には、住所が1つに決まらないものがあります。498-0000 は、愛知県弥富市と三重県桑名郡木曽岬町の両方に当たり、都道府県もまたいでいます。

郵便番号の欄に 4980000 が入り、その下に「候補が2件あります。選んでください。」と、「候補から選ぶ」と書かれた選択欄が出ている。都道府県、市区町村、町域・番地、建物名・部屋番号の欄は空のまま
498-0000 を入れたとき。住所の欄は空のままで、候補の選択欄が出る

この部品では、候補が2つ以上あるときは住所の欄に何も入れず、select で選んでもらいます。「三重県桑名郡木曽岬町」を選ぶと、都道府県と市区町村が入り、選択欄は消えて、カーソルが町域・番地の欄に移りました。

候補の数が多い番号もあります。愛知県清須市の 452-0961 は66件でした。66件をボタンで並べるのは多すぎるので、select にしています。

郵便番号を変えると、町域・番地の欄は入れ直される

番地まで入れたあとに郵便番号を直すと、町域・番地の欄は新しい町域で上書きされます。「千代田1-1」と入れたあとに郵便番号を 100-0004 に変えると、欄は「大手町」になり、打った「1-1」は消えました。
郵便番号の欄に戻ってカーソルを置くだけでは、何も変わりませんでした。検索が動くのは、欄の中身が変わって7桁になったときだけです。

​Posted by 86