TWzipcode.js

快速建立臺灣三碼郵遞區號表單元件的 JS Library

版本 3.0

jQuery-TWzipcode 請前往 Github 下載

Playground

Codepen

See the Pen TWzipcode playground by essoduke (@essoduke) on CodePen.

下載

GitHub developement production

安裝

引用

<script src="/path/twzipcode.js"></script>

npm

npm install twzipcode.js

使用

HTML

<-- /* 基本 */-->
<div class="twzipcode"></div>

<--/* 進階自訂 */-->
<div class="twzipcode">
    <select data-role="county" ></select>
    <select data-role="district"></select>
    <input type="hidden" data-role="zipcode" />
</div>

Javascript

/** 預設選擇器 .twzipcode */
const twzipcode = new TWzipcode();

/** 預設選擇器 & 參數 */
const twzipcode = new TWzipcode({...});

/** 自訂選擇器 & 參數 */
const twzipcode = new TWzipcode('.hello-world', {...});

/** Element 或 NodeList */
const twzipcode = new TWzipcode(document.querySelectorAll('.hello-world'));

方法

.nth()

若有多組清單，可使用 .nth() 選取

@param {String|number} id
@return {TWzipcode}

語法

let foo = twzipcode.nth(string|number id);

// 取得第 1 組清單
let foo = twzipcode.nth(0);

// 取消指定
let foo = twzipcode.nth();

.get()

取值

@param {String|Object} value
@return {Object|Array|String}

語法

let result = twzipcode.get();
// output:
{
    "zipcode": "100",
    "county": "臺北市",
    "district": "大安區"
}

// 取特定欄位
let result = twzipcode.get("zipcode");
// output: 106

// 取多個欄位
let result = twzipcode.get(["county", "zipcode"]);
// output:
{
    "county": "臺北市",
    "zipcode": "大安區"
}

.set()

設定值

@param {Object|String} [key]
@return {TWzipcode}

語法

// 設郵遞區號
// 直接給定郵遞區號
twzipcode.set("106");

// 或給定縣市字串
twzipcode.set({
    "county": "臺北市",
    "district": "大安區"
});

.serialize()

輸入 serialize 字串

@return {String}

語法

let result = twzipcode.serialize();
// Output: county=COUNTY&district=DISTRICT&=zipcode=ZIPCODE...

.isIslands()

判斷所選值是否為離島 (參見 options.islands_key)

@param  {Array}  [islands_name]
@return {Boolean}

語法

let is_island = twzipcode.isIslands();
// output true|false

// 或帶入自訂離島
let is_island = twzipcode.isIslands(["桃園市", "大安區"]);

.parseAddress()

解析台灣地址

參數

{
    county: {
        name: "(string) 表單名稱：預設 `county`",
        css: "(string) 樣式名稱",
        label: "(string) 清單預設文字",
        value: "(string) 預設選取值",
        hidden: "(Boolean|String|Array) 要隱藏的縣市，預設 false"
        onChange: "(Function) onChange event"
    },
    district: {
        name: "(string) 表單名稱：預設 `district`",
        css: "(string) 樣式名稱",
        label: "(string) 清單預設文字",
        value: "(string) 預設選取值",
        hidden: "(Boolean|String|Array) 要隱藏的鄉鎮市區，預設 false"
        onChange: "(Function) onChange event"
    },
    zipcode: {
        name: "(string) 表單名稱：預設 `zipcode`",
        css: "(string) 樣式名稱",
        value: "(string) 預設選取值",
        onKeyup: "(Function) onKeyup event"
    },
    combine: "(bool) 是否將由地區號併入鄉鎮市區清單，預設 true",
    islands_key: "(array) 離島名稱，預設 ['綠島鄉', '蘭嶼鄉', '金門縣', '連江縣', '澎湖縣', '琉球鄉']",
    islands_hidden: "(bool) 是否顯示離島，預設 true"
}

授權

The MIT License