UICityList

来自于：官方立即使用

open close show hide

论坛示例

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

概述

UICityList 模块是一个可定制数据源的城市列表；模块根据数据源自动生成字母索引，点击字母索引快速滚动至目标数据，支持数据源搜索；用于实现城市列表的展示，搜索，及导航功能。UICityList 模块是 cityList 模块的优化版。

UICityList - 图1

实例widget下载地址

open

打开城市列表模块

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

params

rect：

  • 类型：JSON 对象
  • 描述：（可选项）模块的位置及尺寸
  • 内部字段：
  1. {
  2.     x: 0,   //（可选项）数字类型；模块左上角的 x 坐标（相对于所属的 Window 或 Frame）；默认：0
  3.     y: 0,   //（可选项）数字类型；模块左上角的 y 坐标（相对于所属的 Window 或 Frame）；默认：0
  4.     w: 320, //（可选项）数字类型；模块的宽度；默认：'auto'
  5.     h: 480  //（可选项）数字类型；模块的高度；默认：'auto'
  6. }

topCitys：

  • 类型：数组
  • 描述：（可选项）热门城市数据源，若本参数不为空，则忽略 resource中的 topCitys。若不传或传空，则模块会自动读取 resource 中的 topCitys 数据
  • 内部字段：
  1. [{               
  2.         "city": "北京",
  3.         "id": 110001,
  4.         icon: '',           //（可选项）字符串类型；按钮图标路径，要求本地路径（fs://、widget://）
  5.         "pinyin":"beijing"  //（可选项）字符串类型；本字段可不传，若不传模块内会生成该城市名的pinyin，以防止城市名中的多音字乱序问题
  6. },{},{},.....]

resource：

  • 类型：字符串
  • 描述：城市列表的数据源文件路径（支持 https、http、widget、fs 路径协议），数据源文件必须为.json文件。城市的JSON数据会在callback时按原格式返回。若为 json 文件则必须是标准的 json格式，否则会报错。
  • .json文件内部字段：
  1. {
  2.     "topCitys": [{          //（可选项）数组类型；热门城市，若不传则不显示热门城市            
  3.         "city": "北京",
  4.         "id": 110001,
  5.         icon: '',           //（可选项）字符串类型；按钮图标路径，要求本地路径（fs://、widget://）
  6.         "pinyin":"beijing"  //（可选项）字符串类型；本字段可不传，若不传模块内会生成该城市名的pinyin，以防止城市名中的多音字乱序问题
  7.     },{
  8.         "city": "天津",
  9.         "id": 120001
  10.     }],
  11.     "citys": [{             //数组类型，数组元素是JSON对象；城市数据；至少包含 id、city 二个字段，其余可自定义添加
  12.         "id": 110001,
  13.         "city": "北京"
  14.     },{
  15.         "id": 120001,
  16.         "city": "天津"
  17.     }]
  18. }

