UIActionSelector

来自于：官方立即使用

open hide show close setActive getActive

论坛示例

为帮助用户更好更快的使用模块，论坛维护了一个示例，示例中包含示例代码、知识点讲解、注意事项等，供您参考。

概述

UIActionSelector 是一个支持弹出动画的多级选择器。调用 open 接口，会从当前 window 底部弹出一个 action 选择器，该选择器在 iOS 平台上是立体滚轮效果的，在 android 平台上二维平面效果的。开发者可自定义该选择器的数据源，利用此模块做出一个城市地区选择器、公司部门选择器，菜单选择器等各种炫酷的选择器。

本模块选择器是分级联动选择器，最多支持三级目录，每级目录直接是相关联包含的。通过 open 接口内的 layout 参数可配置选择器的级数、显示行数、行间距等各种样式信息。getActive、setActive 接口可获取、设置当前选中项。详情参考模块接口参数。

本模块可替代 citySelector 模块来自定义城市选择器。

模块概览图如下：

UIActionSelector - 图1

模块接口

open

打开选择器

open({params}, callback(ret, err))

params

datas：

  • 类型：JSON 数组类型 或 路径类型
  • 描述：为选择器指定数据，可以是 JSON 数组 或是以 JSON 数组格式内容保存的文件的fs://、widget://路径，若为 json 文件则必须是标准的 json格式，否则会报错。
  • 数据格式：
  1. // 使用以下示例，请先删除注释
  2. [ //JSON 数组类型；第一级选择项数组
  3.     {
  4.         "name": "北京市", //字符串类型；第一级选择项的名称
  5.         "sub": [ //JSON 数组类型；第二级选择项数组
  6.             {
  7.                 "name": "东城区" //字符串类型；第二级选择项的名称
  8.             }, {
  9.                 "name": "西城区" //字符串类型；第二级选择项的名称
  10.             }
  11.         ]
  12.     }, {
  13.         "name": "河南省", //字符串类型；第一级选择项的名称
  14.         "sub": [ //JSON 数组类型；第二级选择项数组
  15.             {
  16.                 "name": "郑州市", //字符串类型；第二级选择项的名称
  17.                 "sub": [ //JSON 数组类型；第三级选择项数组
  18.                     {
  19.                         "name": "中原区" //字符串类型；第三级选择项的名称
  20.                     }, {
  21.                         "name": "金水区" //字符串类型；第三级选择项的名称
  22.                     }
  23.                 ]
  24.             }, {
  25.                 "name": "驻马店市", //字符串类型；第二级选择项的名称
  26.                 "sub": [ //JSON 数组类型；第三级选择项数组
  27.                     {
  28.                         "name": "西平县" //字符串类型；第三级选择项的名称
  29.                     }, {
  30.                         "name": "泌阳县" //字符串类型；第三级选择项的名称
  31.                     }
  32.                 ]
  33.             }
  34.         ]
  35.     }
  36. ]

iPhoneXBottomHeight:

  • 类型：数字类型
  • 描述：iPhoneX底部适配(如果需要底部和模块贴合，可以设置此参数为0) 注意:该参数仅适用于iOS
  • 默认： 34

layout：

  • 类型：JSON 类型
  • 描述：选择器的布局设置
  • 内部字段：
  1. {
  2.     row: 5,                            //（可选项）数字类型；每屏显示的数据行数，超出的数据可以滑动查看，只能是奇数；默认：5
  3.     col: 3,                            //（可选项）数字类型；数据源的数据级数，最多3级；默认：3
  4.     height: 30,                        //（可选项）数字类型；每行选项的高度；默认：30
  5.     size: 12,                          //（可选项）数字类型；普通选项的字体大小；默认：12
  6.     sizeActive: 14,                    //（可选项）数字类型；当前选项的字体大小；默认：同 size
  7.     rowSpacing: 5,                     //（可选项）数字类型；行与行之间的距离；默认：5
  8.     colSpacing: 10,                    //（可选项）数字类型；列与列之间的距离；默认：10
  9.     maskBg: 'rgba(0,0,0,0.2)',         //（可选项）字符串类型；遮罩层背景，点击该区域隐藏选择器，支持 rgb，rgba，#，img；默认：rgba(0,0,0,0.2)
  10.     bg: '#fff',                        //（可选项）字符串类型；选择器有效区域背景，支持 rgb，rgba，#，img；默认：#fff
  11.     color: '#888',                     //（可选项）字符串类型；选项的文字颜色，支持 rgb，rgba，#；默认：#848484
  12.     colorSelected: '#f00'              //（可选项）字符串类型；已选项的文字颜色，支持 rgb，rgba，#；默认：同 colorActive
  13.     leftMargin: 10,                    //（可选项）数字类型；选择器分割线的左边距；默认：0
  14.     rightMargin: 10,                   //（可选项）数字类型；选择器分割线的右边距；默认：0
  15.     isWidth:false,                      //（可选项）布尔类型；是否自定义宽度；默认：false (等分排列)
  16.     leftWidth:0.2,                     //（可选项）左边选择器屏幕占比；默认：0.3
  17.     middleWidth:0.3,                   //（可选项）中间选择器屏幕占比；默认：0.3
  18.     rightWidth:0.4,                    //（可选项）右边选择器屏幕占比；默认：0.3
  19. }

