开源软件名称：

iPicker

开源软件地址：

https://gitee.com/dreamer365/iPicker

开源软件介绍：

iPicker

无任何依赖的省市区多级联动组件

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

查看在线示例

安装组件

本地引入

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

cdn 引入

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

npm 安装

npm i new-ipicker -Sconst iPicker = require( "new-ipicker" );

示例代码

<!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.create("#target", {                data: {                                        // 此处以通过 jquery 库获取本地数据源为例                    source: Promise.resolve( $.getJSON( "area.json" ) )                }            })        </script>    </body></html>

使用方法

使用内置数据源
使用自定义数据源
可选主题模式
设置默认选中值
监听选中项的变化
自定义显示层级
默认禁用层级
默认禁用地区

使用内置数据源

注意：内置数据源中的所有地区数据均来自公开的网络搜索，因此不保证其准确性和完整性，请开发者酌情使用！
提示：内置数据源中暂无香港特别行政区、澳门特别行政区和台湾省等地区的数据！

<div id="target"></div><script>    iPicker.create("#target", {            // 此处以通过 jquery 库获取本地数据源为例        // 使用内置数据源时，必须保证 source 属性值是标准的 Promise 对象        // iPicker 会自动调用 then 方法，同时要确保 then 方法的参数就是返回的数据（Object 类型）        data: {            source: Promise.resolve( $.getJSON( "area.json" ) )        }    });</script>

使用自定义数据源

<div id="target"></div><script>    iPicker.create("#target", {        data: {                        // 此处以通过 jquery 库获取数据为例            // 示例代码中使用的 "http://www.abcddcba.com/api/area" 是模拟地址，实际应用中替换成真实地址即可            // code 参数值就是相应地区对应的行政区划代码            // ----------------------------------------------------------------------------------------------------------            // 使用自定义数据源时，必须保证 source 属性值是 Function 类型            // iPicker 会自动执行此函数，同时要确保此函数的执行结果返回的是标准的 Promise 对象            // iPicker 会自动调用 then 方法，同时要确保 then 方法的参数就是返回的数据（Array 类型）            // ----------------------------------------------------------------------------------------------------------            // 初始状态下，iPicker 会自动执行一次 source 函数来获取 “省份” 数据，此时传入的 code 参数值为 null            // 因此，开发者可能需要给 code 参数设置一个默认值来获取 “省份” 数据（如示例代码中 code 为 null 时默认取零）            source: code => $.get( "http://www.abcddcba.com/api/area/areaId=" + ( code || 0 ) )        }    });</script><!-- 上面的示例代码使用了一个统一的地址返回数据 --><!-- 也可以传入第二个参数，根据此参数可分别设置 “省市区” 不同的数据源 --><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><!--     - iPicker 默认会调用返回数据中 code 和 name 属性，例如：      [{          code: "110000",          name: "北京市"      }]    - 可以通过设置 props 来自定义属性名--><script>    iPicker.create("#target", {        data: {            props: {                code: "areaId",                name: "areaName"            },            source: code => $.get( "http://www.abcddcba.com/api/area/areaId=" + ( code || 0 ) )        }    });</script>

可选主题模式

// 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"});

设置默认选中值

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

监听选中项的变化

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

自定义显示层级

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

默认禁用层级

// 禁用全部层级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 ]});

默认禁用地区

// 禁用全部地区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" ]});

组件方法

iPicker 提供了 10 个方法：

// 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" ] );

配置参数

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