⚠️ [Deprecated] No longer main

Distpicker

A simple jQuery plugin for picking provinces, cities and districts of China.

Website

请注意以下市/县并未设置下一级的区：济源市、潜江市、神农架林区、天门市、仙桃市、东莞市、中山市、东沙群岛、白沙黎族自治县、保亭黎族苗族自治县、昌江黎族自治县、澄迈县、儋州市、定安县、东方市、乐东黎族自治县、临高县、陵水黎族自治县、琼海市、琼中黎族苗族自治县、屯昌县、万宁市、文昌市、五指山市、嘉峪关市、阿拉尔市、北屯市、可克达拉市、昆玉市、石河子市、双河市、铁门关市、图木舒克市、五家渠市。

Table of contents Main Getting started Options Methods No conflict Browser support License Main files

dist/ ├── distpicker.js (UMD) ├── distpicker.min.js (UMD, compressed) ├── distpicker.common.js (CommonJS, default) └── distpicker.esm.js (ES Module) Getting started Install

npm install distpicker

Include files:

<script src="/path/to/jquery.js"></script><!-- jQuery is required --> <script src="/path/to/distpicker.js"></script>

Create HTML elements:

<div><!-- container --> <select></select><!-- province --> <select></select><!-- city --> <select></select><!-- district --> </div> Usage Initialize with data-toggle="distpicker" attribute

Basic

<div data-toggle="distpicker"> <select></select> <select></select> <select></select> </div>

Custom placeholders

<div data-toggle="distpicker"> <select data-province="---- 选择省 ----"></select> <select data-city="---- 选择市 ----"></select> <select data-district="---- 选择区 ----"></select> </div>

Custom districts

<div data-toggle="distpicker"> <select data-province="浙江省"></select> <select data-city="杭州市"></select> <select data-district="西湖区"></select> </div> Initialize with $.fn.distpicker method

Basic

$('#target').distpicker();

Custom placeholders

$('#target').distpicker({ province: '---- 所在省 ----', city: '---- 所在市 ----', district: '---- 所在区 ----' });

Custom districts

$('#target').distpicker({ province: '浙江省', city: '杭州市', district: '西湖区' });

back to top

Options Change the default options with $().distpicker(options). Change the global default options with $.fn.distpicker.setDefaults(options).

Also supports to set the options by data-* attributes:

<div data-toggle="distpicker" data-autoselect="3" data-province="浙江省">...</div> autoselect Type: Number Options: 0: Disable autoselect. 1: Autoselect province only. 2: Autoselect province and city only. 3: Autoselect all (province, city and district). Default: 0

Selects the districts automatically.

placeholder Type: Boolean Default: true

Show placeholder (with an <option> element).

valueType Type: String Options: 'name': administrative division name. 'code': administrative division code. Default: 'name'

Defines the value type of the <select> element.

Note that this option in data-* attribute should be data-value-type:

<div data-toggle="distpicker" data-value-type="code">...</div> province Type: String Default: —— 省 ——

Defines the initial value of province <select>. If it is a valid province, it will be selected. If not, it will be used as a placeholder.

city Type: String Default: —— 市 ——

Defines the initial value of city <select>. If it is a valid city under the selected province, it will be selected. If not, it will be used as a placeholder.

district Type: String Default: —— 区 ——

Defines the initial value of district <select>. If it is a valid district under the selected city, it will be selected. If not, it will be used as a placeholder.

back to top

Methods getDistricts([districtCode])

districtCode (optional):

Type: Number The district code of target country, province or city. If not present, will return all the districts.

(return value):

Type: Object

Get districts data.

$().distpicker('getDistricts'); // 中国 $().distpicker('getDistricts', 330000); // 浙江省 $().distpicker('getDistricts', 330100); // 杭州市 reset([deep]) deep (optional): Type: Boolean Default: false Reset the selects to default states (Undo selected).

Reset the selects to the initial states (Undo changed).

$().distpicker('reset'); $().distpicker('reset', true); destroy()

Destroy the distpicker instance, but keep the selected districts.

If you want to remove the selected districts, you can call reset method first and then call this method.

back to top

No conflict

If you have to use other plugin with the same namespace, just call the $.fn.distpicker.noConflict method to revert to it.

<script src="other-plugin.js"></script> <script src="distpicker.js"></script> <script> $.fn.distpicker.noConflict(); // Code that uses other plugin's "$().distpicker" can follow here. </script> Browser support Chrome (latest) Firefox (latest) Safari (latest) Opera (latest) Edge (latest) Internet Explorer 9+

As a jQuery plugin, you also need to see the jQuery Browser Support.

License

MIT © Chen Fengyuan

back to top