bgCorner:

  • 类型：数字类型
  • 描述：模块顶部圆角
  • 默认：5

animation：

  • 类型：布尔类型
  • 描述：弹出和隐藏选择器时是否带弹出动画效果
  • 默认：true

cancel：

  • 类型：JSON 类型
  • 描述：取消按钮设置，取消按钮显示在选择器左上角
  • 内部字段：
  1. {                                      //（可选项）JSON 对象类型；取消按钮设置
  2.     text: '取消',                      //（可选项）字符串类型；取消按钮的显示文字；默认：未设置时只显示背景
  3.     size: 12,                          //（可选项）数字类型；取消按钮的显示文字大小；默认：12
  4.     w: 90,                             //（可选项）数字类型；取消按钮的宽；默认：90
  5.     h: 35,                             //（可选项）数字类型；取消按钮的高；默认：35
  6.     bg: '#fff',                        //（可选项）字符串类型；取消按钮的背景，支持 rgb，rgba，#，img；默认：'#fff'
  7.     bgActive: '#ccc',                  //（可选项）字符串类型；取消按钮的背景高亮，支持 rgb，rgba，#，img；默认：同 bg
  8.     color: '#888',                     //（可选项）字符串类型；取消按钮的文字颜色，支持 rgb，rgba，#；默认：'#848484'
  9.     colorActive: '#fff'                //（可选项）字符串类型；取消按钮的文字颜色高亮，支持 rgb，rgba，#；默认：同 color
  10.     leftMargin:10                      //（可选项）数字类型；取消按钮的左边距；默认：10
  11. }

ok：

  • 类型：JSON 类型
  • 描述：确定按钮设置，确定按钮显示在选择器右上角
  • 内部字段：
  1. {                                      //（可选项）JSON 对象类型；确定按钮设置
  2.     text: '确定',                      //（可选项）字符串类型；确定按钮的显示文字；默认：未设置时只显示背景
  3.     size: 12,                          //（可选项）数字类型；确定按钮的显示文字大小；默认：12
  4.     w: 90,                             //（可选项）数字类型；确定按钮的宽；默认：90
  5.     h: 35,                             //（可选项）数字类型；确定按钮的高；默认：35
  6.     bg: '#fff',                        //（可选项）字符串类型；确定按钮的背景，支持 rgb，rgba，#，img；默认：'#fff'
  7.     bgActive: '#ccc',                  //（可选项）字符串类型；确定按钮的背景高亮，支持 rgb，rgba，#，img；默认：同 bg
  8.     color: '#888',                     //（可选项）字符串类型；确定按钮的文字颜色，支持 rgb，rgba，#；默认：'#848484'
  9.     colorActive: '#fff',               //（可选项）字符串类型；确定按钮的文字颜色高亮，支持 rgb，rgba，#；默认：同 color
  10.     rightMargin:10                     //（可选项）数字类型；确定按钮的右边距；默认：10
  11. }

title：

  • 类型：JSON 类型
  • 描述：选择器顶部标题栏设置
  • 内部字段：
  1. {                                      //（可选项）JSON 对象类型；选择器顶部标题栏设置
  2.     text: '请选择',                    //（可选项）字符串类型；选择器的标题内容；默认：请选择
  3.     size: 12,                          //（可选项）数字类型；标题内容的文字大小；默认：12
  4.     h: 44,                             //（可选项）数字类型；标题栏的高；默认：44
  5.     bg: '#eee',                        //（可选项）字符串类型；标题栏的背景，支持 rgb，rgba，#，img；默认：'#eee'
  6.     color: '#888'                      //（可选项）字符串类型；标题内容的文字颜色，支持 rgb，rgba，#；默认：'#848484'
  7.     alignment:'center'                 // (可选项)字符串类型；标题内容的文字的对齐方式，默认：'center'
  8. }

lineColor：

  • 类型：字符串
  • 描述：选择器顶部标题栏与选择器内容之间的分割线颜色，支持 rgb，rgba，#；
  • 默认：rgba(0,0,0,0)

lineHeight：

  • 类型：数字
  • 描述：选择器顶部标题栏与选择器内容之间的分割线粗细；
  • 默认：1

selectorDividerColor：

  • 类型：字符串
  • 描述：选择器内容之间的分割线颜色，支持 rgb，rgba，#；
  • 默认：’#e2e2e2’

selectedBold:

  • 类型：布尔类型
  • 描述：选中时是否加粗（仅支持Android）
  • 默认：true

actives：

  • 类型：数组
  • 描述：打开模块时默认选项下标组成的数组，如：[0,0,0]
  • 默认：各级选项的首项的索引组成的数组

