From aef96eda64f7db52a8270c325d9bba9a60be6e74 Mon Sep 17 00:00:00 2001
From: gimmyhehe <975402925@qq.com>
Date: Thu, 14 Dec 2023 15:40:01 +0800
Subject: [PATCH] docs(sites): [pager, form] optimize docs and demos (#1135)

---
 .../pc/app/form/events-composition-api.vue    | 46 ++++++++++++++++
 .../sites/demos/pc/app/form/events.spec.ts    | 12 +++++
 examples/sites/demos/pc/app/form/events.vue   | 52 +++++++++++++++++++
 .../form-validate-field-composition-api.vue   | 27 +++++-----
 .../pc/app/form/form-validate-field.spec.ts   | 11 +++-
 .../demos/pc/app/form/form-validate-field.vue | 21 ++++----
 .../form/form-validation-composition-api.vue  |  7 ++-
 .../demos/pc/app/form/form-validation.vue     |  6 ++-
 .../form/label-position-composition-api.vue   |  2 +-
 .../demos/pc/app/form/label-position.vue      |  2 +-
 .../sites/demos/pc/app/form/webdoc/form.js    | 26 +++++++---
 ...popper-append-to-body-composition-api.vue} |  0
 ....spec.ts => popper-append-to-body.spec.ts} |  0
 ...-to-body.vue => popper-append-to-body.vue} |  0
 .../sites/demos/pc/app/pager/webdoc/pager.js  |  4 +-
 15 files changed, 174 insertions(+), 42 deletions(-)
 create mode 100644 examples/sites/demos/pc/app/form/events-composition-api.vue
 create mode 100644 examples/sites/demos/pc/app/form/events.spec.ts
 create mode 100644 examples/sites/demos/pc/app/form/events.vue
 rename examples/sites/demos/pc/app/pager/{page-append-to-body-composition-api.vue => popper-append-to-body-composition-api.vue} (100%)
 rename examples/sites/demos/pc/app/pager/{page-append-to-body.spec.ts => popper-append-to-body.spec.ts} (100%)
 rename examples/sites/demos/pc/app/pager/{page-append-to-body.vue => popper-append-to-body.vue} (100%)

