@simoko/tw-zip

台灣縣市、行政區、郵遞區號（3碼／6碼）查詢工具，支援 React / Vue / Svelte / SolidJS / Angular / 原生 JS。

特色

• 🚀 極速查詢 - 每秒 2300 萬次操作（效能報告）
• 📦 多框架支援 - React / Vue / Svelte / SolidJS / Angular
• 🎯 3+3 郵遞區號 - 支援 6 碼精確投遞查詢
• 🔍 驗證與搜尋 - 驗證輸入、模糊搜尋行政區/路名
• 🔄 Lazy Loading - 按需載入，初始僅 5KB
• 🌳 Tree Shaking - 只打包你用到的部分

▶ React · ▶ Vue · ▶ Svelte · ▶ SolidJS · ▶ Angular

安裝

npm install @simoko/tw-zip

快速開始

原生 JS

import {
  getZipCode,
  getCityArray,
  searchDistricts,
  isValidZipCode,
  isValidCity,
  getZipCodeAll
} from '@simoko/tw-zip'

// 基本查詢
getCityArray()                    // ['台北市', '基隆市', ...]
getZipCode('中正區')               // ['100', '台北市', '中正區']
getZipCode('100')                 // ['100', '台北市', '中正區']

// 模糊搜尋
searchDistricts('中正')            // [{ city: '台北市', district: '中正區', zipCode: '100' }, ...]

// 驗證
isValidZipCode('100')             // true
isValidCity('台北市')              // true

// 反向查詢（同名行政區）
getZipCodeAll('中正區')            // [['100', '台北市', '中正區'], ['300', '新竹市', '中正區'], ...]

React

import { useTwZip } from '@simoko/tw-zip/react'

function App() {
  const { cities, city, setCity, districts, district, setDistrict, zipCode } = useTwZip()

  return (
    <>
      <select value={city} onChange={e => setCity(e.target.value)}>
        {cities.map(c => <option key={c}>{c}</option>)}
      </select>
      <select value={district} onChange={e => setDistrict(e.target.value)}>
        {districts.map(d => <option key={d.label} value={d.label}>{d.label}</option>)}
      </select>
      <p>郵遞區號：{zipCode}</p>
    </>
  )
}

Vue

<script setup>
import { useTwZip } from '@simoko/tw-zip/vue'
const { cities, city, districts, district, zipCode } = useTwZip()
</script>

<template>
  <select v-model="city">
    <option v-for="c in cities" :key="c">{{ c }}</option>
  </select>
  <select v-model="district">
    <option v-for="d in districts" :key="d.label" :value="d.label">{{ d.label }}</option>
  </select>
  <p>郵遞區號：{{ zipCode }}</p>
</template>

Svelte

<script>
import { createTwZip } from '@simoko/tw-zip/svelte'
const { cities, city, districts, district, zipCode, setCity } = createTwZip()
</script>

<select bind:value={$city} on:change={e => setCity(e.target.value)}>
  {#each $cities as c}
    <option>{c}</option>
  {/each}
</select>
<p>郵遞區號：{$zipCode}</p>

SolidJS

import { useTwZip } from '@simoko/tw-zip/solidjs'

function App() {
  const { cities, city, setCity, districts, zipCode } = useTwZip()

  return (
    <>
      <select value={city()} onChange={e => setCity(e.target.value)}>
        {cities.map(c => <option>{c}</option>)}
      </select>
      <p>郵遞區號：{zipCode()}</p>
    </>
  )
}

Angular

import { Component } from '@angular/core'
import { TwZipService } from '@simoko/tw-zip/angular'

@Component({
  selector: 'app-zip',
  template: `
    <select [value]="twZip.city()" (change)="twZip.setCity($event.target.value)">
      <option *ngFor="let c of twZip.cities">{{ c }}</option>
    </select>
    <p>郵遞區號：{{ twZip.zipCode() }}</p>
  `
})
export class ZipComponent {
  constructor(public twZip: TwZipService) {}
}

6 碼郵遞區號

需要街道層級精確投遞（3+3 格式）？

import { getZipCode6 } from '@simoko/tw-zip/zip6'

getZipCode6({ city: '臺北市', area: '中正區', road: '三元街', number: 145 })
// { zipcode: '100060', zip3: '100', city: '臺北市', area: '中正區', road: '三元街' }

6 碼模組約 1.7MB，可使用 Lazy Load 版本 按需載入。

打包大小

本套件支援 Tree Shaking，只會打包你實際使用的模組：

| 模組 | 說明 | 大小 (minified + gzip) | |------|------|------------------------| | @simoko/tw-zip | 3 碼查詢 | ~11 KB | | @simoko/tw-zip/react | React Hook (3碼) | ~12 KB | | @simoko/tw-zip/vue | Vue Composable (3碼) | ~12 KB | | @simoko/tw-zip/zip6 | 6 碼查詢 | ~260 KB | | @simoko/tw-zip/react/lazy | React Lazy (6碼) | ~5 KB + 按需載入 |

💡 只用 3 碼？ 只會打包約 11 KB，不會包含 6 碼的 1.7MB 資料。

💡 需要 6 碼？ 使用 Lazy 版本，初始僅 5 KB，資料按縣市動態載入。

文件

| 文件 | 說明 | |------|------| | 3 碼 API | 縣市、行政區、郵遞區號查詢 | | 6 碼 API | 街道層級精確查詢 | | React Hooks | useTwZip / useTwZip6 | | Vue Composables | useTwZip / useTwZip6 | | Svelte Stores | createTwZip / createTwZip6 | | SolidJS Hooks | useTwZip / useTwZip6 | | Angular Services | TwZipService / TwZip6Service | | Lazy Load | 按縣市動態載入，減少初始大小 | | 效能基準測試 | 效能報告與最佳化建議 |

授權

MIT