iPicker v4.0.0

Select 主题

基本用法

线形箭头

自定义层级

禁用指定层级的展示框

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

默认值

严格模式

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

自定义圆角值

限制列表高度

清空按钮

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

禁用指定地区

Cascader 主题

基本用法

线形箭头

自定义层级

禁用指定层级的展示框

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

默认值

严格模式

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

自定义圆角值

限制列表高度

清空按钮

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

禁用指定地区

分隔符

cascader 和 panel 独有功能。

只展示最后一级结果

cascader 和 panel 独有功能。

Panel 主题

基本用法

线形箭头

自定义层级

禁用指定层级的展示框

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

默认值

严格模式

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

自定义圆角值

限制列表高度

清空按钮

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

禁用指定地区

分隔符

cascader 和 panel 独有功能。

只展示最后一级结果

cascader 和 panel 独有功能。

安装使用

本地引入

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

组件方法

# 创建组件

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.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;