@simoko/tw-zip/dist/index.d.ts

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

interface IDistrict {
    [key: string]: string;
}
interface ICity {
    [key: string]: IDistrict;
}
type ZipCodeResult = [string, string, string];
/**
 * 回傳所有資料
 * @example
 * getData()
 * // { "台北市": { "中正區": "100", "大同區": "103", "中山區": "104", "松山區": "105", ... }, "基隆市": { "仁愛區": "200", "信義區": "201", "中正區": "202", ... }, ... }
 */
declare function getData(): ICity;
/**
 * 回傳縣市陣列
 * @example
 * getCityArray()
 * // [ "台北市", "基隆市", "新北市", ... ]
 */
declare function getCityArray(): string[];
/**
 * 回傳行政區資料 - dist
 * @param city 縣市名稱
 * @example
 * getDistricts("台北市")
 * // { "中正區": "100", "大同區": "103", ... }
 */
declare function getDistricts(city?: string): IDistrict;
/**
 * 回傳行政區資料 - array
 * @param city 縣市名稱
 * @param options 選項
 * @param options.label 標籤鍵名 (預設 `label`)
 * @param options.value 值鍵名 (預設 `value`)
 * @example
 * getDistrictArray("台北市", { label: "key" })
 * // [ { key: "中正區", value: "100" }, { key: "大同區", value: "103" }, ... ]
 */
declare function getDistrictArray(city?: string | null, { label, value }?: {
    label?: string;
    value?: string;
}): {
    [key: string]: string;
}[];
/**
 * 回傳扁平化陣列資訊
 * @param options 選項
 * @param options.city 縣市名稱 (預設回傳所有縣市)
 * @param options.symbol 分隔符號 (預設為 `空格符`)
 * @example
 * getFlatArray("台北市")
 * // [ "100 台北市 中正區", "103 台北市 大同區", ... ]
 *
 * getFlatArray({ city: '嘉義市', symbol: '#' })
 * // [ "600#嘉義市#東區", "600#嘉義市#西區" ]
 */
declare function getFlatArray({ city, symbol }?: {
    city?: string;
    symbol?: string;
}): string[];
/**
 * 根據行政區或郵遞區號回傳單筆資料（若有多筆則回傳第一筆）
 * @param input 行政區名稱或郵遞區號
 * @description 注意：同名行政區（如「中正區」）或共用郵遞區號（如「300」）會有多筆結果，
 * 此函數僅回傳第一筆。若需精確查詢，請使用 `getZipCodeByCity` 或 `searchDistricts`。
 * @example
 * getZipCode("中正區")
 * // [ "100", "台北市", "中正區" ]
 * getZipCode("100")
 * // [ "100", "台北市", "中正區" ]
 */
declare function getZipCode(input: string): ZipCodeResult | undefined;
/**
 * 根據行政區或郵遞區號回傳所有匹配的資料
 * @param input 行政區名稱或郵遞區號
 * @example
 * getZipCodeAll("中正區")
 * // [ ["100", "台北市", "中正區"], ["202", "基隆市", "中正區"] ]
 * getZipCodeAll("300")
 * // [ ["300", "新竹市", "東區"], ["300", "新竹市", "北區"], ["300", "新竹市", "香山區"] ]
 */
declare function getZipCodeAll(input: string): ZipCodeResult[];
/**
 * 根據縣市和行政區回傳郵遞區號資料（解決同名行政區問題）
 * @param city 縣市名稱
 * @param district 行政區名稱
 * @example
 * getZipCodeByCity("基隆市", "中正區")
 * // [ "202", "基隆市", "中正區" ]
 * getZipCodeByCity("台北市", "中正區")
 * // [ "100", "台北市", "中正區" ]
 */
declare function getZipCodeByCity(city: string, district: string): ZipCodeResult | undefined;
/**
 * 模糊搜尋行政區（支援同名行政區）
 * @param keyword 搜尋關鍵字
 * @example
 * searchDistricts("中正")
 * // [ ["100", "台北市", "中正區"], ["202", "基隆市", "中正區"] ]
 * searchDistricts("大安")
 * // [ ["106", "台北市", "大安區"], ["439", "台中市", "大安區"] ]
 */
declare function searchDistricts(keyword: string): ZipCodeResult[];
/**
 * 驗證縣市名稱是否有效
 * @param city 縣市名稱
 * @example
 * isValidCity("台北市") // true
 * isValidCity("東京都") // false
 */
declare function isValidCity(city: string): boolean;
/**
 * 驗證行政區名稱是否有效
 * @param district 行政區名稱
 * @param city 縣市名稱（可選，若指定則只在該縣市內驗證）
 * @example
 * isValidDistrict("中正區") // true
 * isValidDistrict("中正區", "台北市") // true
 * isValidDistrict("中正區", "高雄市") // false
 */
declare function isValidDistrict(district: string, city?: string): boolean;
/**
 * 驗證郵遞區號是否有效
 * @param zipCode 郵遞區號
 * @example
 * isValidZipCode("100") // true
 * isValidZipCode("999") // false
 */
declare function isValidZipCode(zipCode: string): boolean;

export { type ICity, type IDistrict, type ZipCodeResult, getCityArray, getData, getDistrictArray, getDistricts, getFlatArray, getZipCode, getZipCodeAll, getZipCodeByCity, isValidCity, isValidDistrict, isValidZipCode, searchDistricts };