README.md · Flash/iPicker

<br>
<h1 align="center">iPicker</h1>

<h4 align="center">无任何依赖的省市区多级联动组件</h4>

<blockquote align="center">
  这是一个轻量级的地区选择组件，可以简单快速的对 “省市区” 进行选择<br>
专门针对桌面端的现代高级浏览器，无任何第三方依赖完全使用原生 JavaScript 开发
</blockquote>

<h4 align="center">
  <a href="http://dreamer365.gitee.io/ipicker/" target="_blank">查看在线示例</a>
</h4>

<hr/>

## 安装组件

```html
<script src="ipicker.min.js"></script>
```

```html
<script src="https://unpkg.com/new-ipicker"></script>
<script src="https://cdn.jsdelivr.net/npm/new-ipicker"></script>
```

```javascript
npm i new-ipicker -S
const iPicker = require( "new-ipicker" );
```
<hr/>

## 示例代码

```html
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>iPicker 基础示例代码</title>
    </head>
    <body>

<div id="target"></div>
        
        
        <script src="ipicker.min.js"></script>
        
        <script>

// 调用 iPicker 方法
            iPicker.create("#target", {
                data: {
                    
                    // 此处以通过 jquery 库获取本地数据源为例
                    source: Promise.resolve( $.getJSON( "area.json" ) )
                }
            })
        </script>

</body>
</html>
```

<hr/>