styles：

  • 类型：JSON 对象
  • 描述：（可选项）城市列表样式设置
  • 内部字段：
  1. {   
  2.     searchBar: {                    //（可选项）JSON对象；顶部搜索条的样式
  3.         height: 40,                 //（可选项）数字类型；搜索框区域高度；默认：40
  4.         bgColor: '#696969',         //（可选项）字符串类型；搜索条背景色，支持 rgb、rgba、#；默认：'#696969'
  5.         cancelColor: '#E3E3E3' ,     //（可选项）字符串类型；取消文字颜色，支持 rgb、rgba、#，默认：'#E3E3E3'
  6.         contentBgColor: '#ffffff'    //（可选项）字符串类型；搜索框输入区域背景色
  7.         cancelText: '取消',          //(可选项) 字符串类型；取消按钮的文本；默认：'取消'；此参数只在android平台有效
  8.         cancelSize: 15,          //(可选项) 数字类型；取消按钮的文本大小；默认：15；此参数只在android平台有效
  9.         placeholderColor:,          //（可选项）字符串类型；占位提示符颜色，注意此参数在iOS 13（包含iOS 13）以上系统不再支持；默认:#D3D3D3
  10.         placeholderSize:,           //（可选项）数字类型；占位提示符字体大小；默认：16
  11.         corner:4,                   //（可选项）数字类型；输入框圆角大小；默认：8
  12.         searchIconLeft:4,           //（可选项）数字类型；输入框内图标左间距；默认：0
  13.         searchIconTop:4,            //（可选项）数字类型；输入框内图标上间距；默认：0
  14.         hidden: false,               //（可选项）布尔类型：是否隐藏搜索框；默认：false
  15.         searchTextColor:'',     //（可选项）字符串类型；搜索文字颜色；默认：‘#000000’
  16.     },
  17.     location: {                     //（可选项）JSON对象；定位提示文字样式
  18.         color: '#696969',           //（可选项）字符串类型；定位提示文字颜色，支持 rgb、rgba、#，默认：'#696969'
  19.         size: 12                    //（可选项）数字类型；定位提示文字大小，默认：12.0
  20.     },
  21.     hotCity: {                      //（可选项）JSON对象；热门城市矩阵分布样式配置，若不传则表示热门城市呈列表显示
  22.         column: 5,                  //（可选项）数字类型；每行显示列数；默认：5
  23.         width: 48,                  //（可选项）数字类型；按钮的宽；默认：48
  24.         height: 30,                 //（可选项）数字类型；按钮的高；默认：30
  25.         interval: 20,               //（可选项）数字类型；按钮排列行间距；默认：20
  26.         corner: 15,                 //（可选项）数字类型；按钮圆角大小；默认：15
  27.         titleSize:,                 //（可选项）数字类型；按钮字体大小；默认：15
  28.         iconSize:,                  //（可选项）数字类型；按钮图片大小；默认：18
  29.         color: '#000',              //（可选项）字符串类型；标题常态时的颜色，支持rgb、rgba、#；默认：#000
  30.         borderColor: '#000',        //（可选项）字符串类型；按钮边框的颜色，支持rgb、rgba、#；默认：#000
  31.         bgColor: '#000',            //（可选项）字符串类型；按钮背景的颜色，支持rgb、rgba、#；默认：#fff
  32.         background: '#000',         //（可选项）字符串类型；热门区域的背景色，支持rgb、rgba、#；默认：#fff
  33.         titleBgColor: '#000',       //（可选项）字符串类型；热门区域标题的背景色，支持rgb、rgba、#；默认：#EEEEEE
  34.         active: '#f00'              //（可选项）字符串类型；按钮点击高亮状态色值，支持rgb、rgba、#；默认：#f00
  35.     },
  36.     sectionTitle: {                 //（可选项）JSON对象；标题的样式
  37.         bgColor: '#eee',            //（可选项）字符串类型；标题的背景色，支持 rgb、rgba、#；默认：'#EEEEEE'
  38.         color: '#000',              //（可选项）字符串类型；标题文字颜色，支持 rgb、rgba、#；默认：'#000000'
  39.         size: 12,                   //（可选项）数字类型；标题文字大小；默认：12.0
  40.         height: 25                  //（可选项）数字类型；区域标题的高度，默认：25.0
  41.     },
  42.     item: {                         //（可选项）JSON对象；列表项的样式
  43.         bgColor: '#fff',            //（可选项）字符串类型；列表项的背景色，支持 rgb、rgba、#；默认：'#FFFFFF'
  44.         activeBgColor: '#696969',   //（可选项）字符串类型；列表项按下时的背景色，支持 rgb、rgba、#；默认：'#696969'
  45.         color: '#000',              //（可选项）字符串类型；列表项的文字颜色，支持 rgb、rgba、#，默认：'#000000'
  46.         boardColor: '#000',         //（可选项）字符串类型；列表项的分割线颜色，支持 rgb、rgba、#，默认：'#c3c3c3'
  47.         size: 14,                   //（可选项）数字类型；列表项的文字大小，默认：14.0
  48.         height: 40                  //（可选项）数字类型；列表项的高度，默认：40.0
  49.     },
  50.     indicator: {                    //（可选项）JSON对象；右侧字母导航条样式
  51.         bgColor: '#fff',            //（可选项）字符串类型；字母导航条背景色，支持 rgb、rgba、#，默认：'#FFFFFF'
  52.         color: '#696969'            //（可选项）字符串类型；字母导航条字母颜色，支持 rgb、rgba、#，默认：'#696969'
  53.     },
  54.     searchEmptyView: {             //JSON对象；搜索结果为空时显示效果配置
  55.     background:'',       //字符串类型；结果为空时背景颜色；默认值：‘#ffffff’
  56.        image: {              //JSON对象；图片配置
  57.           path:,             //字符串类型；图片路径，要求本地路径（fs://、widget://）；不传则不显示
  58.           w:,                //数字类型；图片宽；默认：100
  59.           h:,                //数字类型；图片高；默认：80
  60.           marginB:           //数字类型；图片下边距离模块下边距离；默认：自适应上下居中显示
  61.        },
  62.        title: {              //JSON对象；提示文字配置
  63.           content:,          //字符串类型；提示文字内容；不传则不显示
  64.           size:,             //数字类型；提示文字大小；默认：14
  65.           color:,            //字符串类型；提示文字颜色；默认：#00BFFF
  66.           interval:         //数字类型；与图片的间距；默认：15
  67.        }
  68.     }
  69. }

