Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fengyuanchen/distpicker
⚠️ [Deprecated] No longer maintained. A simple jQuery plugin for picking provinces, cities and districts of China. (中国 / 省市区 / 三级联动 / 地址选择器)
https://github.com/fengyuanchen/distpicker
china district jquery-plugin picker
Last synced: 7 days ago
JSON representation
⚠️ [Deprecated] No longer maintained. A simple jQuery plugin for picking provinces, cities and districts of China. (中国 / 省市区 / 三级联动 / 地址选择器)
- Host: GitHub
- URL: https://github.com/fengyuanchen/distpicker
- Owner: fengyuanchen
- License: mit
- Created: 2014-01-09T08:37:07.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2023-01-01T10:54:31.000Z (about 2 years ago)
- Last Synced: 2024-12-20T01:08:55.018Z (14 days ago)
- Topics: china, district, jquery-plugin, picker
- Language: JavaScript
- Homepage: https://fengyuanchen.github.io/distpicker/
- Size: 877 KB
- Stars: 1,641
- Watchers: 72
- Forks: 464
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Distpicker
[](https://www.npmjs.com/package/distpicker) [](https://www.npmjs.com/package/distpicker) [](https://unpkg.com/distpicker/dist/distpicker.common.js)
> A simple jQuery plugin for picking provinces, cities and districts of China.
- [Website](https://fengyuanchen.github.io/distpicker)
> 请注意以下市/县并未设置下一级的区：济源市、潜江市、神农架林区、天门市、仙桃市、东莞市、中山市、东沙群岛、白沙黎族自治县、保亭黎族苗族自治县、昌江黎族自治县、澄迈县、儋州市、定安县、东方市、乐东黎族自治县、临高县、陵水黎族自治县、琼海市、琼中黎族苗族自治县、屯昌县、万宁市、文昌市、五指山市、嘉峪关市、阿拉尔市、北屯市、可克达拉市、昆玉市、石河子市、双河市、铁门关市、图木舒克市、五家渠市。
## Table of contents
- [Main](#main)
- [Getting started](#getting-started)
- [Options](#options)
- [Methods](#methods)
- [No conflict](#no-conflict)
- [Browser support](#browser-support)
- [License](#license)
## Main files
```text
dist/
├── distpicker.js (UMD)
├── distpicker.min.js (UMD, compressed)
├── distpicker.common.js (CommonJS, default)
└── distpicker.esm.js (ES Module)
```
## Getting started
### Install
```shell
npm install distpicker
```
Include files:
```html
```
Create HTML elements:
```html
```
### Usage
#### Initialize with `data-toggle="distpicker"` attribute
Basic
```html
```
Custom placeholders
```html
```
Custom districts
```html
```
#### Initialize with `$.fn.distpicker` method
Basic
```js
$('#target').distpicker();
```
Custom placeholders
```js
$('#target').distpicker({
province: '---- 所在省 ----',
city: '---- 所在市 ----',
district: '---- 所在区 ----'
});
```
Custom districts
```js
$('#target').distpicker({
province: '浙江省',
city: '杭州市',
district: '西湖区'
});
```
[⬆ back to top](#table-of-contents)
## 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:
```html
...
```
### 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 `` element).
### valueType
- Type: `String`
- Options:
- `'name'`: administrative division name.
- `'code'`: administrative division code.
- Default: `'name'`
Defines the value type of the `` element.
Note that this option in `data-*` attribute should be `data-value-type`:
```html
...
```
### province
- Type: `String`
- Default: `—— 省 ——`
Defines the initial value of province ``. 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 ``. 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 ``. 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](#table-of-contents)
## 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.
```js
$().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).
```js
$().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](#table-of-contents)
## No conflict
If you have to use other plugin with the same namespace, just call the `$.fn.distpicker.noConflict` method to revert to it.
```html
$.fn.distpicker.noConflict();
// Code that uses other plugin's "$().distpicker" can follow here.
```
## 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](https://jquery.com/browser-support/).
## License
[MIT](https://opensource.org/licenses/MIT) © [Chen Fengyuan](https://chenfengyuan.com/)
[⬆ back to top](#table-of-contents)