docs(site): [cascader, cascader-panel] Optimize document (#873)

opentiny · Nov 20, 2023 · b64a631 · b64a631
1 parent 83a49ee
commit b64a631
Show file tree

Hide file tree

Showing 21 changed files with 307 additions and 132 deletions.
diff --git a/examples/sites/demos/pc/app/cascader-panel/cascader-panel-props-composition-api.vue b/examples/sites/demos/pc/app/cascader-panel/cascader-panel-props-composition-api.vue
@@ -1,9 +1,8 @@
 <template>
-  <div class="cascader-panel-demo">
+  <div class="cascader-panel-demo-props">
     <div>选中值：<span>{{ value }}</span></div>
     <tiny-cascader-panel
       v-model="value"
-      class="cascader-panel-demo"
       :options="optionsCascader"
       :props="{
         children: 'children',
@@ -219,7 +218,7 @@ const optionsCascader = ref([
 </script>
 
 <style scoped>
-.cascader-panel-demo > :not(:last-child) {
-  margin-bottom: 20px;
+.cascader-panel-demo-props > :not(:last-child) {
+  margin-bottom: 12px;
 }
 </style>
diff --git a/examples/sites/demos/pc/app/cascader-panel/cascader-panel-props.vue b/examples/sites/demos/pc/app/cascader-panel/cascader-panel-props.vue
@@ -1,9 +1,8 @@
 <template>
-  <div class="cascader-panel-demo">
+  <div class="cascader-panel-demo-props">
     <div>选中值：<span>{{ value }}</span></div>
     <tiny-cascader-panel
       v-model="value"
-      class="cascader-panel-demo"
       :options="optionsCascader"
       :props="{
         children: 'children',
@@ -227,7 +226,7 @@ export default {
 </script>
 
 <style scoped>
-.cascader-panel-demo > :not(:last-child) {
-  margin-bottom: 20px;
+.cascader-panel-demo-props > :not(:last-child) {
+  margin-bottom: 12px;
 }
 </style>
diff --git a/examples/sites/demos/pc/app/cascader-panel/change-composition-api.vue b/examples/sites/demos/pc/app/cascader-panel/change-composition-api.vue
@@ -1,10 +1,9 @@
 <template>
-  <div>
+  <div class="cascader-panel-demo-event">
     <tiny-button @click="clearCheckedNodes">清除选中节点</tiny-button>
     <tiny-cascader-panel
       v-model="value"
-      ref="CascaderPanelRef"
-      class="cascader-panel-demo"
+      ref="CascaderPanel"
       :options="optionsCascader"
       @change="change"
       @expand-change="expandChange"
@@ -211,14 +210,14 @@ const optionsCascader = ref([
     ]
   }
 ])
-const CascaderPanelRef = ref()
+const cascaderPanelRef = ref()
 
 function clearCheckedNodes() {
-  CascaderPanelRef.value.clearCheckedNodes()
+  cascaderPanelRef.value.clearCheckedNodes()
 }
 
 function change(value) {
-  const checkVal = CascaderPanelRef.value.getCheckedNodes()
+  const checkVal = cascaderPanelRef.value.getCheckedNodes()
   let mess = ''
 
   if (checkVal.length) {
@@ -238,7 +237,7 @@ function expandChange(value) {
 </script>
 
 <style scoped>
-.cascader-panel-demo {
-  min-height: 200px;
+.cascader-panel-demo-event > :not(:last-child) {
+  margin-bottom: 12px;
 }
 </style>
diff --git a/examples/sites/demos/pc/app/cascader-panel/change.vue b/examples/sites/demos/pc/app/cascader-panel/change.vue
@@ -1,10 +1,9 @@
 <template>
-  <div>
+  <div class="cascader-panel-demo-event">
     <tiny-button @click="clearCheckedNodes">清除选中节点</tiny-button>
     <tiny-cascader-panel
       v-model="value"
-      ref="CascaderPanel"
-      class="cascader-panel-demo"
+      ref="cascaderPanel"
       :options="optionsCascader"
       @change="change"
       @expand-change="expandChange"
@@ -221,13 +220,13 @@ export default {
   },
   methods: {
     clearCheckedNodes() {
-      this.$refs.CascaderPanel.clearCheckedNodes()
+      this.$refs.cascaderPanel.clearCheckedNodes()
     },
     expandChange(value) {
       Modal.message({ message: `节点展开：${value}`, status: 'info' })
     },
     change(value) {
-      const checkVal = this.$refs.CascaderPanel.getCheckedNodes()
+      const checkVal = this.$refs.cascaderPanel.getCheckedNodes()
       let mess = ''
 
       if (checkVal.length) {
@@ -244,7 +243,7 @@ export default {
 </script>
 
 <style scoped>
-.cascader-panel-demo {
-  min-height: 200px;
+.cascader-panel-demo-event > :not(:last-child){
+  margin-bottom: 12px;
 }
 </style>
diff --git a/examples/sites/demos/pc/app/cascader-panel/webdoc/cascader-panel.js b/examples/sites/demos/pc/app/cascader-panel/webdoc/cascader-panel.js
@@ -13,38 +13,56 @@ export default {
       },
       'codeFiles': ['basic-usage.vue']
     },
-    {
-      'demoId': 'change',
-      'name': { 'zh-CN': '事件与方法', 'en-US': 'Selected node changes' },
-      'desc': {
-        'zh-CN':
-          '<p>通过 <code>change</code> 点击节点后触发的事件，回调参数为 选中节点的值\n通过 <code>clearCheckedNodes</code> 清除选中的节点。\n通过 <code>getCheckedNodes</code> 获取选中的节点。</p>\n',
-        'en-US':
-          '<p>The event is triggered after a node is clicked through <code>change</code>. The callback parameter is the value of the selected node.\nYou can clear the selected node through <code>clearCheckedNodes</code>. \n Obtain the selected node through <code>getCheckedNodes</code>. </p>\n'
-      },
-      'codeFiles': ['change.vue']
-    },
     {
       'demoId': 'custom-option-content',
       'name': { 'zh-CN': '自定义节点内容', 'en-US': 'Custom Node Content' },
       'desc': {
-        'zh-CN':
-          '<p>可以通过 <code>scoped slot</code> 对级联面板的备选项的节点内容进行自定义，<code>scoped slot</code> 会传入两个字段 <code>node</code> 和 <code>data</code>，分别表示当前节点的 Node 对象和数据。</p>\n',
-        'en-US':
-          '<p>You can use <code>scoped slot</code> to customize the node content of the options of the cascading panel. <code>scoped slot</code> transfers two fields: <code>node</code> and <code>data</code>, indicating the node object and data of the current node, respectively. </p>\n'
+        'zh-CN': `<p>
+            <div>可以通过 <code>scoped slot</code> 对级联面板的备选项的节点内容进行自定义。</div>
+            <div><code>scoped slot</code> 会传入两个字段 <code>node</code> 和 <code>data</code>，分别表示当前节点的 Node 对象和数据。</div>
+          </p>`,
+        'en-US': `<p>
+          The <div> can customize the node contents of the cascade panel's alternatives through the <code>scoped slot</code>. </div>
+          <div><code>scoped slot</code> passes in two fields, <code>node</code> and <code>data</code>, representing the Node object and data of the current node, respectively. </div>
+        </p>`
       },
       'codeFiles': ['custom-option-content.vue']
     },
     {
       'demoId': 'cascader-panel-props',
       'name': { 'zh-CN': 'Props 选项', 'en-US': 'Props Options' },
       'desc': {
-        'zh-CN':
-          '<div class="tip custom-block"><p class="custom-block-title">Props</p>\n<p>通过 <code>children</code> 指定子级选项，默认值为 children。\n通过 <code>emitPath</code> 是否返回由该节点所在的各级菜单的值所组成的数组。\n通过 <code>label</code> 指定显示选项 label 值，默认为 label。\n通过 <code>value</code> 指定值选项 value 值，默认为 value</p>\n</div>\n',
-        'en-US':
-          '<div class="tip custom-block"><p class="custom-block-title">Props</p>\n<p> specifies child options with <code>children</code>. The default value is children. \n Indicates whether to return an array consisting of the values of the menus where the node is located through <code>emitPath</code>. \n Use <code>label</code> to specify the label value of the display option. The default value is label. \n Use <code>value</code> to specify the value of the value option. The default value is value</p>\n</div>\n'
+        'zh-CN': `<p>
+              <div>通过 <code>children</code> 指定子级选项，默认值为 children。</div>
+              <div>通过 <code>emitPath</code> 是否返回由该节点所在的各级菜单的值所组成的数组。</div>
+              <div>通过 <code>label</code> 指定显示选项 label 值，默认为 label。</div>
+              <div>通过 <code>value</code> 指定值选项 value 值，默认为 value。</div>
+            </p>`,
+        'en-US': `<p>
+            <div> specifies the child options through <code>children</code>, which defaults to children. </div>
+            <div> Whether to return an array of values from the menu levels where the node resides via <code>emitPath</code>. </div>
+            <div> specifies the display option label value by <code>label</code>, which defaults to label. </div>
+            <div> Specifies the value option value by <code>value</code>, which defaults to value. </div>
+          </p>`
       },
       'codeFiles': ['cascader-panel-props.vue']
+    },
+    {
+      'demoId': 'change',
+      'name': { 'zh-CN': '事件与方法', 'en-US': 'Selected node changes' },
+      'desc': {
+        'zh-CN': `<p>
+            <div>通过 <code>change</code> 点击节点后触发的事件，回调参数为"选中节点的值"。</div>
+            <div>通过 <code>clearCheckedNodes</code> 清除选中的节点。</div>
+            <div>通过 <code>getCheckedNodes</code> 获取选中的节点。</dic>
+          </p>`,
+        'en-US': `<p>
+            <div> The event triggered by clicking the node through <code>change</code>, with the callback parameter "Select the value of the node". </div>
+            <div> Clear the selected nodes with <code>clearCheckedNodes</code>. </div>
+            <div> Get the selected nodes from <code>getCheckedNodes</code>. </dic>
+          </p>`
+      },
+      'codeFiles': ['change.vue']
     }
   ],
   apis: [
@@ -55,9 +73,12 @@ export default {
         {
           'name': 'modelValue / v-model',
           'type': 'ICascaderPanelNodePropValue',
-          'typeAnchorName': 'ICascaderPanelNodeValue',
+          'typeAnchorName': 'ICascaderPanelNodePropValue',
           'defaultValue': '',
-          'desc': { 'zh-CN': '选中项绑定值', 'en-US': 'Bound value of the selected item' },
+          'desc': {
+            'zh-CN': `选中项绑定值, 其类型由 props.multiple、props.emitPath 共同决定`,
+            'en-US': `Select an item binding value whose type is determined by both props.multiple and props.emitPath`
+          },
           'demoId': 'basic-usage'
         },
         {
@@ -87,6 +108,7 @@ export default {
         {
           'name': 'change',
           'type': '(value: ICascaderPanelNodePropValue) => void',
+          'typeAnchorName': 'ICascaderPanelNodePropValue',
           'defaultValue': '',
           'desc': {
             'zh-CN': '当选中节点变化时触发; 回调参数为 选中节点的值',
@@ -98,9 +120,10 @@ export default {
         {
           'name': 'expand-change',
           'type': '(value: ICascaderPanelNodeValue[]) => void',
+          'typeAnchorName': 'ICascaderPanelNodeValue',
           'defaultValue': '',
           'desc': {
-            'zh-CN': '当展开节点发生变化时触发; 回调参数为 各父级选项值组成的数组 (Array类型)',
+            'zh-CN': '当展开节点发生变化时触发; 回调参数为 各父级选项值组成的数组 (Array 类型)',
             'en-US':
               'This event is triggered when the expanded node changes. arg: The callback parameter is an array (Array type) consisting of parent option values.'
           },
@@ -113,7 +136,8 @@ export default {
           'type': '',
           'defaultValue': '',
           'desc': {
-            'zh-CN': '自定义备选项的节点内容，参数为 { node: ICascaderPanelNode, data: ICascaderPanelData }，分别为当前节点的 Node 对象和数据',
+            'zh-CN':
+              '自定义备选项的节点内容，参数为 { node: ICascaderPanelNode, data: ICascaderPanelData }，分别为当前节点的 Node 对象和数据',
             'en-US':
               'User-defined candidate node content. The parameter is {node, data}, which indicates the node object and data of the current node.'
           },
@@ -124,6 +148,7 @@ export default {
         {
           'name': 'getCheckedNodes',
           'type': '(leafOnly: boolean = false) => ICascaderPanelNode[]',
+          'typeAnchorName': 'ICascaderPanelNode',
           'defaultValue': '',
           'desc': {
             'zh-CN': '获取选中的节点;参数为 (leafOnly) 是否只是获取子节点，默认值为 false',
@@ -143,7 +168,7 @@ export default {
       'casprops: ICascaderPanelConfig': [
         {
           'name': 'expandTrigger',
-          'type': '"click" | "hover"',
+          'type': `'click' | 'hover'`,
           'defaultValue': 'click',
           'desc': {
             'zh-CN': '次级菜单的展开方式',
@@ -194,7 +219,7 @@ export default {
           'defaultValue': '',
           'desc': {
             'zh-CN':
-              '加载动态数据的方法，仅在 lazy 为 true 时有效;参数说明： node为当前点击的节点，resolve为数据加载完成的回调(必须调用)',
+              '加载动态数据的方法，仅在 lazy 为 true 时有效;参数说明： node 为当前点击的节点，resolve 为数据加载完成的回调(必须调用)',
             'en-US':
               'Method for loading dynamic data. This parameter is valid only when lazy is set to true. Parameter description: node indicates the currently clicked node. resolve indicates the callback after data loading is complete (mandatory).'
           }

diff --git a/examples/sites/demos/pc/app/cascader/check-strictly-composition-api.vue b/examples/sites/demos/pc/app/cascader/check-strictly-composition-api.vue
@@ -1,7 +1,9 @@
 <template>
-  <div>
-    <tiny-cascader :options="options" :props="{ checkStrictly: true }" v-model="value"></tiny-cascader>
-    value:{{ value }}
+  <div class="demo-tiny-cascader-check-strictly">
+    <div>value: {{ value }}</div>
+    <div>
+      <tiny-cascader :options="options" :props="{ checkStrictly: true }" v-model="value"></tiny-cascader>
+    </div>
   </div>
 </template>
 
@@ -205,3 +207,9 @@ const options = ref([
   }
 ])
 </script>
+
+<style scoped>
+.demo-tiny-cascader-check-strictly > :not(:last-child) {
+  margin-bottom: 12px;
+}
+</style>
diff --git a/examples/sites/demos/pc/app/cascader/check-strictly.vue b/examples/sites/demos/pc/app/cascader/check-strictly.vue
@@ -1,7 +1,9 @@
 <template>
-  <div>
-    <tiny-cascader :options="options" :props="{ checkStrictly: true }" v-model="value"></tiny-cascader>
-    value:{{ value }}
+  <div class="demo-tiny-cascader-check-strictly">
+    <div>value: {{ value }}</div>
+    <div>
+      <tiny-cascader :options="options" :props="{ checkStrictly: true }" v-model="value"></tiny-cascader>
+    </div>
   </div>
 </template>
 
@@ -213,3 +215,9 @@ export default {
   }
 }
 </script>
+
+<style scoped>
+.demo-tiny-cascader-check-strictly > :not(:last-child) {
+  margin-bottom: 12px;
+}
+</style>
diff --git a/examples/sites/demos/pc/app/cascader/clearable-composition-api.vue b/examples/sites/demos/pc/app/cascader/clearable-composition-api.vue
@@ -1,13 +1,5 @@
 <template>
-  <tiny-cascader
-    v-model="value"
-    :options="options"
-    clearable
-    separator="+"
-    size="medium"
-    popper-class="custom-class"
-    :popper-append-to-body="false"
-  ></tiny-cascader>
+  <tiny-cascader v-model="value" :options="options" clearable separator="+"></tiny-cascader>
 </template>
 
 <script setup>

diff --git a/examples/sites/demos/pc/app/cascader/clearable.spec.ts b/examples/sites/demos/pc/app/cascader/clearable.spec.ts
@@ -8,6 +8,4 @@ test('可清空', async ({ page }) => {
   await page.locator('.tiny-input__suffix-inner > .tiny-svg').click()
   const textClear = await page.getByRole('textbox', { name: '请选择' }).inputValue()
   await expect(textClear).toEqual('')
-  const medium = page.locator('.tiny-cascader--medium')
-  await expect(medium).toBeVisible()
 })
diff --git a/examples/sites/demos/pc/app/cascader/clearable.vue b/examples/sites/demos/pc/app/cascader/clearable.vue
@@ -1,13 +1,5 @@
 <template>
-  <tiny-cascader
-    v-model="value"
-    :options="options"
-    clearable
-    separator="+"
-    size="medium"
-    popper-class="custom-class"
-    :popper-append-to-body="false"
-  ></tiny-cascader>
+  <tiny-cascader v-model="value" :options="options" clearable separator="+"></tiny-cascader>
 </template>
 
 <script>

diff --git a/examples/sites/demos/pc/app/cascader/collapse-tags-composition-api.vue b/examples/sites/demos/pc/app/cascader/collapse-tags-composition-api.vue
@@ -1,5 +1,5 @@
 <template>
-  <tiny-cascader v-model="value" :options="options" :props="props" collapse-tags clearable></tiny-cascader>
+  <tiny-cascader v-model="value" :options="options" :props="props" collapse-tags></tiny-cascader>
 </template>
 
 <script setup>

diff --git a/examples/sites/demos/pc/app/cascader/collapse-tags.vue b/examples/sites/demos/pc/app/cascader/collapse-tags.vue
@@ -1,5 +1,5 @@
 <template>
-  <tiny-cascader v-model="value" :options="options" :props="props" collapse-tags clearable></tiny-cascader>
+  <tiny-cascader v-model="value" :options="options" :props="props" collapse-tags></tiny-cascader>
 </template>
 
 <script>

diff --git a/examples/sites/demos/pc/app/cascader/disabled-items-composition-api.vue b/examples/sites/demos/pc/app/cascader/disabled-items-composition-api.vue
@@ -1,7 +1,9 @@
 <template>
-  <tiny-cascader :options="optionsDis"></tiny-cascader>
+  <div class="cascader-demo-disabled">
+    <tiny-cascader :options="optionsDis"></tiny-cascader>
+    <tiny-cascader :options="optionsDis" disabled></tiny-cascader>
+  </div>
 </template>
-
 <script setup>
 import { ref } from 'vue'
 import { Cascader as TinyCascader } from '@opentiny/vue'
@@ -202,3 +204,9 @@ const optionsDis = ref([
   }
 ])
 </script>
+
+<style scoped>
+.cascader-demo-disabled > :not(:last-child){
+  margin-right: 12px;
+}
+</style>