isSortOrder:

  • 类型：布尔类型
  • 描述：正序显示还是倒序显示
  • 默认：true；正序显示

fixedOn：

  • 类型：字符串类型
  • 描述：（可选项）模块视图添加到指定 frame 的名字（只指 frame，传 window 无效）
  • 默认：模块依附于当前 window

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     eventType: 'ok',                  //字符串类型；交互事件类型，取值范围如下：
  3.                                       //ok（表示用户点击了确定按钮）
  4.                                       //cancel（表示用户取消了选择器显示，包括点击取消按钮和遮罩层）
  5.                                           //onChange 选项改变时触发
  6.     level1: '河南省',                  //字符串类型；第一级选项的内容；只在 eventType 是 ok 时有效
  7.     level2: '驻马店市',                //字符串类型；第二级选项的内容；只在 eventType 是 ok 时有效
  8.     level3: '泌阳县',                  //字符串类型；第三级选项的内容；只在 eventType 是 ok 时有效
  9.     selectedInfo: [                   //JSON对象；选中项的详细信息（open时传入的信息）
  10.         {
  11.             name:'河南省',  
  12.             id:'',                     // 字符串类型；第一级选项的内容；该字段为用户定义字段
  13.             title:'',                  // 字符串类型；第一级选项的内容；该字段为用户定义字段
  14.             ...
  15.         },
  16.         {
  17.             name:'驻马店市',
  18.             id:'',
  19.             title:'',
  20.             ...
  21.         },
  22.         {
  23.             name:'泌阳县',
  24.             id:'',
  25.             title:'',
  26.             ...
  27.         }
  28.     ]                
  29. }

示例代码

  1. var UIActionSelector = api.require('UIActionSelector');
  2. UIActionSelector.open({
  3.     datas: 'widget://res/city.json',
  4.     layout: {
  5.         row: 5,
  6.         col: 3,
  7.         height: 30,
  8.         size: 12,
  9.         sizeActive: 14,
  10.         rowSpacing: 5,
  11.         colSpacing: 10,
  12.         maskBg: 'rgba(0,0,0,0.2)',
  13.         bg: '#fff',
  14.         color: '#888',
  15.         colorActive: '#f00',
  16.         colorSelected: '#f00'
  17.     },
  18.     animation: true,
  19.     cancel: {
  20.         text: '取消',
  21.         size: 12,
  22.         w: 90,
  23.         h: 35,
  24.         bg: '#fff',
  25.         bgActive: '#ccc',
  26.         color: '#888',
  27.         colorActive: '#fff'
  28.     },
  29.     ok: {
  30.         text: '确定',
  31.         size: 12,
  32.         w: 90,
  33.         h: 35,
  34.         bg: '#fff',
  35.         bgActive: '#ccc',
  36.         color: '#888',
  37.         colorActive: '#fff'
  38.     },
  39.     title: {
  40.         text: '请选择',
  41.         size: 12,
  42.         h: 44,
  43.         bg: '#eee',
  44.         color: '#888'
  45.     },
  46.     fixedOn: api.frameName
  47. }, function(ret, err) {
  48.     if (ret) {
  49.         alert(JSON.stringify(ret));
  50.     } else {
  51.         alert(JSON.stringify(err));
  52.     }
  53. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

hide

隐藏选择器

hide()

示例代码

  1. var UIActionSelector = api.require('UIActionSelector');
  2. UIActionSelector.hide();

补充说明

隐藏选择器，只是移除到屏幕之外，还在内存里没有清除

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

show

显示选择器

show()

示例代码

  1. var UIActionSelector = api.require('UIActionSelector');
  2. UIActionSelector.show();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

close

关闭选择器

close()

示例代码

  1. var UIActionSelector = api.require('UIActionSelector');
  2. UIActionSelector.close();

补充说明

关闭选择器，意味着从内存里清除

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setActive

设置当前选中项

setActive({params})

params

actives：

  • 类型：数组
  • 描述：打开模块时默认选项下标组成的数组，如：[0,0,0]
  • 默认：各级选项的首项的索引组成的数组

示例代码

  1. var UIActionSelector = api.require('UIActionSelector');
  2. UIActionSelector.setActive({
  3.     actives: [1, 0, 0]
  4. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getActive

获取当前选中项

getActive(callback(ret, err))

callback

ret:

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.         level1: '河南省',                  //字符串类型；第一级选项的内容
  3.         level2: '驻马店市',                //字符串类型；第二级选项的内容
  4.         level3: '泌阳县'                   //字符串类型；第三级选项的内容
  5. }

示例代码

  1. var UIActionSelector = api.require('UIActionSelector');
  2. UIActionSelector.getActive(function(ret, err) {
  3.     if (ret) {
  4.         alert(JSON.stringify(ret));
  5.     } else {
  6.         alert(JSON.stringify(err));
  7.     }
  8. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

论坛示例

为帮助用户更好更快的使用模块，论坛维护了一个示例，示例中包含示例代码、知识点讲解、注意事项等，供您参考。