cityAreaSelect.js使用說明

一、簡介

該JS為省市區選擇外掛，當前最新版本為1.0，外掛中地區資料更新於2024年07月02日，外掛不依賴第三方JS，可獨立使用。

github地址：https://github.com/TammyViola/cityAreaSelect

二、CSS和JS引用

PS：樣式可根據專案實際情況進行調整

<link href="./dist/css/cityAreaSelect.css" rel="stylesheet" type="text/css"/>
...
<script type="text/javascript" src="./dist/js/cityAreaSelect.min.js"></script>

三、html編寫及對應JS呼叫

1. 省市區-select控制元件-3級聯動

1）html程式碼：

<div class="cityAreaSelect-group row">
    <div class="cityAreaSelect-item col-md-4">
        <select class="cityAreaSelect-select" id="provinceSelect1">
            <option value="">請選擇省/直轄市</option>
        </select>
    </div>
    <div class="cityAreaSelect-item col-md-4">
        <select class="cityAreaSelect-select" id="citySelect1">
            <option value="">請選擇城市/區</option>
        </select>
    </div>
    <div class="cityAreaSelect-item col-md-4">
        <select class="cityAreaSelect-select" id="areaSelect1">
            <option value="">請選擇區/縣</option>
        </select>
    </div>
</div>

2）JS程式碼：

const pcaSelect1 = new ProvinceCityAreaSelect({
    addrValElem: ['provinceSelect1', 'citySelect1', 'areaSelect1'],
    onInit: function(provinceSelect, citySelect, areaSelect){
        //console.log(provinceSelect+', '+citySelect+', '+areaSelect)
    },
    onSelected: function(provinceVal, cityVal, areaVal){
        //console.log(provinceVal+', '+cityVal+', '+areaVal)
    }
});

2. 省市-select控制元件-2級聯動

1）html程式碼：

<div class="cityAreaSelect-group row">
    <div class="cityAreaSelect-item col-md-6">
        <select class="cityAreaSelect-select" id="provinceSelect2">
            <option value="">請選擇省/直轄市</option>
        </select>
    </div>
    <div class="cityAreaSelect-item col-md-6">
        <select class="cityAreaSelect-select" id="citySelect2">
            <option value="">請選擇城市/區</option>
        </select>
    </div>
</div>

2）JS程式碼：

const pcaSelect2 = new ProvinceCityAreaSelect({
    addrValElem: ['provinceSelect2', 'citySelect2']
});

3. 省市區-自定義div控制元件-3級聯動

1）html程式碼：

<div class="cityAreaSelect-group row">
    <div class="cityAreaSelect-item col-md-4">
        <div class="cityAreaSelect-custom-box">
            <input type="text" hidden class="cityAreaSelect-input" id="provinceSelect3">
            <div class="cityAreaSelect-text">請選擇省/直轄市</div>
        </div>
    </div>
    <div class="cityAreaSelect-item col-md-4">
        <div class="cityAreaSelect-custom-box">
            <input type="text" hidden class="cityAreaSelect-input" id="citySelect3">
            <div class="cityAreaSelect-text">請選擇城市/區</div>
        </div>
    </div>
    <div class="cityAreaSelect-item col-md-4">
        <div class="cityAreaSelect-custom-box">
            <input type="text" hidden class="cityAreaSelect-input" id="areaSelect3">
            <div class="cityAreaSelect-text">請選擇區/縣</div>
        </div>
    </div>
</div>

2）JS程式碼：

const pcaSelect3 = new ProvinceCityAreaSelect({
    addrValElem: ['provinceSelect3', 'citySelect3', 'areaSelect3'],
    onSelected: function(provinceVal, cityVal, areaVal){
        //console.log(provinceVal+', '+cityVal+', '+areaVal)
    }
});

4. 省市區-自定義div控制元件-2級聯動

1）html程式碼：

<div class="cityAreaSelect-group row">
    <div class="cityAreaSelect-item col-md-6">
        <div class="cityAreaSelect-custom-box">
            <input type="text" hidden class="cityAreaSelect-input" id="provinceSelect4">
            <div class="cityAreaSelect-text">請選擇省/直轄市</div>
        </div>
    </div>
    <div class="cityAreaSelect-item col-md-6">
        <div class="cityAreaSelect-custom-box">
            <input type="text" hidden class="cityAreaSelect-input" id="citySelect4">
            <div class="cityAreaSelect-text">請選擇城市/區</div>
        </div>
    </div>
</div>

2）JS程式碼：

const pcaSelect4 = new ProvinceCityAreaSelect({
    addrValElem: ['provinceSelect4', 'citySelect4']
});

5. 省市區-自定義div控制元件-多級合併

1）html程式碼：

<div class="cityAreaSelect-wrapper">
    <div class="cityAreaSelect-group row">
        <div class="cityAreaSelect-item col-md-8">
            <div class="cityAreaSelect-merge-box">
                <input type="text" hidden class="cityAreaSelect-input" id="provinceSelect5">
                <div class="cityAreaSelect-text">請選擇省市區</div>
            </div>
        </div>
    </div>
</div>

2）JS程式碼：

const pcaSelect5 = new ProvinceCityAreaSelect({
    addrValElem: 'provinceSelect5',
    separator: '-',
    onInit: function(provinceSelect, citySelect, areaSelect){
        //console.log(provinceSelect+', '+citySelect+', '+areaSelect)
    },
});

3）效果預覽：

四、引數說明

引數值	引數值型別	預設值	說明
addrValElem	String / Array	null	1. Array型別：省市區控制元件Id，例如：['provinceSelect1', 'citySelect1', 'areaSelect1'] 2. String型別：自定義div省市區多級合併時使用，引數值為隱藏域input的Id，例如： 'cityAreaInput'
separator	String	' '（空格符）	自定義div省市區多級合併時使用，自定義省市區地名間的間隔連線符號； 例如：separator: '-' （北京市-東城區）
provinceWord	String	'請選擇省/直轄市'	省/市佔位提示語
cityWord	String	'請選擇城市/區'	市/區佔位提示語
areaWord	String	'請選擇區/縣'	區/縣佔位提示語
mergeWord	String	'請選擇省市區'	1. 省市區合併時且web端才有效，其他時候無效； 2. 省市區合併顯示控制元件佔位提示語
onInit	Function	null	JS初始載入後回撥，可返回省市區控制元件id值
onSelected	Function	null	省市區選擇後回撥，可返回省市區當前值value

五、Events事件

1. onInit ：初始載入後回撥

該引數為外掛初始載入後回撥，可返回省市區控制元件id值。

const pcaSelect = new ProvinceCityAreaSelect({
    addrValElem: ['provinceSelect', 'citySelect', 'areaSelect'],
    onInit: function(provinceSelect, citySelect, areaSelect){
        //console.log(provinceSelect+', '+citySelect+', '+areaSelect)
    }
});

2. onSelected : 省市區選擇後回撥

該引數為外掛 省市區選擇後回撥，可返回省市區當前值value。

const pcaSelect = new ProvinceCityAreaSelect({
    addrValElem: ['provinceSelect', 'citySelect', 'areaSelect'],
    onSelected: function(provinceVal, cityVal, areaVal){
        //console.log(provinceVal+', '+cityVal+', '+areaVal)
    }
});