UICityList

来自于:官方立即使用

概述

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

实例widget下载地址

open

打开城市列表模块

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

params

rect:

  • 类型:JSON 对象
  • 描述:(可选项)模块的位置及尺寸
  • 内部字段:
{
    x: 0,   //(可选项)数字类型;模块左上角的 x 坐标(相对于所属的 Window 或 Frame);默认:0
    y: 0,   //(可选项)数字类型;模块左上角的 y 坐标(相对于所属的 Window 或 Frame);默认:0
    w: 320, //(可选项)数字类型;模块的宽度;默认:'auto'
    h: 480  //(可选项)数字类型;模块的高度;默认:'auto'
}

topCitys:

  • 类型:数组
  • 描述:(可选项)热门城市数据源,若本参数不为空,则忽略 resource中的 topCitys。若不传或传空,则模块会自动读取 resource 中的 topCitys 数据
  • 内部字段:
[{               
        'city': '北京',      //字符串类型;城市
        'id': 110001,       //字符串类型;城市编号
        'pinyin':'beijing'  //(可选项)字符串类型;本字段可不传,若不传模块内会生成该城市名的pinyin,以防止城市名中的多音字乱序问题
},{},{},.....]

resource:

  • 类型:字符串
  • 描述:城市列表的数据源文件路径(支持 https、http、widget、fs 路径协议),数据源文件必须为.json文件。城市的JSON数据会在callback时按原格式返回。若为 json 文件则必须是标准的 json格式,否则会报错。
  • .json文件内部字段:
{
    'topCitys': [{          //(可选项)数组类型;热门城市,若不传则不显示热门城市            
        'city': '北京',
        'id': 110001,
        'pinyin':'beijing'  //(可选项)字符串类型;本字段可不传,若不传模块内会生成该城市名的pinyin,以防止城市名中的多音字乱序问题
    },{
        'city': '天津',
        'id': 120001
    }],
    'citys': [{             //数组类型,数组元素是JSON对象;城市数据;至少包含 id、city 二个字段,其余可自定义添加
        'id': 110001,
        'city': '北京'
    },{
        'id': 120001,
        'city': '天津'
    }]
}

styles:

  • 类型:JSON 对象
  • 描述:(可选项)城市列表样式设置
  • 内部字段:
{   
    searchBar: {                    //(可选项)JSON对象;顶部搜索条的样式
        bgColor: '#696969',         //(可选项)字符串类型;搜索条背景色,支持 rgb、rgba、#;默认:'#696969'
        cancelColor: '#E3E3E3' ,     //(可选项)字符串类型;取消文字颜色,支持 rgb、rgba、#,默认:'#E3E3E3';
        cancelText: '取消'           //(可选项) 字符串类型;取消按钮的文本;默认:'取消';此参数只在android平台有效
    },
    location: {                     //(可选项)JSON对象;定位提示文字样式
        color: '#696969',           //(可选项)字符串类型;定位提示文字颜色,支持 rgb、rgba、#,默认:'#696969'
        size: 12                    //(可选项)数字类型;定位提示文字大小,默认:12.0
    },
    hotCity: {                      //(可选项)JSON对象;热门城市矩阵分布样式配置,若不传则表示热门城市呈列表显示
        column: 5,                  //(可选项)数字类型;每行显示列数;默认:5
        width: 48,                  //(可选项)数字类型;按钮的宽;默认:48
        height: 30,                 //(可选项)数字类型;按钮的高;默认:30
        interval: 20,               //(可选项)数字类型;按钮排列行间距;默认:20
        corner: 15,                 //(可选项)数字类型;按钮圆角大小;默认:15
        color: '#000',              //(可选项)字符串类型;按钮边框和标题常态时的颜色,支持rgb、rgba、#;默认:#000
        active: '#f00'              //(可选项)字符串类型;按钮点击高亮状态色值,支持rgb、rgba、#;默认:#f00
    },
    sectionTitle: {                 //(可选项)JSON对象;标题的样式
        bgColor: '#eee',            //(可选项)字符串类型;标题的背景色,支持 rgb、rgba、#;默认:'#EEEEEE'
        color: '#000',              //(可选项)字符串类型;标题文字颜色,支持 rgb、rgba、#;默认:'#000000'
        size: 12,                   //(可选项)数字类型;标题文字大小;默认:12.0
        height: 25                  //(可选项)数字类型;区域标题的高度,默认:25.0
    },
    item: {                         //(可选项)JSON对象;列表项的样式
        bgColor: '#fff',            //(可选项)字符串类型;列表项的背景色,支持 rgb、rgba、#;默认:'#FFFFFF'
        activeBgColor: '#696969',   //(可选项)字符串类型;列表项按下时的背景色,支持 rgb、rgba、#;默认:'#696969'
        color: '#000',              //(可选项)字符串类型;列表项的文字颜色,支持 rgb、rgba、#,默认:'#000000'
        size: 14,                   //(可选项)数字类型;列表项的文字大小,默认:14.0
        height: 40                  //(可选项)数字类型;列表项的高度,默认:40.0
    },
    indicator: {                    //(可选项)JSON对象;右侧字母导航条样式
        bgColor: '#fff',            //(可选项)字符串类型;字母导航条背景色,支持 rgb、rgba、#,默认:'#FFFFFF'
        color: '#696969'            //(可选项)字符串类型;字母导航条字母颜色,支持 rgb、rgba、#,默认:'#696969'
    }
}

searchType:

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

currentCity:

  • 类型:字符串
  • 描述:(可选项)显示当前所在城市,若传空或不传则当前城市行不显示( currentCity 和 locationWay 均不显示)
  • 注意:

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

locationWay:

  • 类型:字符串
  • 描述:(可选项)显示定位方式(紧跟在当前城市后面)
  • 默认值:'GPS定位'

hotTitle:

  • 类型:字符串
  • 描述:(可选项)热门城市对应的标题
  • 默认值:'热门城市'

placeholder:

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

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    eventType: 'show',      //字符串类型;交互事件类型
                            //取值范围:
                            //show(模块打开成功)
                            //selected(用户选择城市)
    cityInfo: {             //JSON对象;用户选择的城市信息,同传入的数据源格式相同
        'id': 110001,
        'city': '北京',
        'pinyin':'beijing'
    }            
}

示例代码

var UICityList = api.require('UICityList');
UICityList.open({
    rect: {
        x: 0,
        y: 0,
        w: api.frameWidth,
        h: api.frameHeight
    },
    resource: 'widget://res/cityList.json',
    styles: {
        searchBar: {
            bgColor: '#696969',
            cancelColor: '#E3E3E3'
        },
        location: {
            color: '#696969',
            size: 12
        },
        sectionTitle: {
            bgColor: '#eee',
            color: '#000',
            size: 12
        },
        item: {
            bgColor: '#fff',
            activeBgColor: '#696969',
            color: '#000',
            size: 14,
            height: 40
        },
        indicator: {
            bgColor: '#fff',
            color: '#696969'
        }
    },
    currentCity: '北京',
    locationWay: 'GPS',
    hotTitle: '热门城市',
    fixedOn: api.frameName,
    placeholder: '输入城市名或首字母查询'
}, function(ret, err) {
    if (ret) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

close

关闭城市列表

close()

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

show

显示城市列表

show()

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

hide

隐藏城市列表

hide()

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本