distpicker

    2.0.7 • Public • Published

    Distpicker

    Downloads Version Gzip Size

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

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

    Table of contents

    Main

    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

    Install

    npm i distpicker

    DownloadsWeekly Downloads

    20

    Version

    2.0.7

    License

    MIT

    Unpacked Size

    496 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar