30 Star 254 Fork 42

FeCoder / iPicker

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
MIT

iPicker

原生 JavaScript 开发的省市区多级联动组件

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

查看在线示例


安装组件

unpkg cdn

<script src="https://unpkg.com/new-ipicker@latest"></script>

jsdelivr cdn

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

npm 安装

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

基础用法

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

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

使用方法

使用内置数据源

声明:内置数据源中的所有数据均来自于公开的网络搜索(最新数据截止于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+ 不支持
MIT License Copyright (c) 2020-present ZG Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

简介

原生 JavaScript 开发的省市区多级联动组件 展开 收起
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
JavaScript
1
https://gitee.com/dreamer365/iPicker.git
git@gitee.com:dreamer365/iPicker.git
dreamer365
iPicker
iPicker
master

搜索帮助

14c37bed 8189591 565d56ea 8189591