diff --git a/examples/sites/demos/pc/app/form/events-composition-api.vue b/examples/sites/demos/pc/app/form/events-composition-api.vue
new file mode 100644
index 000000000..7ba308387
--- /dev/null
+++ b/examples/sites/demos/pc/app/form/events-composition-api.vue
@@ -0,0 +1,46 @@
+<template>
+  <div class="demo-form">
+    <tiny-form ref="formRef" :model="createData" @validate="validate">
+      <tiny-form-item label="姓名" prop="name" :rules="{ required: true, messages: '必填', trigger: 'blur' }">
+        <tiny-input v-model="createData.name"></tiny-input>
+      </tiny-form-item>
+      <tiny-form-item label="昵称">
+        <tiny-input v-model="createData.nickname"></tiny-input>
+      </tiny-form-item>
+      <tiny-form-item>
+        <tiny-button @click="submit" type="primary">提交</tiny-button>
+      </tiny-form-item>
+    </tiny-form>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import {
+  Form as TinyForm,
+  FormItem as TinyFormItem,
+  Input as TinyInput,
+  Button as TinyButton,
+  Modal as TinyModal
+} from '@opentiny/vue'
+
+const createData = ref({
+  name: '',
+  nickname: ''
+})
+const formRef = ref()
+function validate() {
+  TinyModal.message({ message: '校验事件触发了', status: 'info' })
+}
+function submit() {
+  formRef.value.validate(() => {
+    // empty
+  })
+}
+</script>
+
+<style scoped>
+.demo-form {
+  width: 380px;
+}
+</style>
diff --git a/examples/sites/demos/pc/app/form/events.spec.ts b/examples/sites/demos/pc/app/form/events.spec.ts
new file mode 100644
index 000000000..d1bbcff21
--- /dev/null
+++ b/examples/sites/demos/pc/app/form/events.spec.ts
@@ -0,0 +1,12 @@
+import { test, expect } from '@playwright/test'
+
+test('表单事件', async ({ page }) => {
+  page.on('pageerror', (exception) => expect(exception).toBeNull())
+  await page.goto('form#events')
+
+  const demo = page.locator('#events')
+  const messageModal = page.locator('.tiny-modal.active')
+
+  await demo.getByRole('button', { name: '提交' }).click()
+  await expect(messageModal).toHaveText('校验事件触发了')
+})
diff --git a/examples/sites/demos/pc/app/form/events.vue b/examples/sites/demos/pc/app/form/events.vue
new file mode 100644
index 000000000..85bb47213
--- /dev/null
+++ b/examples/sites/demos/pc/app/form/events.vue
@@ -0,0 +1,52 @@
+<template>
+  <div class="demo-form">
+    <tiny-form ref="form" :model="createData" @validate="validate">
+      <tiny-form-item label="姓名" prop="name" :rules="{ required: true, messages: '必填', trigger: 'blur' }">
+        <tiny-input v-model="createData.name"></tiny-input>
+      </tiny-form-item>
+      <tiny-form-item label="昵称">
+        <tiny-input v-model="createData.nickname"></tiny-input>
+      </tiny-form-item>
+      <tiny-form-item>
+        <tiny-button @click="submit" type="primary">提交</tiny-button>
+      </tiny-form-item>
+    </tiny-form>
+  </div>
+</template>
+
+<script>
+import { Form, FormItem, Input, Button, Modal as TinyModal } from '@opentiny/vue'
+
+export default {
+  components: {
+    TinyForm: Form,
+    TinyFormItem: FormItem,
+    TinyInput: Input,
+    TinyButton: Button
+  },
+  data() {
+    return {
+      createData: {
+        name: '',
+        nickname: ''
+      }
+    }
+  },
+  methods: {
+    validate() {
+      TinyModal.message({ message: '校验事件触发了', status: 'info' })
+    },
+    submit() {
+      this.$refs.form.validate(() => {
+        // empty
+      })
+    }
+  }
+}
+</script>
+
+<style scoped>
+.demo-form {
+  width: 380px;
+}
+</style>
diff --git a/examples/sites/demos/pc/app/form/form-validate-field-composition-api.vue b/examples/sites/demos/pc/app/form/form-validate-field-composition-api.vue
index 90aa5433c..093afc214 100644
--- a/examples/sites/demos/pc/app/form/form-validate-field-composition-api.vue
+++ b/examples/sites/demos/pc/app/form/form-validate-field-composition-api.vue
@@ -1,25 +1,19 @@
 <template>
   <div class="demo-form">
-    <tiny-form
-      ref="ruleFormRef"
-      hide-required-asterisk
-      :model="createData"
-      :rules="rules"
-      label-width="100px"
-      show-message
-    >
-      <tiny-form-item label="姓名" prop="users" required>
+    <tiny-form ref="ruleFormRef" :model="createData" :rules="rules">
+      <tiny-form-item label="姓名" prop="users">
         <tiny-input v-model="createData.users"></tiny-input>
       </tiny-form-item>
-      <tiny-form-item label="日期" prop="datepicker">
+      <tiny-form-item label="日期" prop="datepicker" ref="dateRef">
         <tiny-date-picker v-model="createData.datepicker"></tiny-date-picker>
       </tiny-form-item>
       <tiny-form-item label="URL" prop="url">
         <tiny-input v-model="createData.url"></tiny-input>
       </tiny-form-item>
       <tiny-form-item>
-        <tiny-button type="primary" @click="validateField"> 校验特定字段 </tiny-button>
-        <tiny-button type="primary" @click="clearValidate"> 移除特定字段校验 </tiny-button>
+        <tiny-button type="primary" @click="validateField"> 校验 </tiny-button>
+        <tiny-button type="primary" @click="clearValidate"> 移除校验 </tiny-button>
+        <tiny-button type="primary" @click="resetField"> 重置日期 </tiny-button>
       </tiny-form-item>
     </tiny-form>
   </div>
