🚀 Socket Launch Week Day 5:Introducing Repository Access Permissions and Custom Roles.Learn more →
Sign In

new-ipicker

Package Overview
Dependencies
Maintainers
1
Versions
8
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

new-ipicker

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

latest
npmnpm
Version
4.0.4
Version published
Weekly downloads
34
78.95%
Maintainers
1
Weekly downloads
 
Created
Source

iPicker

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

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

查看在线示例

安装组件

CDN 引入
<!-- unpkg -->
<script src="https://unpkg.com/new-ipicker"></script>

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

    </body>
</html>

使用方法

使用内置数据源

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

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

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

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

设置默认选中值

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

监听选中项的变化

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

自定义显示层级

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

默认禁用层级

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

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

默认禁用地区

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

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

组件方法

iPicker 提供了 10 个方法：

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

// 创建组件（简写）
const picker = iPicker( "#target", { ... } );

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

// 获取选中项（前两种等效）
iPicker.get( picker );

iPicker.get( picker, "code" );

iPicker.get( picker, "name" );

iPicker.get( picker, "all" );

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

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

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

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

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

iPicker.enabled( picker, 3 );

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

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

iPicker.disabled( picker, 3 );

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

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

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

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

配置参数

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

开源协议

MIT License

浏览器支持

ChromeFirefoxOperaEdgeSafariIE
60+60+60+17+12+不支持

Keywords

iPicker
多级联动
省市区联动
省市区选择

FAQs

Package last updated on 28 Aug 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

GitHub Actions Checkout Now Blocks Risky pull_request_target Checkouts

Security News

GitHub Actions Checkout Now Blocks Risky pull_request_target Checkouts

GitHub Actions checkout now blocks risky pull_request_target checkouts by default to help prevent pwn request supply chain attacks.

By Sarah Gooding  -  Jun 20, 2026