searchType：

  • 类型：字符串
  • 描述：（可选项）搜索类型
  • 默认：fuzzy
  • 取值范围：
    • fuzzy：模糊搜索
    • initial：首字母（首汉字、首词组、首单词）搜索

currentCity：

  • 类型：字符串
  • 描述：（可选项）显示当前所在城市，若传空或不传则当前城市行不显示（ currentCity 和 locationWay 均不显示）

  • 注意：

    1. 当本字段传入的值能与 resource 传入的数据源中的某个 city 值对应时，
    2. 用户点击当前城市,
    3.  open 接口会返回该 city 所在的数据包信息。
    4.  反之，则仅返回当前城市的名字，如：
    5. cityInfo: {          
    6.       'name': '北京'
    7.   }

locationWay：

  • 类型：字符串
  • 描述：（可选项）显示定位方式（紧跟在当前城市后面）
  • 默认值：’GPS定位’

hotTitle：

  • 类型：字符串
  • 描述：（可选项）热门城市对应的标题
  • 默认值：’热门城市’

placeholder：

  • 类型：字符串
  • 描述：（可选项）顶部搜索条占位提示文字
  • 默认值：’输入城市名或首字母查询’

backBtn：

  • 类型：JSON 对象
  • 描述：（可选项）模块左上角按钮配置
  • 内部字段：
  1. {
  2.     rect: {
  3.         x: 0,      //（可选项）数字类型；按钮左上角的 x 坐标（相对于模块）；默认：2
  4.         y: 0,      //（可选项）数字类型；按钮左上角的 y 坐标（相对于模块）；默认：2
  5.         w: 320,    //（可选项）数字类型；按钮的宽度；默认：36
  6.         h: 480     //（可选项）数字类型；按钮的高度；默认：36
  7.     },
  8.     title: '',    //（可选项）字符串类型；按钮标题；默认：不显示
  9.     titleColor:'',//（可选项）字符串类型；按钮标题颜色；默认：#ff0000
  10.     bgColor:'',   //（可选项）字符串类型；按钮背景颜色；默认：透明
  11.     image:''      //（可选项）字符串类型；按钮背景图片；默认：不显示
  12. }

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     eventType: 'show',      //字符串类型；交互事件类型
  3.                             //取值范围：
  4.                             //show（模块打开成功）
  5.                             //selected（用户选择城市）
  6.                             //back（左上角按钮点击事件）
  7.     cityInfo: {             //JSON对象；用户选择的城市信息，同传入的数据源格式相同
  8.         'id': 110001,
  9.         'city': '北京',
  10.         'pinyin':'beijing'
  11.     }            
  12. }

示例代码

  1. var UICityList = api.require('UICityList');
  2. UICityList.open({
  3.     rect: {
  4.         x: 0,
  5.         y: 0,
  6.         w: api.frameWidth,
  7.         h: api.frameHeight
  8.     },
  9.     resource: 'widget://res/cityList.json',
  10.     styles: {
  11.         searchBar: {
  12.             bgColor: '#696969',
  13.             cancelColor: '#E3E3E3'
  14.         },
  15.         location: {
  16.             color: '#696969',
  17.             size: 12
  18.         },
  19.         sectionTitle: {
  20.             bgColor: '#eee',
  21.             color: '#000',
  22.             size: 12
  23.         },
  24.         item: {
  25.             bgColor: '#fff',
  26.             activeBgColor: '#696969',
  27.             color: '#000',
  28.             size: 14,
  29.             height: 40
  30.         },
  31.         indicator: {
  32.             bgColor: '#fff',
  33.             color: '#696969'
  34.         }
  35.     },
  36.     currentCity: '北京',
  37.     locationWay: 'GPS',
  38.     hotTitle: '热门城市',
  39.     fixedOn: api.frameName,
  40.     placeholder: '输入城市名或首字母查询'
  41. }, function(ret, err) {
  42.     if (ret) {
  43.         alert(JSON.stringify(ret));
  44.     } else {
  45.         alert(JSON.stringify(err));
  46.     }
  47. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

close

关闭城市列表

close()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

show

显示城市列表

show()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

hide

隐藏城市列表

hide()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

论坛示例

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