@@ -37,6 +31,7 @@ import {
 } from '@opentiny/vue'
 
 const ruleFormRef = ref()
+const dateRef = ref()
 
 const createData = reactive({
   users: '',
@@ -48,7 +43,7 @@ const rules = ref({
     { required: true, message: '必填', trigger: 'blur' },
     { min: 2, max: 11, message: '长度必须不小于2', trigger: ['change', 'blur'] }
   ],
-  datepicker: { type: 'date' },
+  datepicker: { type: 'date', required: true },
   url: { type: 'url', required: true }
 })
 
@@ -56,6 +51,10 @@ function clearValidate() {
   ruleFormRef.value.clearValidate(['url', 'datepicker'])
 }
 
+function resetField() {
+  dateRef.value.resetField()
+}
+
 async function validateField() {
   const errArray = []
   await ruleFormRef.value.validateField(['url', 'datepicker'], (errMsg, fieldConfig) => {
@@ -64,7 +63,7 @@ async function validateField() {
     }
   })
   if (errArray.length > 0) {
-    console.log(errArray)
+    // empty
   } else {
     Modal.alert('日期和url通过校验')
   }
diff --git a/examples/sites/demos/pc/app/form/form-validate-field.spec.ts b/examples/sites/demos/pc/app/form/form-validate-field.spec.ts
index 2a884694e..b202135d7 100644
--- a/examples/sites/demos/pc/app/form/form-validate-field.spec.ts
+++ b/examples/sites/demos/pc/app/form/form-validate-field.spec.ts
@@ -6,11 +6,18 @@ test('特定表单项校验', async ({ page }) => {
 
   const demo = page.locator('#form-validate-field')
   const getTooltipByText = (text: string) => page.locator('.tiny-tooltip').getByText(text)
+  const validBtn = demo.getByRole('button', { name: '校验' }).first()
 
-  await demo.getByRole('button', { name: '校验特定字段' }).click()
+  await validBtn.click()
   await expect(getTooltipByText('不符合规则的日期格式')).toBeVisible()
   await expect(getTooltipByText('必填')).toBeVisible()
-  await demo.getByRole('button', { name: '移除特定字段校验' }).click()
+  await demo.getByRole('button', { name: '移除校验' }).click()
   await expect(getTooltipByText('不符合规则的日期格式')).not.toBeVisible()
   await expect(getTooltipByText('必填')).not.toBeVisible()
+  await validBtn.click()
+  await expect(getTooltipByText('不符合规则的日期格式')).toBeVisible()
+  await expect(getTooltipByText('必填')).toBeVisible()
+  await demo.getByRole('button', { name: '重置日期' }).click()
+  await expect(getTooltipByText('不符合规则的日期格式')).not.toBeVisible()
+  await expect(getTooltipByText('必填')).toBeVisible()
 })
diff --git a/examples/sites/demos/pc/app/form/form-validate-field.vue b/examples/sites/demos/pc/app/form/form-validate-field.vue
index 59f174c53..c2ede97fa 100644
--- a/examples/sites/demos/pc/app/form/form-validate-field.vue
+++ b/examples/sites/demos/pc/app/form/form-validate-field.vue
@@ -1,25 +1,19 @@
 <template>
   <div class="demo-form">
-    <tiny-form
-      ref="ruleFormRef"
-      hide-required-asterisk
-      :model="createData"
-      :rules="rules"
-      label-width="100px"
-      show-message
-    >
-      <tiny-form-item label="姓名" prop="users" required>
+    <tiny-form ref="ruleFormRef" :model="createData" :rules="rules">
+      <tiny-form-item label="姓名" prop="users">
         <tiny-input v-model="createData.users"></tiny-input>
       </tiny-form-item>
-      <tiny-form-item label="日期" prop="datepicker">
+      <tiny-form-item label="日期" prop="datepicker" ref="dateRef">
         <tiny-date-picker v-model="createData.datepicker"></tiny-date-picker>
       </tiny-form-item>
       <tiny-form-item label="URL" prop="url">
         <tiny-input v-model="createData.url"></tiny-input>
       </tiny-form-item>
       <tiny-form-item>
-        <tiny-button type="primary" @click="validateField"> 校验特定字段 </tiny-button>
-        <tiny-button type="primary" @click="clearValidate"> 移除特定字段校验 </tiny-button>
+        <tiny-button type="primary" @click="validateField"> 校验 </tiny-button>
+        <tiny-button type="primary" @click="clearValidate"> 移除校验 </tiny-button>
+        <tiny-button type="primary" @click="resetField"> 重置日期 </tiny-button>
       </tiny-form-item>
     </tiny-form>
   </div>
@@ -69,6 +63,9 @@ export default {
     },
     clearValidate() {
       this.$refs.ruleFormRef.clearValidate(['url', 'datepicker'])
+    },
+    resetField() {
+      this.$refs.dateRef.resetField()
     }
   }
 }
