【picker】选择器组件说明

picker从底部弹起选择器组件

组件细节：

1) 该组件有五种类型，分别是普通选择器、多列选择器、时间选择器、日期选择器、省市区选择器。

2) 组件内必需包裹内容，不然无法弹出选项

<!-- 采用wxs提供数据源更直观显示 -->
<wxs module="picker">
  module.exports.items=['美国', '德国', '英国', '法国'];
</wxs>

<!-- 点击灰色的选择器无法弹出，因为其内部没有包裹内容 -->
<picker mode="selector" value="0" style="background:#ccc;width:300px;height:100px;" range="{{picker.items}}">
</picker>

<!-- 点击红色选择器内文字可以弹出 -->
<picker mode="selector" value="0" style="background:#f00;width:300px;height:100px;" range="{{picker.items}}"> <view>点我这一行可以弹出</view> </picker>

3) 五类选择器默认返回值不同（值也可以通过JS脚本进行更改）：

普通选择器：[Number] 当前选项的序号值，第一项序号为0，以次累推

多列选择器：[Array] 元素值是每一列的选择项的序号值

时间选择器：[String] 格式 hh:mm

日期选择器：[String] 格式 YYYY-MM-DD

省市区选择器: [Array] 格式 [ 省名称, 市名称, 区名称 ]

五种类型：

1、 普通选择器: mode="selector"

原型：

<picker
    mode="selector"
    value="[String]"
    range="[Array | Object Array]"
    range-key="[String]"
    disabled="[Boolean]"
    bindchange="[EventHandle]"
    bindcancel="[EventHandle]"
>
</picker>

属性：

名称	是否必需	类型	默认值	说明
mode	是	[String]	selector	固定值为selector表示是普通的选择器
range	是	[Array | Object Array]	[]	初始化选择器选项的数据源 值类型为Array时，数组的每一个元素为选择器的选项列表 值类型为Object Array时，要求指明range-key，做为选项列表值
range	否	[String]		当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
value	否	[String]	空值	选择器默认值。 其值默认为选项的序号值（第一项序号为0，以次类推） 如果想自定义其值，可以通过JS设置此属性值
disabled	否	[Boolean]	false	值为true表示禁用此组件
bindchange	否	[EventHandle]		选择组件选项时触发此事件，不管选择的项是否发生变化都会触发此事件，（即点击组件右侧“确认”按钮时就会触发此事件） 通过JS改变组件值时不触发此事件。 事件参数中返回组件值：event.detail = {value: value}
bindcancel	否	[EventHandle]		点击组件右侧“取消”按钮时就会触发此事件

2、多列选择器：mode="multiSelector"

原型：

<picker
    mode="multiSelector"
    value="[Array]"
    range="[二维Array / 二维Object Array]"
    range-key="[String]"
    disabled="[boolean]"
    bindchange="[EventHandle]"
    bindcancel="[EventHandle]"
    bindcolumnchange="[EventHandle]"
>
</picker>

属性：

名称	是否必需	类型	默认值	说明
mode	是	[String]	multiSelector	固定值为multiSelector表示是多列选择器
range	是	[Array | Object Array]	[]	初始化选择器选项的数据源 mode为 selector 或 multiSelector 时，range 有效。二维数组，长度表示多少列，数组的每项表示每列的数据，如[["a","b"], ["c","d"]]
range	否	[String]		当 range 是一个 二维Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
value	否	[Array]	[]	选择器默认值。 如果想自定义其值，可以通过JS设置此属性值 value 每一项的值表示选择了 range 对应项中的第几个（下标从 0 开始）
disabled	否	[Boolean]	false	值为true表示禁用此组件
bindchange	否	[EventHandle]		选择组件选项时触发此事件，不管选择的项是否发生变化都会触发此事件，（即点击组件右侧“确认”按钮时就会触发此事件） 通过JS改变组件值时不触发此事件。 事件参数中返回组件值：event.detail = {value: value}
bindcolumnchange	否	[EventHandle]		某一列的值改变时触发 columnchange 事件，event.detail = {column: column, value: value}，column 的值表示改变了第几列（下标从0开始），value 的值表示变更值的下标
bindcancel	否	[EventHandle]		点击组件右侧“取消”按钮时就会触发此事件