## 使用方法
- [使用内置数据源](#a)
- [使用自定义数据源](#b)
- [可选主题模式](#c)
- [设置默认选中值](#d)
- [监听选中项的变化](#e)
- [自定义显示层级](#g)
- [默认禁用层级](#h)
- [默认禁用地区](#i)

<h4 id="a">使用内置数据源</h4>
<b>注：内置数据源中的所有数据均来自于公开的网络搜索（目前，地区和区划代码的最新数据截止于2021-10-31）。</b>
<br><br>
<b>提示：内置数据源中暂无香港特别行政区、澳门特别行政区和台湾省等地区的数据。</b>
<br><br>

```html
<div id="target"></div>

<h4 id="b">使用自定义数据源</h4>

```html
<div id="target"></div>

<script>
    iPicker.create("#target", {
        data: {
            source: function ( code, level ) {
                var data = "";

// level 表示层级（范围 1-3 代表：省-市-区）
                switch ( level ) {

// 省数据源
                    // 初始状态下，iPicker 会自动执行一次 source 函数来获取 “省份” 数据，此时传入的 code 参数值为 null
                    // 因此，开发者可能需要给 code 参数设置一个默认值来获取 “省份” 数据（如示例代码中 areaId=0）
                    case 1: data = $.get( "http://www.abcddcba.com/api/province/areaId=0" ); break;

// 市数据源
                    case 2: data = $.get( "http://www.abcddcba.com/api/city/areaId=" + code ); break;

// 区数据源
                    case 3: data = $.get( "http://www.abcddcba.com/api/district/areaId=" + code ); break;
                }
                return data;
            }
        }
    });
</script>

<script>
    iPicker.create("#target", {
        data: {
            props: {
                code: "areaId",
                name: "areaName"
            },
            source: code => $.get( "http://www.abcddcba.com/api/area/areaId=" + ( code || 0 ) )
        }
    });
</script>
```

<h4 id="c">可选主题模式</h4>

```javascript
// select 模式
iPicker.create("#target", {
    data: {
        source: Promise.resolve( $.getJSON( "area.json" ) )
    },
    theme: "select"
});

// cascader 模式
iPicker.create("#target", {
    data: {
        source: Promise.resolve( $.getJSON( "area.json" ) )
    },
    theme: "cascader"
});

// panel 模式
iPicker.create("#target", {
    data: {
        source: Promise.resolve( $.getJSON( "area.json" ) )
    },
    theme: "panel"
});
```

<h4 id="d">设置默认选中值</h4>

```javascript
iPicker.create("#target", {
    data: {
        source: Promise.resolve( $.getJSON( "area.json" ) )
    },
    selected: [ "230000", "230100", "230103" ],
    selectedCallback: () => console.log( "默认值设置成功" )
});
```

<h4 id="e">监听选中项的变化</h4>

```javascript
iPicker.create("#target", {
    data: {
        source: Promise.resolve( $.getJSON( "area.json" ) )
    },
    onSelect: ( code, name, all ) => {
            
        // 返回参数均为数组形式
        console.log( code );
        console.log( name );
        console.log( all );
    }
});
```

<h4 id="g">自定义显示层级</h4>

```javascript
iPicker.create("#target", {
    data: {
        source: Promise.resolve( $.getJSON( "area.json" ) )
    },
    level: 2
});
```

<h4 id="h">默认禁用层级</h4>

```javascript
// 禁用全部层级
iPicker.create("#target", {
    data: {
        source: Promise.resolve( $.getJSON( "area.json" ) )
    },
    disabled: true
});

// 禁用指定层级，仅限 select 主题模式下
iPicker.create("#target", {
    data: {
        source: Promise.resolve( $.getJSON( "area.json" ) )
    },
    disabled: [ 2, 3 ]
});
```

<h4 id="i">默认禁用地区</h4>

```javascript
// 禁用全部地区
iPicker.create("#target", {
    data: {
        source: Promise.resolve( $.getJSON( "area.json" ) )
    },
    disabledItem: true
});

// 禁用指定地区
iPicker.create("#target", {
    data: {
        source: Promise.resolve( $.getJSON( "area.json" ) )
    },
    disabledItem: [ "230000", "230100", "230103" ]
});
```

<b>iPicker 提供了 10 个方法：</b>

```javascript
// 01. 创建组件
const picker = iPicker.create( "#target", { ... } );

// 01. 创建组件（上述用法的简写）
const picker = iPicker( "#target", { ... } );

// 02. 设置选中项
iPicker.set( picker, [ "230000", "230100", "230103" ] );

// 03. 获取选中项（前两种等效）
iPicker.get( picker );
iPicker.get( picker, "code" );
iPicker.get( picker, "name" );
iPicker.get( picker, "all" );

// 04. 清空选中项
iPicker.clear( picker );

// 05. 重置（恢复初始状态）
iPicker.reset( picker );

// 06. 销毁组件
iPicker.destroy( picker );

// 07. 启用所有层级
iPicker.enabled( picker, true );

// 07. 启用指定层级，范围：1 - 3，仅限 select 主题模式下
iPicker.enabled( picker, [ 2, 3 ] );
iPicker.enabled( picker, 3 );

// 08. 禁用所有层级
iPicker.disabled( picker, true );

// 08. 禁用指定层级，范围：1 - 3，仅限 select 主题模式下
iPicker.disabled( picker, [ 2, 3 ] );
iPicker.disabled( picker, 3 );

// 09. 启用所有地区
iPicker.enabledItem( picker, true );

// 09. 启用指定地区
iPicker.enabledItem( picker, [ "230000" ] );

// 10. 禁用所有地区
iPicker.disabledItem( picker, true );

// 10. 禁用指定地区
iPicker.disabledItem( picker, [ "230000" ] );
```

<hr/>

<h2 id="j">配置参数</h2>
<table>
    <tr>
        <td width="170">参数</td>
        <td>说明</td>
        <td>类型</td>
        <td width="160">默认值</td>
    </tr>
    <tr>
        <td>theme</td>
        <td>主题模式，可选值：select、cascader、panel</td>
        <td>String</td>
        <td>select</td>
    </tr>
    <tr>
        <td>data</td>
        <td>设置数据源，共有三个属性：
            <br> <span>1. props：数据属性映射（仅能用于自定义数据源）</span>
            <br> <span>2. source：数据源类型（Promise 类型表示使用本地数据源；Function 类型表示使用自定义数据源）</span>
            <br> <span>3. when：数据源加载成功后执行的函数，可对数据进行最后的处理（若设置了此函数，则一定要在函数中返回处理过的数据，函数有两个参数：原始数据和数据对应的层级，层级只在自定义数据源时有效）</span></td>
        <td>Object</td>
        <td> {
            <br> &nbsp;props: {
            <br> &nbsp;&nbsp;code: "code",
            <br> &nbsp;&nbsp;name: "name"
            <br> &nbsp;},
            <br> &nbsp;source: null,
            <br> &nbsp;when: null
            <br> } </td>
    </tr>
    <tr>
        <td>level</td>
        <td>展示的层级，可选值：1、2、3</td>
        <td>Number</td>
        <td>3</td>
    </tr>
    <tr>
        <td>width</td>
        <td>展示框的宽度，可设置为 Number 类型，单位：px，也可设置为百分比</td>
        <td>Number / String</td>
        <td>200</td>
    </tr>
    <tr>
        <td>height</td>
        <td>展示框的高度，单位：px</td>
        <td>Number</td>
        <td>34</td>
    </tr>
    <tr>
        <td>radius</td>
        <td>展示框和下拉列表的圆角值，单位：px</td>
        <td>Number</td>
        <td>2</td>
    </tr>
    <tr>
        <td>maxHeight</td>
        <td>下拉列表的最大高度，单位：px</td>
        <td>Number</td>
        <td>300</td>
    </tr>
    <tr>
        <td>disabled</td>
        <td>禁用层级，设置为 true 则禁用所有层级，设置为 Number 或 Array 则禁用指定层级</td>
        <td>Boolean / Number / Array</td>
        <td>[]</td>
    </tr>
    <tr>
        <td>disabledItem</td>
        <td>禁用指定的地区，设置为 true 则禁用所有地区，设置为 Array 则禁用指定地区（传入行政编码）</td>
        <td>Boolean / Array</td>
        <td>[]</td>
    </tr>
    <tr>
        <td>selected</td>
        <td>默认值（传入行政编码）</td>
        <td>Array</td>
        <td>[]</td>
    </tr>
    <tr>
        <td>selectedCallback</td>
        <td>成功设置了默认值后执行的函数，主要应用于自定义数据源的情况（因为自定义数据源是异步获取数据）</td>
        <td>Function</td>
        <td>空函数</td>
    </tr>
    <tr>
        <td>placeholder</td>
        <td>展示框的默认提示文字，select 主题下是 Array 类型，cascader 和 panel 主题下是 String 类型</td>
        <td>Array / String</td>
        <td>[ "省", "市", "区" ]</td>
    </tr>
    <tr>
        <td>separator</td>
        <td>cascader 和 panel 主题下，展示结果中的文字分隔符</td>
        <td>String</td>
        <td>/</td>
    </tr>
    <tr>
        <td>onlyShowLastLevel</td>
        <td>cascader 和 panel 主题下，在展示框中只显示选中结果的最后一级数据</td>
        <td>Boolean</td>
        <td>false</td>
    </tr>
    <tr>
        <td>clearable</td>
        <td>在展示框右侧显示清空按钮（鼠标悬浮在展示框上时显示）</td>
        <td>Boolean</td>
        <td>false</td>
    </tr>
    <tr>
        <td>strict</td>
        <td>严格模式</td>
        <td>Boolean</td>
        <td>false</td>
    </tr>
    <tr>
        <td>icon</td>
        <td>展示框末端的图标，可选值：triangle、arrow</td>
        <td>String</td>
        <td>triangle</td>
    </tr>
    <tr>
        <td>onClear</td>
        <td>点击清空按钮时执行的函数</td>
        <td>Function</td>
        <td>空函数</td>
    </tr>
    <tr>
        <td>onSelect</td>
        <td>选中地区时执行的函数，有三个参数：行政编码、地区名称、编码与名称的集合体</td>
        <td>Function</td>
        <td>空函数</td>
    </tr>
</table>

<hr/>

<h2 id="k">开源协议</h2>
<p><a href="https://gitee.com/dreamer365/iPicker/blob/master/LICENSE">MIT License</a></p>

<hr/>

<h2 id="l">浏览器支持</h2>

| Chrome | Firefox | Opera | Edge | Safari | IE  |
| ---    | ---     | ---   | ---  | ---    | --- |
| 60+    | 60+     | 60+   | 17+  | 12+    | 不支持 |

Flash/iPicker

简介

发行版

贡献者

近期动态

Flash/iPicker .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

Flash/iPicker