diff --git a/examples/sites/demos/pc/app/form/form-validation-composition-api.vue b/examples/sites/demos/pc/app/form/form-validation-composition-api.vue
index 6614dfc2b..ba5fc78a3 100644
--- a/examples/sites/demos/pc/app/form/form-validation-composition-api.vue
+++ b/examples/sites/demos/pc/app/form/form-validation-composition-api.vue
@@ -29,7 +29,8 @@
         <tiny-button type="primary" @click="validType === 'callback' ? handleSubmit() : handleSubmitPromise()">
           提交
         </tiny-button>
-        <tiny-button type="success" @click="clearFormValid"> 移除校验 </tiny-button>
+        <tiny-button type="primary" @click="clearFormValid"> 移除校验 </tiny-button>
+        <tiny-button type="primary" @click="resetForm"> 重置表单 </tiny-button>
       </tiny-form-item>
     </tiny-form>
   </div>
@@ -132,6 +133,10 @@ function handleSubmitPromise() {
 function clearFormValid() {
   ruleFormRef.value.clearValidate()
 }
+
+function resetForm() {
+  ruleFormRef.value.resetFields()
+}
 </script>
 
 <style scoped>
diff --git a/examples/sites/demos/pc/app/form/form-validation.vue b/examples/sites/demos/pc/app/form/form-validation.vue
index 1a86735a5..995d0bf06 100644
--- a/examples/sites/demos/pc/app/form/form-validation.vue
+++ b/examples/sites/demos/pc/app/form/form-validation.vue
@@ -29,7 +29,8 @@
         <tiny-button type="primary" @click="validType === 'callback' ? handleSubmit() : handleSubmitPromise()">
           提交
         </tiny-button>
-        <tiny-button type="success" @click="clearFormValid"> 移除校验 </tiny-button>
+        <tiny-button type="primary" @click="clearFormValid"> 移除校验 </tiny-button>
+        <tiny-button type="primary" @click="resetForm"> 重置表单 </tiny-button>
       </tiny-form-item>
     </tiny-form>
   </div>
@@ -140,6 +141,9 @@ export default {
     },
     clearFormValid() {
       this.$refs.ruleFormRef.clearValidate()
+    },
+    resetForm() {
+      this.$refs.ruleFormRef.resetFields()
     }
   }
 }
diff --git a/examples/sites/demos/pc/app/form/label-position-composition-api.vue b/examples/sites/demos/pc/app/form/label-position-composition-api.vue
index dc90b8859..929862486 100644
--- a/examples/sites/demos/pc/app/form/label-position-composition-api.vue
+++ b/examples/sites/demos/pc/app/form/label-position-composition-api.vue
@@ -3,7 +3,7 @@
     <div class="title">
       标签位置： <tiny-button-group :data="labelPositionList" v-model="labelPositionValue"></tiny-button-group>
     </div>
