iPicker v4.0.4 star

Select 主题

基本用法

线形箭头

自定义层级

禁用指定层级的展示框

对于 select 主题，最多有三级展示框，示例中禁用 2-3 级。

默认值

严格模式

对于 select 主题，开启严格模式，每选中一个地区后，则会自动选中后面层级中的第一个选项。此设置可以保证当列表关闭时，已选择了所有选项。

自定义圆角值

限制列表高度

清空按钮

对于 select 主题，点击清空按钮，会清空当前和后续层级的选中项。

禁用指定地区

Cascader 主题

基本用法

线形箭头

自定义层级

禁用指定层级的展示框

对于 cascader 主题，只有一级展示框，示例中禁用了这一级。

默认值

严格模式

对于 cascader 主题，开启严格模式，当关闭列表时，如果所选结果的层级与设置的层级数不等，则会自动选中所有未选择的层级中的第一个选项。

自定义圆角值

限制列表高度

清空按钮

对于 cascader 主题，点击清空按钮，会清空当前所有选中项。

禁用指定地区

分隔符

cascader 和 panel 独有功能。

只展示最后一级结果

cascader 和 panel 独有功能。

Panel 主题

基本用法

线形箭头

自定义层级

禁用指定层级的展示框

对于 panel 主题，只有一级展示框，示例中禁用了这一级。

默认值

严格模式

对于 panel 主题，开启严格模式，当关闭列表时，如果所选结果的层级与设置的层级数不等，则会自动选中所有未选择的层级中的第一个选项。

自定义圆角值

限制列表高度

清空按钮

对于 panel 主题，点击清空按钮，会清空当前所有选中项。

禁用指定地区

分隔符

cascader 和 panel 独有功能。

只展示最后一级结果

cascader 和 panel 独有功能。

安装使用

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

组件方法

# 创建组件

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、panel String select
data 设置数据源，共有三个属性：
1. props：数据属性映射（仅能用于自定义数据源）
2. source：数据源类型（Promise 类型表示使用本地数据源；Function 类型表示使用自定义数据源）
3. when：数据源加载成功后执行的函数，可对数据进行最后的处理（若设置了此函数，则一定要在函数中返回处理
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 空函数

更新日志

v4.0.4 2023-08-28

修复

  • 通过 iPicker.set 设置三级数据时，cascader 和 panel 主题下只展示两级数据的 Bug。

v4.0.3 2022-11-02

修复

  • 使用自定义数据源时，第三级数据在 select 主题下无法选中的 Bug；
  • onSelect 事件会出现多执行一次的 Bug。

v4.0.2 2021-03-30

修复

  • 内置数据源的数据缓存 Bug。

v4.0.1 2021-02-20

修复

  • v4.0.0 版本中，当设置了 clearable 属性，如果组件被禁用，鼠标滑过选择框时依然显示清除按钮的 Bug。

v4.0.0 2021-02-03

新增

  • data 属性下新增 when 属性；
  • 增加 panel 主题；
  • 增加 clearable 属性；
  • 增加 onClear 属性；
  • 增加 height 属性；
  • 增加 disabledItem 属性；
  • 增加 iPicker.disabledItem() 方法；
  • 增加 iPicker.enabledItem() 方法；
  • 增加位置自动检测功能，当组件处于可视区域底部时，列表会自动调整为在上方显示；

修复

  • v3.0.0 版本中调用 iPicker.clear() 方法后仍能获取到选中值的 Bug；

变更

  • 不再兼容 IE 浏览器；
  • 移除了 activeStyle 属性，现在要改变主题颜色需要手动设置 css 代码来实现；
  • arrowTheme 属性改名为 icon，同时属性值变为：triangle 和 arrow；
  • radius 默认值由 4px 改为 2px。

v3.0.0 2020-11-27

新增

  • 增加可选数据源功能，现在可自由选择使用 “内置数据源” 或 “自定义数据源”；
  • 增加 separator 属性，在 cascader 主题下可自定义选择结果的分隔符；
  • 增加 onlyShowLastLevel 属性，在 cascader 主题下可设置只显示所选地区的最后一项；
  • 增加 strict 属性，此属性将开启严格选择模式；增加 arrowTheme 属性，现在选择框结尾的箭头图标有两种主题可选；
  • 增加 selectedCallback 属性，在默认值设置成功后执行的回调函数；
  • 增加 activeStyle 属性，用来取代 activeColor 属性；
  • 增加 radius 属性，可设置结果展示框的圆角值；
  • disabled 属性，enabled 方法和 disabled 方法现在可以传入数字类型的值；

修复

  • reset 方法无法重置 disabled 属性的问题；

变更

  • iPicker 组件现在只作用于第一个匹配元素；
  • 废弃 activeColor 属性；
  • 默认选中值不再支持传入 name，只能设置相应地区的 code 值；
  • 代码进行了完全重构，现在内部使用了 Promise 对象，因此如果要兼容 IE11 浏览器，需要引入相应的 polyfill 或 shim；
  • 更新了内置数据源的 json 数据；
  • level 属性现在从 1 开始，可选值范围变为 1 - 3；
  • 样式的细微调整。

v2.1.0 2020-03-09

新增

  • data 参数支持传入 Promise；
  • 增加 activeColor 参数。

v2.0.0 2020-03-06

新增

  • 增加 cascader 主题；

变更

  • 对程序进行重写，不再依赖 jQuery 和 Vue，完全基于原生 JavaScript 开发。

v1.0.0 2020-01-14

  • 发布 iPicker；