diff --git a/document/common/config/menu.json b/document/common/config/menu.json index 797f745c03de7fbf9fa495156eacd28449f5e727..9786adc0658ff899d180615c611244131fd907d3 100644 --- a/document/common/config/menu.json +++ b/document/common/config/menu.json @@ -29,6 +29,7 @@ "popup": "Popup", "toast": "Toast", "picker": "Picker", + "cascade-picker": "CascadePicker", "time-picker": "TimePicker", "dialog": "Dialog", "action-sheet": "ActionSheet" @@ -83,6 +84,7 @@ "popup": "Popup", "toast": "Toast", "picker": "Picker", + "cascade-picker": "CascadePicker", "time-picker": "TimePicker", "dialog": "Dialog", "action-sheet": "ActionSheet" diff --git a/document/components/docs/en-US/cascade-picker.md b/document/components/docs/en-US/cascade-picker.md new file mode 100644 index 0000000000000000000000000000000000000000..50703d054f49fd257da1a7a04f708894aaa9b522 --- /dev/null +++ b/document/components/docs/en-US/cascade-picker.md @@ -0,0 +1,3 @@ +## CascadePicker + +Please waiting... \ No newline at end of file diff --git a/document/components/docs/zh-CN/cascade-picker.md b/document/components/docs/zh-CN/cascade-picker.md new file mode 100644 index 0000000000000000000000000000000000000000..d28cbfc5d2e1a07677e95564e5f022fd1ed9e2da --- /dev/null +++ b/document/components/docs/zh-CN/cascade-picker.md @@ -0,0 +1,207 @@ +## CascadePicker组件 + +`CascadePicker`组件是级联选择器,用于实现多列选择之间的级联变化。比如,在选择省市区时,当省切换到了江苏省,城市列应该变成江苏省的各个城市,同理,如果城市切换到苏州市,区列的选项也应变成苏州市的各个区,这就级联的意义。 + +### 示例 + +- 基本用法 + + 相比普通选择器,级联选择器需要传入的数据结构是不一样的。普通选择器的数据结构是一个二维数组,每一列对应一个固定的数组,而级联选择器,则需要传入的是一个树形结构,第一列的数组,的每个选项的children属性,对应着切换到该选项时后续列的数据,从而实现对后续列的改变。如下所示 + + ```html + Cascade Picker + ``` + ```js + const cascadeData = [ + { + value: 'Fruit', + text: 'Fruit', + children: [ + { + value: 'Apple', + text: 'Apple', + children: [{ value: 1, text: 'One' }, { value: 2, text: 'Two' }] + }, + { + value: 'Orange', + text: 'Orange', + children: [{ value: 3, text: 'Three'}, { value: 4, text: 'Four' }] + } + ] + }, + { + value: 'Drink', + text: 'Drink', + children: [ + { + value: 'Coffee', + text: 'Coffee', + children: [{ value: 1, text: 'One' }, { value: 2, text: 'Two' }] + }, + { + value: 'Tea', + text: 'Tea', + children: [{ value: 1, text: 'One' }, { value: 3, text: 'Three'}] + } + ] + } + ] + export default { + mounted () { + this.cascadePicker = this.$createCascadePicker({ + title: 'Cascade Picker', + data: cascadeData, + selectedIndex: [1, 0, 0], + onSelect: (selectedVal, selectedIndex, selectedText) => { + console.log('select', selectedVal, selectedIndex, selectedText) + }, + onCancel: () => { + console.log('cancel') + } + }) + }, + methods: { + showCascadePicker() { + this.cascadePicker.show() + } + } + } + ``` + 当第一列选中`Fruit`时,第二列的选项是`Apple`、`Orange`。以此类推,当第二列选中`Orange`时,第三列的选项是`Three`、`Four`。 + +- 省市区选择器 + + 对于省市区选择器,只需要构造出级联选择器的数据结构传入就可以了。 + + ```html + City Picker + ``` + ```js + import { provinceList, cityList, areaList } from 'example/data/area' + + const cityData = provinceList + cityData.forEach(province => { + province.children = cityList[province.value] + province.children.forEach(city => { + city.children = areaList[city.value] + }) + }) + + export default { + mounted () { + this.cityPicker = this.$createCascadePicker({ + title: 'City Picker', + data: cityData, + onSelect: (selectedVal, selectedIndex, selectedText) => { + console.log('select', selectedVal, selectedIndex, selectedText) + }, + onCancel: () => { + console.log('cancel') + } + }) + }, + methods: { + showCityPicker() { + this.cityPicker.show() + } + } + } + ``` + +- 日期选择器 + + 日期选择器的原理也是一样,就是构造出级联选择器的数据结构。而且我们还在示例中提供一个[日期选择器组件](https://github.com/didi/cube-ui/blob/dev/example/components/date-picker.vue),可以传入起始日期和结束日期,帮你生成相应的级联树形数据结构。用法如下: + + ```html + Date Picker + ``` + ```js + import DatePicker from 'example/components/date-picker.vue' + + createAPI(Vue, DatePicker, ['select', 'cancel'], false) + + export default { + mounted () { + this.datePicker = this.$createDatePicker({ + min: [2008, 8, 8], + max: [2020, 10, 20], + onSelect: (selectedVal, selectedIndex, selectedText) => { + console.log('select', selectedVal, selectedIndex, selectedText) + }, + onCancel: () => { + console.log('cancel') + } + }) + }, + methods: { + showDatePicker() { + this.datePicker.show() + } + } + } + ``` + +- 实例方法 `setData` + + `setData`方法,用于重置`CascadePicker`实例的数据和选中的索引。 + + ```html + SetData Picker + ``` + ```js + export default { + mounted () { + this.setDataPicker = this.$createCascadePicker({ + title: 'Set Data', + onSelect: (selectedVal, selectedIndex, selectedText) => { + console.log('select', selectedVal, selectedIndex, selectedText) + }, + onCancel: () => { + console.log('cancel') + } + }) + }, + methods: { + showSetDataPicker() { + // setData when picker is invisible + this.setDataPicker.setData(cascadeData) + this.setDataPicker.show() + setTimeout(() => { + // setData when picker is visible + this.setDataPicker.setData(cityData, [1, 1, 0]) + }, 1000) + } + } + } + ``` + + 值得注意的一点是,虽然不管选择器显示前后,都可以`setData`,但是为了体验,在显示后`setData`,所传入的数据结构,必须与之前的列数相同,也就是说如果之前是三列选择器,显示时`setData`还得是三列。 + +### Props 配置 + +| 参数 | 说明 | 类型 | 默认值 | 示例 | +| - | - | - | - | - | +| title | 标题 | String | '' | - | +| data | 级联选择器的树形数据,用于初始化选项 | Array | [] | - | +| selectIndex | 被选中的索引值,拉起选择器后显示这个索引值对应的内容 | Array | [] | [1] | + +* `data`子配置项 + +| 参数 | 说明 | 类型 | 默认值 | 示例 | +| - | - | - | - | - | +| text | 每个选项展示的文案 | String/Number | - | - | +| value | 每个选项的值 | String/Number/Boolean | - | - | + +### 事件 + +| 事件名 | 说明 | 参数1 | 参数2 | 参数3 | +| - | - | - | - | - | +| select | 点击确认按钮触发此事件 | selectedVal: 当前选中项每一列的值,Array类型 | selectedIndex: 当前选中项每一列的索引,Array类型 | selectedText: 当前选中项每一列的文案,Array类型 | +| change | 滚轴滚动后触发此事件 | index: 当前滚动列次序,Number类型 | selectedIndex: 当前列选中项的索引,Number类型 | +| cancel | 点击取消按钮触发此事件 | - | - | + +### 实例方法 + +| 方法名 | 说明 | 参数1 | 参数2 | +| - | - | - | - | +| setData | 重置数据和选中的索引 | 级联树形数据结构,Array类型 | 每列选中的索引,Array类型 | diff --git a/example/data/cascade.js b/example/data/cascade.js index b40350b5ca5e92f59ee74ae4c78c886693a3e7e9..45867004e83984f5daa3fa890081a4aaba980a99 100644 --- a/example/data/cascade.js +++ b/example/data/cascade.js @@ -25,14 +25,6 @@ export const cascadeData = [ value: 'Orange', text: 'Orange', children: [ - { - value: 1, - text: 'One' - }, - { - value: 2, - text: 'Two' - }, { value: 3, text: 'Three' diff --git a/example/pages/cascade-picker.vue b/example/pages/cascade-picker.vue index 00eaaca59e47696870a7328fc43557ee78aeb81c..ce81b6795428382946fff108ab5d93a40076c40d 100644 --- a/example/pages/cascade-picker.vue +++ b/example/pages/cascade-picker.vue @@ -35,7 +35,7 @@ this.cascadePicker = this.$createCascadePicker({ title: 'Cascade Picker', data: cascadeData, - selectedIndex: [1, 0, 0], + selectedIndex: [0, 1, 0], onSelect: this.selectHandle, onCancel: this.cancelHandle, onChange: () => {