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

    </body>
</html>

使用方法

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

使用内置数据源

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

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

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

使用自定义数据源

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

<script>
    iPicker("#target", {
        data: {
            
            // 此处以通过 jquery 库获取数据为例
            // 示例代码中使用的 "http://www.abcddcba.com/api/area" 是模拟地址，实际应用中替换成真实地址即可
            // code 参数值就是相应地区对应的行政区划代码
            // ----------------------------------------------------------------------------------------------------------
            // 使用自定义数据源时，必须保证 source 属性值是 Function 类型
            // iPicker 会自动执行此函数，同时要确保此函数的执行结果返回的是标准的 Promise 对象或者是 jquery 提供的 Deferred 对象
            // iPicker 会自动调用 then 方法，同时要确保 then 方法的参数就是返回的数据（Array 类型）
            // ----------------------------------------------------------------------------------------------------------
            // 初始状态下，iPicker 会自动执行一次 source 函数来获取 “省份” 数据，此时传入的 code 参数值为 null
            // 因此，开发者可能需要给 code 参数设置一个默认值来获取 “省份” 数据（如示例代码中 code 为 null 时默认为零）
            source: function ( code ) {
                return $.get( "http://www.abcddcba.com/api/area/areaId=" + ( code || 0 ) );
            }
        }
    });
</script>


<!-- 上面的示例代码使用了一个统一的地址返回数据 -->
<!-- 也可以传入第二个参数，根据此参数可分别设置 “省市区” 不同的数据源 -->
<script>
    iPicker("#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("#target", {
        data: {
            props: {
                code: "areaId",
                name: "areaName"
            },
            source: function ( code ) {
                return $.get( "http://www.abcddcba.com/api/area/areaId=" + code );
            }
        }
    });
</script>

可选主题模式

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

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

设置默认选中值

iPicker("#target", {
    data: {
        source: $.getJSON( "area.json" )
    },
    selected: [ "230000", "230100", "230103" ]
});

监听选中项的变化

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

自定义主题颜色

iPicker("#target", {
    data: {
        source: $.getJSON( "area.json" )
    },
    activeStyle: {
        color: "#09f",
        borderColor: "#A600DB",
        backgroundColor: "#A600DB"
    }
});

自定义显示层级

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

默认禁用

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

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

组件方法

iPicker 提供了六个方法： 输入图片说明

var picker = iPicker( "#target", {} );

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

// 清空选中结果
iPicker.clear( picker );

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

// 启用（全部）
iPicker.enabled( picker );

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

// 禁用（全部）
iPicker.disabled( picker );

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

// 销毁（移除 iPicker 组件）
iPicker.destroy( picker );

配置参数

参数	说明	类型	默认值
theme	主题模式，可选值：select、cascader	String	select
data	设置数据源，共有 2 个属性： 01. props: 自定义数据源的数据属性映射（用于自定义数据源，使用内置数据源时无效） 02. source: 数据来源：返回 Promise 表示加载本地数据源；返回 Function 表示使用自定义数据源；	Object	{ props: { code: "code", name: "name" }, data: null }
level	数据的展示层级，有效范围：1-3（代表 1-3 级，省-市-区）	Number	3
width	展示框的宽度，单位：px，不能小于 90（如果设置了小于 90 的值则按照 90 处理）	Number	200
maxHeight	下拉列表的最大高度，单位：px，不能小于 46（如果设置了小于 46 的值则按照 46 处理）	Number	300
disabled	默认禁用的展示框，有 3 种设置方式： 01. 设置为 true 则禁用所有展示框； 02. 设置为 1-3 范围内的数字，则禁用单个指定层级的展示框（仅限 select 模式下）； 03. 设置为 Array 形式，则禁用单个/多个指定层级的展示框（仅限 select 模式下）例如： disabled: true（禁用所有展示框） disabled: [ 2, 3 ] （禁用第 2，3 级展示框） disabled: 3 （禁用第 3 级展示框）	Boolean / Array / Number	false
selected	默认选中项，需要传入地区相应的 code 值注意：selected 设置的层级数（即：数组长度）必须与 level 相同，否则无效例如： selected: [ "230000", "230100", "230103" ], level: 3	Array	[]
selectedCallback	默认选中项设置成功后执行的回调函数，有 3 个回调参数： 1. code 数组 2. name 数组 3. code 与 name 的数组集合提示：此属性一般用于 “自定义数据源” 的情况，因为自定义数据源需要发送请求来获取地区数据，就会存在网络请求导致的延时，因此可能需要用此属性来执行一些操作而使用内置数据源时，因为在初始化阶段已经一次性加载了全部数据，不存在延时问题因此一般不会用到这个属性。	Function	空函数
placeholder	展示框的占位文字，select 模式下是 Array 形式，cascader 模式下是 String 形式	Array / String	[ "省", "市", "区" ]
onSelect	选择项改变时执行的回调函数，有 3 个回调参数： 1. code 数组 2. name 数组 3. code 与 name 的数组集合	Function	空函数
activeStyle （v3.0.0新增）	设置选中项的激活颜色	Object	{ color: "#00b8ff", borderColor: "#00b8ff", backgroundColor: "#f5f5f5" }
separator （v3.0.0新增）	cascader 主题模式下，展示框内的选择结果的分隔符	String	/
strict （v3.0.0新增）	开启 strict 时 cascader 主题模式下，当关闭列表时，如果选择的结果层级与设置的 level 不等，则选择无效 select 主题模式下会自动将下一级的第一个选项选中	Boolean	false
onlyShowLastLevel （v3.0.0新增）	cascader 主题下设置只显示所选地区的最后一项	Boolean	false
arrowTheme （v3.0.0新增）	设置选择框结尾的箭头图标的样式，可选值：arrow, arrow-outline	String	arrow

友情提示

当使用【自定义数据源】时，只要设置好 data.props 属性，iPicker 就能实现任何数据的选择匹配功能（绝不仅限于地区选择哦）

开源协议

MIT License

更新日志

浏览器支持

Chrome	Firefox	Opera	Edge	Safari	IE
60+	60+	60+	17+	12+	11+

wekomrc / iPicker

iPicker

无任何依赖的轻量级地区选择组件

查看在线示例

最新版本

安装组件

本地引入

cdn 引入

npm 安装

示例代码

使用方法

使用内置数据源

使用自定义数据源

可选主题模式

设置默认选中值

监听选中项的变化

自定义主题颜色

自定义显示层级

默认禁用

组件方法

配置参数

友情提示

开源协议

更新日志

浏览器支持

简介

发行版

贡献者

近期动态

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

iPicker

无任何依赖的轻量级地区选择组件

查看在线示例

最新版本

安装组件

本地引入

cdn 引入

npm 安装

示例代码

使用方法

使用内置数据源

使用自定义数据源

可选主题模式

设置默认选中值

监听选中项的变化

自定义主题颜色

自定义显示层级

默认禁用

组件方法

配置参数

友情提示

开源协议

更新日志

浏览器支持

简介

发行版

贡献者

近期动态

搜索帮助

wekomrc / iPicker