-    <tiny-form ref="ruleFormRef" :model="createData" :label-position="labelPositionValue">
+    <tiny-form ref="ruleFormRef" :model="createData" :label-position="labelPositionValue" label-width="60px">
       <tiny-form-item label="用户名" prop="username">
         <tiny-input v-model="createData.username"></tiny-input>
       </tiny-form-item>
diff --git a/examples/sites/demos/pc/app/form/label-position.vue b/examples/sites/demos/pc/app/form/label-position.vue
index 54cca1a39..77f4e75b1 100644
--- a/examples/sites/demos/pc/app/form/label-position.vue
+++ b/examples/sites/demos/pc/app/form/label-position.vue
@@ -3,7 +3,7 @@
     <div class="title">
       标签位置： <tiny-button-group :data="labelPositionList" v-model="labelPositionValue"></tiny-button-group>
     </div>
-    <tiny-form ref="ruleFormRef" :model="createData" :label-position="labelPositionValue">
+    <tiny-form ref="ruleFormRef" :model="createData" :label-position="labelPositionValue" label-width="60px">
       <tiny-form-item label="用户名" prop="username">
         <tiny-input v-model="createData.username"></tiny-input>
       </tiny-form-item>
diff --git a/examples/sites/demos/pc/app/form/webdoc/form.js b/examples/sites/demos/pc/app/form/webdoc/form.js
index ab8df3e80..9532a70ae 100644
--- a/examples/sites/demos/pc/app/form/webdoc/form.js
+++ b/examples/sites/demos/pc/app/form/webdoc/form.js
@@ -60,9 +60,10 @@ export default {
       demoId: 'form-validation',
       name: { 'zh-CN': '表单校验、移除校验', 'en-US': 'Form Validation/Clear Validation' },
       desc: {
-        'zh-CN': `<p>通过 <code>rules</code> 设置校验规则， <code>rules</code> 的详情见 <a href="#IFormRules">IFormRules</a>
-          <br />
-          调用 <code>clearValidate</code> 方法移除表单项的校验结果。传入待移除的表单项的 <code>prop</code> 属性或者 <code>prop</code> 组成的数组，如不传则移除整个表单的校验结果。</p>`,
+        'zh-CN': `<p>通过 <code>rules</code> 设置校验规则，
+        调用 <code>clearValidate</code> 方法移除表单项的校验结果。传入待移除的表单项的 <code>prop</code> 属性或者 <code>prop</code> 组成的数组，如不传则移除整个表单的校验结果，
+        调用 <code>resetFields</code> 方法重置表单并移除校验结果。
+        </p>`,
         'en-US': `<p>Includes common verification rules such as mandatory fields, date, time, URL, and email. Use <code>trigger</code> to configure the mode of triggering the validation rule. If <code>change</code> is used, the validation is triggered when the value in the text box changes. If <code>blur</code> is used, the validation is triggered after the focus is lost. 
           <br />
           Use <code>clearValidate</code> method to clear the validation result. 
@@ -76,7 +77,7 @@ export default {
       'name': { 'zh-CN': '特定表单项校验', 'en-US': 'Form field Validation' },
       'desc': {
         'zh-CN':
-          '<p>通过 <code>validateField</code> 方法对特定表单项进行校验， <code>clearValidate</code> 方法移除特定表单项校验。</p>',
+          '<p>通过 <code>validateField</code> 方法对特定表单项进行校验， <code>clearValidate</code> 方法移除特定表单项校验， <code>resetField</code> 重置表单项并移除校验。</p>',
         'en-US':
           '<p>Verify specific form items using the <code>validateField</code> method, and remove specific form item validation using the <code>clearValidate</code> method.</p>'
       },
@@ -221,6 +222,15 @@ export default {
           'Set the <code>tip</code> type error prompt through <code>popper-options</code>. For example, when the parent element of the form is a scrolling element and the page scrolls, the prompt will be misaligned. Change the <code>bubbling</code> attribute Set to <code>true</code> to resolve this issue.'
       },
       codeFiles: ['popper-options.vue']
+    },
+    {
+      demoId: 'events',
+      name: { 'zh-CN': '表单事件', 'en-US': 'Form events' },
+      desc: {
+        'zh-CN': '<p>任一表单项被校验后触发 <code>validate</code>事件</p>',
+        'en-US': 'The <code>validate</code> event is triggered after any form item is verified.'
+      },
+      codeFiles: ['events.vue']
     }
   ],
   apis: [
@@ -498,7 +508,7 @@ export default {
             'zh-CN': '任一表单项被校验后触发',
             'en-US': 'Triggered after any form item is verified'
           },
-          demoId: 'form-validation'
+          demoId: 'events'
         }
       ]
     },
@@ -599,7 +609,7 @@ export default {
             'zh-CN': '是否显示校验错误信息',
             'en-US': 'Whether to display verification error information'
           },
-          demoId: 'form-validation'
+          demoId: 'novalid-tip'
         },
         {
           name: 'size',
@@ -641,7 +651,7 @@ export default {
             'zh-CN': '指定校验提示框显示的位置',
             'en-US': 'Specify the position where the verification dialog box is displayed'
           },
-          demoId: 'form-validation'
+          demoId: 'validation-position'
         },
         {
           name: 'validate-type',
@@ -695,7 +705,7 @@ export default {
             'zh-CN': '对该表单项进行重置，将其值重置为初始值并移除校验结果',
             'en-US': 'Reset the table item to the initial value and remove the verification result.'
           },
-          demoId: 'form-validation'
+          demoId: 'form-validate-field'
         }
       ],
       'events': []
diff --git a/examples/sites/demos/pc/app/pager/page-append-to-body-composition-api.vue b/examples/sites/demos/pc/app/pager/popper-append-to-body-composition-api.vue
similarity index 100%
rename from examples/sites/demos/pc/app/pager/page-append-to-body-composition-api.vue
rename to examples/sites/demos/pc/app/pager/popper-append-to-body-composition-api.vue
diff --git a/examples/sites/demos/pc/app/pager/page-append-to-body.spec.ts b/examples/sites/demos/pc/app/pager/popper-append-to-body.spec.ts
similarity index 100%
rename from examples/sites/demos/pc/app/pager/page-append-to-body.spec.ts
rename to examples/sites/demos/pc/app/pager/popper-append-to-body.spec.ts
diff --git a/examples/sites/demos/pc/app/pager/page-append-to-body.vue b/examples/sites/demos/pc/app/pager/popper-append-to-body.vue
similarity index 100%
rename from examples/sites/demos/pc/app/pager/page-append-to-body.vue
rename to examples/sites/demos/pc/app/pager/popper-append-to-body.vue
diff --git a/examples/sites/demos/pc/app/pager/webdoc/pager.js b/examples/sites/demos/pc/app/pager/webdoc/pager.js
index c2d6c0827..0f18c2677 100644
--- a/examples/sites/demos/pc/app/pager/webdoc/pager.js
+++ b/examples/sites/demos/pc/app/pager/webdoc/pager.js
@@ -88,7 +88,7 @@ export default {
         'en-US':
           'Indicates whether to add an element in the <p> <code>popper-append-to-body</code> paging drop-down list box to the body element node.</p>'
       },
-      'codeFiles': ['page-append-to-body.vue']
+      'codeFiles': ['popper-append-to-body.vue']
     },
     {
       'demoId': 'popper-class',
@@ -338,7 +338,7 @@ export default {
             'en-US':
               'Whether to insert the pop-up box into the body element. You can set this attribute to false (refer to the select component)'
           },
-          'demoId': 'page-append-to-body'
+          'demoId': 'popper-append-to-body'
         },
         {
           'name': 'popper-class',