3、时间选择器：mode="time"

原型：

<picker
    mode="time"
    value="[String]"
    start="[Date]"
    end="[Date]"
    disabled="[Boolean]"
    bindchange="[EventHandle]"
    bindcancel="[EventHandle]"
>
</picker>

属性：

名称	是否必需	类型	默认值	说明
mode	是	[String]	time	固定值为time表示是普通的选择器
start	否	[String]		有效时间范围的开始，字符串格式为"hh:mm"
end	否	[String]		有效时间范围的结束，字符串格式为"hh:mm"
value	否	[String]		表示选中的时间，格式为"hh:mm"
disabled	否	[Boolean]	false	值为true表示禁用此组件
bindchange	否	[EventHandle]		选择组件选项时触发此事件，不管选择的项是否发生变化都会触发此事件，（即点击组件右侧“确认”按钮时就会触发此事件） 通过JS改变组件值时不触发此事件。 事件参数中返回组件值：event.detail = {value: value}
bindcancel	否	[EventHandle]		点击组件右侧“取消”按钮时就会触发此事件

4、日期选择器：mode="date"

原型：

<picker
    mode="date"
    start="[String]"
    end="[String]"
    fields="[day | month | year]"
    value="[String]"
    disabled="[Boolean]"
    bindchange="[EventHandle]"
    bindcancel="[EventHandle]"
>
</picker>

属性：

名称	是否必需	类型	默认值	说明
mode	是	[String]	date	固定值为date表示是普通的选择器
start	否	[String]		有效日期起始范围，格式为"YYYY-MM-DD"
end	否	[String]		有效日期结束范围，格式为"YYYY-MM-DD"
fields	否	[day | month | year]	day	有效值 year,month,day，表示选择器的粒度 值为day时，格式为： YYYY-MM-DD 值为month时，格式为： YYYY-MM 值为year时，格式为： YYYY
value	否	[String]	0	表示选中的日期，格式为"YYYY-MM-DD"
disabled	否	[Boolean]	false	值为true表示禁用此组件
bindchange	否	[EventHandle]		选择组件选项时触发此事件，不管选择的项是否发生变化都会触发此事件，（即点击组件右侧“确认”按钮时就会触发此事件） 通过JS改变组件值时不触发此事件。 事件参数中返回组件值：event.detail = {value: value}
bindcancel	否	[EventHandle]		点击组件右侧“取消”按钮时就会触发此事件

5. 省市区选择器：mode="region" 

原型：

<picker
    mode="region"
    value="[Array]"
    custom-item="[String]"
    disabled="[Boolean]"
    bindchange="[EventHandle]"
    bindcancel="[EventHandle]"
>
</picker>

属性：

名称	是否必需	类型	默认值	说明
mode	是	[String]	regio	固定值为regio表示是普通的选择器
value	否	[Array]	[]	表示选中省市区，格式：[省, 市, 区]
custom-item	否	[String]		可为每一列的顶部添加一个自定义的项（比如全部，或者请选择）
disabled	否	[Boolean]	false	值为true表示禁用此组件
bindchange	否	[EventHandle]		选择组件选项时触发此事件，不管选择的项是否发生变化都会触发此事件，（即点击组件右侧“确认”按钮时就会触发此事件） 通过JS改变组件值时不触发此事件。 事件参数中返回组件值：event.detail = {value: value}
bindcancel	否	[EventHandle]		点击组件右侧“取消”按钮时就会触发此事件

注意：

1） 该选择器显示三列类型选项，分别是省、市、区。

2）该选择器的显示是[省份名称, 市名称, 区名称]。

3）省、市、区数据源由组件自动生成，无需提供。