docs(Picker): new document

packages/vant/docs/markdown/migrate-from-v3.zh-CN.md

@@ -17,6 +17,7 @@
 
 #### 主要变更
 
+- 支持通过 `v-model` 绑定当前选中的值，移除 `default-index` 属性
 - 重新定义了 `columns` 属性的结构
 - 移除了所有操作内部数据的实例方法
 - 调整了 `confirm`、`cancel`、`change` 事件的参数

packages/vant/src/picker/Picker.tsx

@@ -61,7 +61,6 @@ export const pickerSharedProps = {
 const pickerProps = extend({}, pickerSharedProps, {
   columns: makeArrayProp<PickerColumn | PickerColumn[]>(),
   modelValue: makeArrayProp<number | string>(),
-  defaultIndex: makeNumericProp(0),
   toolbarPosition: makeStringProp<PickerToolbarPosition>('top'),
   columnsFieldNames: Object as PropType<PickerFieldNames>,
 });

packages/vant/src/picker/README.md

@@ -42,11 +42,11 @@ export default {
       { text: 'Indiana', value: 'Indiana' },
       { text: 'Maine', value: 'Maine' },
     ];
-    const onConfirm = (option, index) => {
+    const onConfirm = ({ selectedValues }) => {
-      Toast(`Value: ${option.value}, Index: ${index}`);
+      Toast(`Value: ${selectedValues.join(',')}`);
     };
-    const onChange = (option, index) => {
+    const onChange = ({ selectedValues }) => {
-      Toast(`Value: ${option.value}, Index: ${index}`);
+      Toast(`Value: ${selectedValues.join(',')}`);
     };
     const onCancel = () => Toast('Cancel');
 
@@ -60,6 +60,57 @@ export default {
 };
 ```
 
+### With Popup
+
+```html
+<van-field
+  v-model="result"
+  is-link
+  readonly
+  label="City"
+  placeholder="Choose City"
+  @click="showPicker = true"
+/>
+<van-popup v-model:show="showPicker" round position="bottom">
+  <van-picker
+    title="Title"
+    :columns="columns"
+    @cancel="showPicker = false"
+    @confirm="onConfirm"
+  />
+</van-popup>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const columns = [
+      { text: 'Delaware', value: 'Delaware' },
+      { text: 'Florida', value: 'Florida' },
+      { text: 'Georqia', value: 'Georqia' },
+      { text: 'Indiana', value: 'Indiana' },
+      { text: 'Maine', value: 'Maine' },
+    ];
+    const result = ref('');
+    const showPicker = ref(false);
+
+    const onConfirm = ({ selectedOptions }) => {
+      showPicker.value = false;
+      fieldValue.value = selectedOptions[0].text;
+    };
+
+    return {
+      result,
+      columns,
+      onConfirm,
+      showPicker,
+    };
+  },
+};
+```
+
 ### Multiple Columns
 
 ```html
@@ -101,27 +152,45 @@ export default {
     const columns = [
       {
         text: 'Zhejiang',
+        value: 'Zhejiang',
         children: [
           {
             text: 'Hangzhou',
-            children: [{ text: 'Xihu' }, { text: 'Yuhang' }],
+            value: 'Hangzhou',
+            children: [
+              { text: 'Xihu', value: 'Xihu' },
+              { text: 'Yuhang', value: 'Yuhang' },
+            ],
           },
           {
             text: 'Wenzhou',
-            children: [{ text: 'Lucheng' }, { text: 'Ouhai' }],
+            value: 'Wenzhou',
+            children: [
+              { text: 'Lucheng', value: 'Lucheng' },
+              { text: 'Ouhai', value: 'Ouhai' },
+            ],
           },
         ],
       },
       {
         text: 'Fujian',
+        value: 'Fujian',
         children: [
           {
             text: 'Fuzhou',
-            children: [{ text: 'Gulou' }, { text: 'Taijiang' }],
+            value: 'Fuzhou',
+            children: [
+              { text: 'Gulou', value: 'Gulou' },
+              { text: 'Taijiang', value: 'Taijiang' },
+            ],
           },
           {
             text: 'Xiamen',
-            children: [{ text: 'Siming' }, { text: 'Haicang' }],
+            value: 'Xiamen',
+            children: [
+              { text: 'Siming', value: 'Siming' },
+              { text: 'Haicang', value: 'Haicang' },
+            ],
           },
         ],
       },
@@ -142,51 +211,15 @@ export default {
 export default {
   setup() {
     const columns = [
-      { text: 'Delaware', disabled: true },
+      { text: 'Delaware', value: 'Delaware', disabled: true },
-      { text: 'Florida' },
+      { text: 'Florida', value: 'Florida' },
-      { text: 'Georqia' },
+      { text: 'Georqia', value: 'Georqia' },
     ];
-
     return { columns };
   },
 };
 ```
 
-### Set Column Values
-
-```html
-<van-picker ref="picker" title="Title" :columns="columns" @change="onChange" />
-```
-
-```js
-import { ref } from 'vue';
-
-export default {
-  setup() {
-    const picker = ref(null);
-
-    const states = {
-      Group1: ['Delaware', 'Florida', 'Georqia', 'Indiana', 'Maine'],
-      Group2: ['Alabama', 'Kansas', 'Louisiana', 'Texas'],
-    };
-    const columns = [
-      { values: Object.keys(states) },
-      { values: states.Group1 },
-    ];
-
-    const onChange = (values) => {
-      picker.value.setColumnValues(1, states[values[0]]);
-    };
-
-    return {
-      picker,
-      columns,
-      onChange,
-    };
-  },
-};
-```
-
 ### Loading
 
 When Picker columns data is acquired asynchronously, use `loading` prop to show loading prompt.
@@ -204,7 +237,7 @@ export default {
     const loading = ref(true);
 
     setTimeout(() => {
-      columns.value = ['Option'];
+      columns.value = [{ text: 'Option', value: 'option' }];
       loading.value = false;
     }, 1000);
 
@@ -213,51 +246,6 @@ export default {
 };
 ```
 
-### With Popup
-
-```html
-<van-field
-  v-model="result"
-  is-link
-  readonly
-  label="City"
-  placeholder="Choose City"
-  @click="showPicker = true"
-/>
-<van-popup v-model:show="showPicker" round position="bottom">
-  <van-picker
-    title="Title"
-    :columns="columns"
-    @cancel="showPicker = false"
-    @confirm="onConfirm"
-  />
-</van-popup>
-```
-
-```js
-import { ref } from 'vue';
-
-export default {
-  setup() {
-    const columns = ['Delaware', 'Florida', 'Georqia', 'Indiana', 'Maine'];
-    const result = ref('');
-    const showPicker = ref(false);
-
-    const onConfirm = (value) => {
-      result.value = value;
-      showPicker.value = false;
-    };
-
-    return {
-      result,
-      columns,
-      onConfirm,
-      showPicker,
-    };
-  },
-};
-```
-
 ### Custom Columns Field
 
 ```html
@@ -302,6 +290,7 @@ export default {
 
     const customFieldName = {
       text: 'cityName',
+      value: 'cityName',
       children: 'cities',
     };
 
@@ -319,8 +308,8 @@ export default {
 
 | Attribute | Description | Type | Default |
 | --- | --- | --- | --- |
-| columns | Columns data | _Column[]_ | `[]` |
+| columns | Columns data | _PickerOption[] \| PickerOption[][]_ | `[]` |
-| columns-field-names | custom columns field | _object_ | `{ text: 'text', values: 'values', children: 'children' }` |
+| columns-field-names | custom columns field | _object_ | `{ text: 'text', value: 'value', children: 'children' }` |
 | title | Toolbar title | _string_ | - |
 | confirm-button-text | Text of confirm button | _string_ | `Confirm` |
 | cancel-button-text | Text of cancel button | _string_ | `Cancel` |
@@ -328,58 +317,46 @@ export default {
 | loading | Whether to show loading prompt | _boolean_ | `false` |
 | show-toolbar | Whether to show toolbar | _boolean_ | `true` |
 | allow-html | Whether to allow HTML in option text | _boolean_ | `false` |
-| default-index | Default value index of single column picker | _number \| string_ | `0` |
 | option-height | Option height, supports `px` `vw` `vh` `rem` unit, default `px` | _number \| string_ | `44` |
 | visible-option-num | Count of visible columns | _number \| string_ | `6` |
 | swipe-duration | Duration of the momentum animation，unit `ms` | _number \| string_ | `1000` |
 
 ### Events
 
-Picker events will pass different parameters according to the columns are single or multiple
-
 | Event | Description | Arguments |
 | --- | --- | --- |
-| confirm | Emitted when click confirm button | Single column：current value，current index<br>Multiple columns：current values，current indexes |
+| confirm | Emitted when click confirm button | _{ selectedValues, selectedOptions }_ |
-| cancel | Emitted when click cancel button | Single column：current value，current index<br>Multiple columns：current values，current indexes |
+| cancel | Emitted when click cancel button | _{ selectedValues, selectedOptions }_ |
-| change | Emitted when current option changed | Single column：Picker instance, current value，current index<br>Multiple columns：Picker instance, current values，column index |
+| change | Emitted when current option changed | _{ selectedValues, selectedOptions, columnIndex }_ |
 
 ### Slots
 
 | Name            | Description                  | SlotProps              |
-| --------------- | ---------------------------- | -------------------------- |
+| --------------- | ---------------------------- | ---------------------- |
 | toolbar `3.1.2` | Custom toolbar content       | -                      |
 | title           | Custom title                 | -                      |
 | confirm         | Custom confirm button text   | -                      |
 | cancel          | Custom cancel button text    | -                      |
-| option          | Custom option content        | _option: string \| object_ |
+| option          | Custom option content        | _option: PickerOption_ |
 | columns-top     | Custom content above columns | -                      |
 | columns-bottom  | Custom content below columns | -                      |
 
-### Data Structure of Column
+### Data Structure of PickerOption
 
 | Key       | Description               | Type                        |
-| ------------ | ------------------------- | --------------------------- |
+| --------- | ------------------------- | --------------------------- |
-| values       | Value of column           | _Array<string \| number>_   |
+| text      | Text                      | _string \| number_          |
-| defaultIndex | Default value index       | _number_                    |
+| value     | Value of option           | _string \| number_          |
-| className    | ClassName for this column | _string \| Array \| object_ |
+| disabled  | Whether to disable option | _boolean_                   |
-| children     | Cascade children          | _Column_                    |
+| children  | Cascade children options  | _PickerOption[]_            |
+| className | ClassName for this option | _string \| Array \| object_ |
 
 ### Methods
 
 Use [ref](https://v3.vuejs.org/guide/component-template-refs.html) to get Picker instance and call instance methods.
 
 | Name    | Description                           | Attribute | Return value |
-| --- | --- | --- | --- |
+| ------- | ------------------------------------- | --------- | ------------ |
-| getValues | Get current values of all columns | - | values |
-| setValues | Set current values of all columns | values | - |
-| getIndexes | Get current indexes of all columns | - | indexes |
-| setIndexes | Set current indexes of all columns | indexes | - |
-| getColumnValue | Get current value of the column | columnIndex | value |
-| setColumnValue | Set current value of the column | columnIndex, value | - |
-| getColumnIndex | Get current index of the column | columnIndex | optionIndex |
-| setColumnIndex | Set current index of the column | columnIndex, optionIndex | - |
-| getColumnValues | Get columns data of the column | columnIndex | values |
-| setColumnValues | Set columns data of the column | columnIndex, values | - |
 | confirm | Stop scrolling and emit confirm event | -         | -            |
 
 ### Types
@@ -393,9 +370,10 @@ import type {
   PickerOption,
   PickerInstance,
   PickerFieldNames,
-  PickerObjectColumn,
-  PickerObjectOption,
   PickerToolbarPosition,
+  PickerCancelEventParams,
+  PickerChangeEventParams,
+  PickerConfirmEventParams,
 } from 'vant';
 ```
 

packages/vant/src/picker/README.zh-CN.md

@@ -49,15 +49,12 @@ export default {
       { text: '温州', value: 'Wenzhou' },
       { text: '绍兴', value: 'Shaoxing' },
       { text: '湖州', value: 'Huzhou' },
-      { text: '嘉兴', value: 'Jiaxing' },
-      { text: '金华', value: 'Jinhua' },
-      { text: '衢州', value: 'Quzhou' },
     ];
-    const onConfirm = (option, index) => {
+    const onConfirm = ({ selectedValues }) => {
-      Toast(`当前值: ${option.value}, 当前索引: ${index}`);
+      Toast(`当前值: ${selectedValues.join(',')}`);
     };
-    const onChange = (option, index) => {
+    const onChange = ({ selectedValues }) => {
-      Toast(`当前值: ${option.value}, 当前索引: ${index}`);
+      Toast(`当前值: ${selectedValues.join(',')}`);
     };
     const onCancel = () => Toast('取消');
 
@@ -71,6 +68,58 @@ export default {
 };
 ```
 
+### 搭配弹出层使用
+
+在实际场景中，Picker 通常作为用于辅助表单填写，可以搭配 Popup 和 Field 实现该效果。
+
+```html
+<van-field
+  v-model="value"
+  is-link
+  readonly
+  label="城市"
+  placeholder="选择城市"
+  @click="showPicker = true"
+/>
+<van-popup v-model:show="showPicker" round position="bottom">
+  <van-picker
+    :columns="columns"
+    @cancel="showPicker = false"
+    @confirm="onConfirm"
+  />
+</van-popup>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const columns = [
+      { text: '杭州', value: 'Hangzhou' },
+      { text: '宁波', value: 'Ningbo' },
+      { text: '温州', value: 'Wenzhou' },
+      { text: '绍兴', value: 'Shaoxing' },
+      { text: '湖州', value: 'Huzhou' },
+    ];
+    const result = ref('');
+    const showPicker = ref(false);
+
+    const onConfirm = ({ selectedOptions }) => {
+      showPicker.value = false;
+      fieldValue.value = selectedOptions[0].text;
+    };
+
+    return {
+      result,
+      columns,
+      onConfirm,
+      showPicker,
+    };
+  },
+};
+```
+
 ### 多列选择
 
 `columns` 属性可以通过二维数组的形式配置多列选择。
@@ -118,27 +167,45 @@ export default {
     const columns = [
       {
         text: '浙江',
+        value: 'Zhejiang',
         children: [
           {
             text: '杭州',
-            children: [{ text: '西湖区' }, { text: '余杭区' }],
+            value: 'Hangzhou',
+            children: [
+              { text: '西湖区', value: 'Xihu' },
+              { text: '余杭区', value: 'Yuhang' },
+            ],
           },
           {
             text: '温州',
-            children: [{ text: '鹿城区' }, { text: '瓯海区' }],
+            value: 'Wenzhou',
+            children: [
+              { text: '鹿城区', value: 'Lucheng' },
+              { text: '瓯海区', value: 'Ouhai' },
+            ],
           },
         ],
       },
       {
         text: '福建',
+        value: 'Fujian',
         children: [
           {
             text: '福州',
-            children: [{ text: '鼓楼区' }, { text: '台江区' }],
+            value: 'Fuzhou',
+            children: [
+              { text: '鼓楼区', value: 'Gulou' },
+              { text: '台江区', value: 'Taijiang' },
+            ],
           },
           {
             text: '厦门',
-            children: [{ text: '思明区' }, { text: '海沧区' }],
+            value: 'Xiamen',
+            children: [
+              { text: '思明区', value: 'Siming' },
+              { text: '海沧区', value: 'Haicang' },
+            ],
           },
         ],
       },
@@ -163,53 +230,15 @@ export default {
 export default {
   setup() {
     const columns = [
-      { text: '杭州', disabled: true },
+      { text: '杭州', value: 'Hangzhou', disabled: true },
-      { text: '宁波' },
+      { text: '宁波', value: 'Ningbo' },
-      { text: '温州' },
+      { text: '温州', value: 'Wenzhou' },
     ];
-
     return { columns };
   },
 };
 ```
 
-### 动态设置选项
-
-通过 Picker 上的实例方法可以更灵活地控制选择器，比如使用 `setColumnValues` 方法实现多列联动。
-
-```html
-<van-picker ref="picker" :columns="columns" @change="onChange" />
-```
-
-```js
-import { ref } from 'vue';
-
-export default {
-  setup() {
-    const picker = ref(null);
-
-    const cities = {
-      浙江: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
-      福建: ['福州', '厦门', '莆田', '三明', '泉州'],
-    };
-    const columns = [
-      { values: Object.keys(cities) },
-      { values: cities['浙江'] },
-    ];
-
-    const onChange = (values) => {
-      picker.value.setColumnValues(1, cities[values[0]]);
-    };
-
-    return {
-      picker,
-      columns,
-      onChange,
-    };
-  },
-};
-```
-
 ### 加载状态
 
 若选择器数据是异步获取的，可以通过 `loading` 属性显示加载提示。
@@ -227,7 +256,7 @@ export default {
     const loading = ref(true);
 
     setTimeout(() => {
-      columns.value = ['选项'];
+      columns.value = [{ text: '选项', value: 'option' }];
       loading.value = false;
     }, 1000);
 
@@ -236,52 +265,6 @@ export default {
 };
 ```
 
-### 搭配弹出层使用
-
-在实际场景中，Picker 通常作为用于辅助表单填写，可以搭配 Popup 和 Field 实现该效果。
-
-```html
-<van-field
-  v-model="value"
-  is-link
-  readonly
-  label="城市"
-  placeholder="选择城市"
-  @click="showPicker = true"
-/>
-<van-popup v-model:show="showPicker" round position="bottom">
-  <van-picker
-    :columns="columns"
-    @cancel="showPicker = false"
-    @confirm="onConfirm"
-  />
-</van-popup>
-```
-
-```js
-import { ref } from 'vue';
-
-export default {
-  setup() {
-    const columns = ['杭州', '宁波', '温州', '绍兴', '湖州', '嘉兴', '金华'];
-    const result = ref('');
-    const showPicker = ref(false);
-
-    const onConfirm = (value) => {
-      result.value = value;
-      showPicker.value = false;
-    };
-
-    return {
-      result,
-      columns,
-      onConfirm,
-      showPicker,
-    };
-  },
-};
-```
-
 ### 自定义 Columns 的结构
 
 ```html
@@ -326,6 +309,7 @@ export default {
 
     const customFieldName = {
       text: 'cityName',
+      value: 'cityName',
       children: 'cities',
     };
 
@@ -343,8 +327,8 @@ export default {
 
 | 参数 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |
-| columns | 对象数组，配置每一列显示的数据 | _Column[]_ | `[]` |
+| columns | 对象数组，配置每一列显示的数据 | _PickerOption[] \| PickerOption[][]_ | `[]` |
-| columns-field-names | 自定义 `columns` 结构中的字段 | _object_ | `{ text: 'text', values: 'values', children: 'children' }` |
+| columns-field-names | 自定义 `columns` 结构中的字段 | _object_ | `{ text: 'text', value: 'value', children: 'children' }` |
 | title | 顶部栏标题 | _string_ | - |
 | confirm-button-text | 确认按钮文字 | _string_ | `确认` |
 | cancel-button-text | 取消按钮文字 | _string_ | `取消` |
@@ -352,61 +336,47 @@ export default {
 | loading | 是否显示加载状态 | _boolean_ | `false` |
 | show-toolbar | 是否显示顶部栏 | _boolean_ | `true` |
 | allow-html | 是否允许选项内容中渲染 HTML | _boolean_ | `false` |
-| default-index | 单列选择时，默认选中项的索引 | _number \| string_ | `0` |
 | option-height | 选项高度，支持 `px` `vw` `vh` `rem` 单位，默认 `px` | _number \| string_ | `44` |
 | visible-option-num | 可见的选项个数 | _number \| string_ | `6` |
 | swipe-duration | 快速滑动时惯性滚动的时长，单位 `ms` | _number \| string_ | `1000` |
 
 ### Events
 
-当选择器有多列时，事件回调参数会返回数组。
-
 | 事件名 | 说明 | 回调参数 |
 | --- | --- | --- |
-| confirm | 点击完成按钮时触发 | 单列：选中值，选中值对应的索引<br>多列：所有列选中值，所有列选中值对应的索引 |
+| confirm | 点击完成按钮时触发 | _{ selectedValues, selectedOptions }_ |
-| cancel | 点击取消按钮时触发 | 单列：选中值，选中值对应的索引<br>多列：所有列选中值，所有列选中值对应的索引 |
+| cancel | 点击取消按钮时触发 | _{ selectedValues, selectedOptions }_ |
-| change | 选项改变时触发 | 单列：选中值，选中值对应的索引<br>多列：所有列选中值，当前列对应的索引 |
+| change | 选项改变时触发 | _{ selectedValues, selectedOptions, columnIndex }_ |
 
 ### Slots
 
 | 名称             | 说明                   | 参数                   |
-| ---------------- | ---------------------- | -------------------------- |
+| ---------------- | ---------------------- | ---------------------- |
 | toolbar `v3.1.2` | 自定义整个顶部栏的内容 | -                      |
 | title            | 自定义标题内容         | -                      |
 | confirm          | 自定义确认按钮内容     | -                      |
 | cancel           | 自定义取消按钮内容     | -                      |
-| option           | 自定义选项内容         | _option: string \| object_ |
+| option           | 自定义选项内容         | _option: PickerOption_ |
 | columns-top      | 自定义选项上方内容     | -                      |
 | columns-bottom   | 自定义选项下方内容     | -                      |
 
-### Column 数据结构
+### PickerOption 数据结构
-
-当传入多列数据时，`columns` 为一个对象数组，数组中的每一个对象配置每一列，每一列有以下 `key`:
 
 | 键名      | 说明         | 类型                        |
-| ------------ | -------------------------- | --------------------------- |
+| --------- | ------------ | --------------------------- |
-| values       | 列中对应的备选值           | _Array<string \| number>_   |
+| text      | 选项文字内容 | _string \| number_          |
-| defaultIndex | 初始选中项的索引，默认为 0 | _number_                    |
+| value     | 选项对应的值 | _string \| number_          |
-| className    | 为对应列添加额外的类名     | _string \| Array \| object_ |
+| disabled  | 是否禁用选项 | _boolean_                   |
-| children     | 级联选项                   | _Column_                    |
+| children  | 级联选项     | _PickerOption[]_            |
+| className | 选项额外类名 | _string \| Array \| object_ |
 
 ### 方法
 
 通过 ref 可以获取到 Picker 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。
 
 | 方法名  | 说明                              | 参数 | 返回值 |
-| --- | --- | --- | --- |
+| ------- | --------------------------------- | ---- | ------ |
-| getValues | 获取所有列选中的值 | - | values |
+| confirm | 停止惯性滚动并触发 `confirm` 事件 | -    | -      |
-| setValues | 设置所有列选中的值 | values | - |
-| getIndexes | 获取所有列选中值对应的索引 | - | indexes |
-| setIndexes | 设置所有列选中值对应的索引 | indexes | - |
-| getColumnValue | 获取对应列选中的值 | columnIndex | value |
-| setColumnValue | 设置对应列选中的值 | columnIndex, value | - |
-| getColumnIndex | 获取对应列选中项的索引 | columnIndex | optionIndex |
-| setColumnIndex | 设置对应列选中项的索引 | columnIndex, optionIndex | - |
-| getColumnValues | 获取对应列中所有选项 | columnIndex | values |
-| setColumnValues | 设置对应列中所有选项 | columnIndex, values | - |
-| confirm | 停止惯性滚动并触发 confirm 事件 | - | - |
 
 ### 类型定义
 
@@ -419,9 +389,10 @@ import type {
   PickerOption,
   PickerInstance,
   PickerFieldNames,
-  PickerObjectColumn,
-  PickerObjectOption,
   PickerToolbarPosition,
+  PickerCancelEventParams,
+  PickerChangeEventParams,
+  PickerConfirmEventParams,
 } from 'vant';
 ```
 

packages/vant/src/picker/demo/data.ts

@@ -5,9 +5,6 @@ export const basicColumns = {
     { text: '温州', value: 'Wenzhou' },
     { text: '绍兴', value: 'Shaoxing' },
     { text: '湖州', value: 'Huzhou' },
-    { text: '嘉兴', value: 'Jiaxing' },
-    { text: '金华', value: 'Jinhua' },
-    { text: '衢州', value: 'Quzhou' },
   ],
   'en-US': [
     { text: 'Delaware', value: 'Delaware' },