85

0

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 -S
const iPicker = require( "new-ipicker" );

示例代码

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

        <!-- 目标容器 -->
        <div id="target"></div>

        <!-- 引入 iPicker 脚本文件 -->
        <script src="ipicker.min.js"></script>

        <script>

            // 调用 iPicker 方法
            iPicker.create("#target", {
                data: {

                    // 此处以通过 jquery 库获取本地数据源为例
                    source: Promise.resolve( $.getJSON( "area.json" ) )
                }
            })
        </script>

    </body>
</html>

使用方法

使用内置数据源

注:内置数据源中的所有数据均来自于公开的网络搜索(目前,地区和区划代码的最新数据截止于2021-10-31)。

提示:内置数据源中暂无香港特别行政区、澳门特别行政区和台湾省等地区的数据。

<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 空函数

开源协议

MIT License


浏览器支持

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