From a26248122779aff89eba2b08b50984bb82e8c690 Mon Sep 17 00:00:00 2001
From: haoziqaq <357229046@qq.com>
Date: Wed, 31 Jul 2024 23:30:14 +0800
Subject: [PATCH] docs: optimize docs

---
 packages/varlet-ui/src/picker/docs/en-US.md   | 88 ++++++++-----------
 packages/varlet-ui/src/picker/docs/zh-CN.md   | 86 +++++++-----------
 .../varlet-ui/src/picker/example/index.vue    |  8 +-
 .../src/picker/example/locale/zh-CN.ts        |  2 +-
 4 files changed, 74 insertions(+), 110 deletions(-)

diff --git a/packages/varlet-ui/src/picker/docs/en-US.md b/packages/varlet-ui/src/picker/docs/en-US.md
index f28fcb4ba4d..0160a3f4e1b 100644
--- a/packages/varlet-ui/src/picker/docs/en-US.md
+++ b/packages/varlet-ui/src/picker/docs/en-US.md
@@ -162,6 +162,32 @@ async function picker() {
 </template>
 ```
 
+### Columns Count
+
+The maximum number of displayed columns can be set via `columnsCount`, which is very useful in cascading mode.
+
+```html
+<script setup>
+import { Picker, Snackbar } from '@varlet/ui'
+import columns from '@varlet/ui/json/area.json'
+
+async function picker() {
+  const { state, texts, indexes } = await Picker({
+    cascade: true,
+    columns,
+    columnsCount: 2,
+    onChange(values, indexes) {
+      Snackbar(`values: ${values.toString()}, indexes: ${indexes.toString()}`)
+    },
+  })
+}
+</script>
+
+<template>
+  <var-button type="primary" block @click="picker">Columns Count</var-button>
+</template>
+```
+
 ### Value Mapping
 
 ```html
@@ -202,32 +228,6 @@ async function picker() {
 </template>
 ```
 
-### Columns Count
-
-`columns-count` property is used to config number of columns to be displayed. If not set, total columns will be displayed.
-
-```html
-<script setup>
-import { Picker, Snackbar } from '@varlet/ui'
-import columns from '@varlet/ui/json/area.json'
-
-async function picker() {
-  const { state, texts, indexes } = await Picker({
-    cascade: true,
-    columns,
-    columnsCount: 2,
-    onChange(values, indexes) {
-      Snackbar(`values: ${values.toString()}, indexes: ${indexes.toString()}`)
-    },
-  })
-}
-</script>
-
-<template>
-  <var-button type="primary" block @click="picker">Columns Count</var-button>
-</template>
-```
-
 ## Component Call
 
 ### Single Column Picker
@@ -370,33 +370,15 @@ function handleChange(values, indexes) {
 </template>
 ```
 
-### Value Mapping
+### Columns Count
 
 ```html
 <script setup>
 import { ref } from 'vue'
 import { Snackbar } from '@varlet/ui'
+import area from '@varlet/ui/json/area.json'
 
-const columns = ref([
-  [
-    { text: 'A', value: 1 },
-    { text: 'B', value: 2 },
-    { text: 'C', value: 3 },
-    { text: 'D', value: 4 },
-  ],
-  [
-    { text: 'A', value: 1 },
-    { text: 'B', value: 2 },
-    { text: 'C', value: 3 },
-    { text: 'D', value: 4 },
-  ],
-  [
-    { text: 'A', value: 1 },
-    { text: 'B', value: 2 },
-    { text: 'C', value: 3 },
-    { text: 'D', value: 4 },
-  ],
-])
+const columns = ref(area)
 
 function handleChange(values, indexes) {
   Snackbar(`values: ${values.toString()}, indexes: ${indexes.toString()}`)
@@ -404,11 +386,11 @@ function handleChange(values, indexes) {
 </script>
 
 <template>
-  <var-picker :columns="columns" @change="handleChange" />
+  <var-picker cascade :columns="columns" :columns-count="2" @change="handleChange" />
 </template>
 ```
 
-### Columns Count
+### Value Mapping
 
 ```html
 <script setup>
@@ -442,7 +424,7 @@ function handleChange(values, indexes) {
 </script>
 
 <template>
-  <var-picker :columns="columns" columns-count="2" @change="handleChange" />
+  <var-picker :columns="columns" @change="handleChange" />
 </template>
 ```
 
@@ -510,8 +492,8 @@ function handleChange(values, indexes) {
 | `toolbar` | Whether to display the upper toolbar | _boolean_ | `true` |
 | `cascade` | Whether to enable cascade mode | _boolean_ | `true` |
 | `option-height` | The height of the option | _string \| number_ | `44` |
-| `option-count` | Number of visible options | _string \| number_ | `6` |
-| `columns-count`  ***3.3.11***  | Number of visible columns(defaults to display total columns) | _string \| number_ | `-` |
+| `option-count` | Number of visible columns | _string \| number_ | `6` |
+| `columns-count`  ***3.3.11***  | Number of visible columns | _string \| number_ | `-` |
 | `confirm-button-text` | Confirm button text | _string_ | `Confirm` |
 | `cancel-button-text` | Cancel button text | _string_ | `Cancel` |
 | `confirm-button-text-color` | Confirm button text color | _string_ | `-` |
@@ -537,7 +519,7 @@ function handleChange(values, indexes) {
 | `confirmButtonTextColor` | Confirm button text color | _string_ | `-` |
 | `cancelButtonTextColor`  | Cancel button text color | _string_ | `-` |
 | `closeOnClickOverlay`    | Whether to click the overlay to close the picker  | _boolean_ |  `true`  |
-| `closeOnkeyEscape`       | Whether to support keyboard ESC to close the picker | _boolean_ |`true`  |
+| `closeOnKeyEscape`       | Whether to support keyboard ESC to close the picker | _boolean_ |`true`  |
 | `safeArea`               | Whether to enable bottom safety zone adaptation      | _boolean_             | `false`  |
 | `onClickOverlay`         | Click overlay callback  | _() => void_   | `-`  |
 | `onOpen`                 | Popup open callback | _() => void_ | `-` |
diff --git a/packages/varlet-ui/src/picker/docs/zh-CN.md b/packages/varlet-ui/src/picker/docs/zh-CN.md
index f5ff1ee505b..4dceb9568d3 100644
--- a/packages/varlet-ui/src/picker/docs/zh-CN.md
+++ b/packages/varlet-ui/src/picker/docs/zh-CN.md
@@ -162,6 +162,32 @@ async function picker() {
 </template>
 ```
 
+### 列数量
+
+通过 `columnsCount` 设置最大显示列的数量，在级联模式下十分有用。
+
+```html
+<script setup>
+import { Picker, Snackbar } from '@varlet/ui'
+import columns from '@varlet/ui/json/area.json'
+
+async function picker() {
+  const { state, texts, indexes } = await Picker({
+    cascade: true,
+    columns,
+    columnsCount: 2,
+    onChange(values, indexes) {
+      Snackbar(`values: ${values.toString()}, indexes: ${indexes.toString()}`)
+    },
+  })
+}
+</script>
+
+<template>
+  <var-button type="primary" block @click="picker">配置显示列</var-button>
+</template>
+```
+
 ### 值映射
 
 ```html
@@ -202,32 +228,6 @@ async function picker() {
 </template>
 ```
 
-### 配置显示列
-
-可以通过`columns-count`属性配置显示的列数，默认将显示所有列。
-
-```html
-<script setup>
-import { Picker, Snackbar } from '@varlet/ui'
-import columns from '@varlet/ui/json/area.json'
-
-async function picker() {
-  const { state, texts, indexes } = await Picker({
-    cascade: true,
-    columns,
-    columnsCount: 2,
-    onChange(values, indexes) {
-      Snackbar(`values: ${values.toString()}, indexes: ${indexes.toString()}`)
-    },
-  })
-}
-</script>
-
-<template>
-  <var-button type="primary" block @click="picker">配置显示列</var-button>
-</template>
-```
-
 ## 组件调用
 
 ### 单列选择
@@ -370,33 +370,15 @@ function handleChange(values, indexes) {
 </template>
 ```
 
-### 值的映射
+### 列数量
 
 ```html
 <script setup>
 import { ref } from 'vue'
 import { Snackbar } from '@varlet/ui'
+import area from '@varlet/ui/json/area.json'
 
-const columns = ref([
-  [
-    { text: 'A', value: 1 },
-    { text: 'B', value: 2 },
-    { text: 'C', value: 3 },
-    { text: 'D', value: 4 },
-  ],
-  [
-    { text: 'A', value: 1 },
-    { text: 'B', value: 2 },
-    { text: 'C', value: 3 },
-    { text: 'D', value: 4 },
-  ],
-  [
-    { text: 'A', value: 1 },
-    { text: 'B', value: 2 },
-    { text: 'C', value: 3 },
-    { text: 'D', value: 4 },
-  ],
-])
+const columns = ref(area)
 
 function handleChange(values, indexes) {
   Snackbar(`values: ${values.toString()}, indexes: ${indexes.toString()}`)
@@ -404,11 +386,11 @@ function handleChange(values, indexes) {
 </script>
 
 <template>
-  <var-picker :columns="columns" @change="handleChange" />
+  <var-picker cascade :columns="columns" :columns-count="2" @change="handleChange" />
 </template>
 ```
 
-### 配置显示列
+### 值的映射
 
 ```html
 <script setup>
@@ -442,7 +424,7 @@ function handleChange(values, indexes) {
 </script>
 
 <template>
-  <var-picker :columns="columns" columns-count="2" @change="handleChange" />
+  <var-picker :columns="columns" @change="handleChange" />
 </template>
 ```
 
@@ -511,7 +493,7 @@ function handleChange(values, indexes) {
 | `cascade` | 是否开启级联模式 | _boolean_ | `true` |
 | `option-height` | 选项的高度(px rem) | _string \| number_ | `44` |
 | `option-count` | 可见的选项个数 | _string \| number_ | `6` |
-| `columns-count`  ***3.3.11*** | 显示列数(默认显示全部列) | _string \| number_ | `-` |
+| `columns-count`  ***3.3.11*** | 最大显示列数 | _string \| number_ | `-` |
 | `confirm-button-text` | 确认按钮文字 | _string_ | `确认` |
 | `cancel-button-text` | 取消按钮文字 | _string_ | `取消` |
 | `confirm-button-text-color` | 确认按钮文字颜色 | _string_ | `-` |
@@ -531,7 +513,7 @@ function handleChange(values, indexes) {
 | `cascade`                | 是否开启级联模式 | _boolean_ | `true` |
 | `optionHeight`           | 选项的高度 | _string \| number_ | `44` |
 | `optionCount`            | 可见的选项个数 | _string \| number_ | `6` |
-| `columnsCount`  ***3.3.11***   | 显示列数(默认显示全部列) | _string \| number_ | `-` |
+| `columnsCount`  ***3.3.11***   | 最大显示列数 | _string \| number_ | `-` |
 | `confirmButtonText`      | 确认按钮文字 | _string_ | `确认` |
 | `cancelButtonText`       | 取消按钮文字 | _string_ | `取消` |
 | `confirmButtonTextColor` | 确认按钮文字颜色 | _string_ | `-` |
diff --git a/packages/varlet-ui/src/picker/example/index.vue b/packages/varlet-ui/src/picker/example/index.vue
index c5b0f129d90..f81e51b50b9 100644
--- a/packages/varlet-ui/src/picker/example/index.vue
+++ b/packages/varlet-ui/src/picker/example/index.vue
@@ -144,8 +144,8 @@ function handleChange(values, indexes) {
     <var-button type="primary" block @click="picker2">{{ t('multiplePicker') }}</var-button>
     <var-button type="primary" block @click="picker3">{{ t('cascadePicker') }}</var-button>
     <var-button type="primary" block @click="picker4">{{ t('areaPicker') }}</var-button>
-    <var-button type="primary" block @click="picker5">{{ t('valueMapping') }}</var-button>
     <var-button type="primary" block @click="picker6">{{ t('columnsCount') }}</var-button>
+    <var-button type="primary" block @click="picker5">{{ t('valueMapping') }}</var-button>
   </var-space>
 
   <app-type>{{ t('componentCall') }}</app-type>
@@ -162,12 +162,12 @@ function handleChange(values, indexes) {
   <app-type>{{ t('areaPicker') }}</app-type>
   <var-picker :columns="columns4" cascade @change="handleChange" />
 
+  <app-type>{{ t('columnsCount') }}</app-type>
+  <var-picker :columns="columns4" cascade :columns-count="2" @change="handleChange" />
+
   <app-type>{{ t('valueMapping') }}</app-type>
   <var-picker :columns="columns5" @change="handleChange" />
 
-  <app-type>{{ t('columnsCount') }}</app-type>
-  <var-picker :columns="columns5" columns-count="2" @change="handleChange" />
-
   <app-type>{{ t('twoWayBinding') }}</app-type>
   <var-space direction="column" size="large">
     <var-button type="primary" @click="values = ['A', 'B', 'C']">values: {{ values }} {{ t('reset') }}</var-button>
diff --git a/packages/varlet-ui/src/picker/example/locale/zh-CN.ts b/packages/varlet-ui/src/picker/example/locale/zh-CN.ts
index f5f398b1113..deb3bf4e37c 100644
--- a/packages/varlet-ui/src/picker/example/locale/zh-CN.ts
+++ b/packages/varlet-ui/src/picker/example/locale/zh-CN.ts
@@ -5,7 +5,7 @@ export default {
   multiplePicker: '多列选择',
   cascadePicker: '级联选择',
   areaPicker: '地区选择',
-  columnsCount: '配置显示列',
+  columnsCount: '列数量',
   valueMapping: '值映射',
   twoWayBinding: '双向绑定',
   reset: '点击重置',