docs: update docs (#4466)

* chore: fixed known issues with form components

* docs: add vben form doc

Author: anncwb

apps/web-antd/src/adapter/form.ts

@@ -27,13 +27,13 @@ import {
   Select,
   Space,
   Switch,
+  Textarea,
   TimePicker,
   TreeSelect,
   Upload,
 } from 'ant-design-vue';
 
-// 业务表单组件适配
-
+// 这里需要自行根据业务组件库进行适配，需要用到的组件都需要在这里类型说明
 export type FormComponentType =
   | 'AutoComplete'
   | 'Checkbox'
@@ -51,6 +51,7 @@ export type FormComponentType =
   | 'Select'
   | 'Space'
   | 'Switch'
+  | 'Textarea'
   | 'TimePicker'
   | 'TreeSelect'
   | 'Upload'
@@ -83,12 +84,16 @@ setupVbenForm<FormComponentType>({
     Select,
     Space,
     Switch,
+    Textarea,
     TimePicker,
     TreeSelect,
     Upload,
   },
   config: {
+    // ant design vue组件库默认都是 v-model:value
     baseModelPropName: 'value',
+
+    // 一些组件是 v-model:checked 或者 v-model:fileList
     modelPropNameMap: {
       Checkbox: 'checked',
       Radio: 'checked',
@@ -97,12 +102,14 @@ setupVbenForm<FormComponentType>({
     },
   },
   defineRules: {
+    // 输入项目必填国际化适配
     required: (value, _params, ctx) => {
-      if ((!value && value !== 0) || value.length === 0) {
+      if (value === undefined || value === null || value.length === 0) {
         return $t('formRules.required', [ctx.label]);
       }
       return true;
     },
+    // 选择项目必填国际化适配
     selectRequired: (value, _params, ctx) => {
       if (value === undefined || value === null) {
         return $t('formRules.selectRequired', [ctx.label]);

apps/web-ele/src/adapter/form.ts

@@ -73,7 +73,7 @@ setupVbenForm<FormComponentType>({
   },
   defineRules: {
     required: (value, _params, ctx) => {
-      if ((!value && value !== 0) || value.length === 0) {
+      if (value === undefined || value === null || value.length === 0) {
         return $t('formRules.required', [ctx.label]);
       }
       return true;

apps/web-naive/src/adapter/form.ts

@@ -82,7 +82,7 @@ setupVbenForm<FormComponentType>({
   },
   defineRules: {
     required: (value, _params, ctx) => {
-      if ((!value && value !== 0) || value.length === 0) {
+      if (value === undefined || value === null || value.length === 0) {
         return $t('formRules.required', [ctx.label]);
       }
       return true;

docs/.vitepress/components/demo-preview.vue

@@ -24,14 +24,16 @@ const parsedFiles = computed(() => {
       class="not-prose relative w-full overflow-x-auto rounded-t-lg px-4 py-6"
     >
       <div class="flex w-full max-w-[700px] px-2">
-        <slot v-if="parsedFiles.length > 0"></slot>
-        <div v-else class="text-destructive text-sm">
-          <span class="bg-destructive text-foreground rounded-sm px-1 py-1">
-            ERROR:
-          </span>
-          The preview directory does not exist. Please check the 'dir'
-          parameter.
-        </div>
+        <ClientOnly>
+          <slot v-if="parsedFiles.length > 0"></slot>
+          <div v-else class="text-destructive text-sm">
+            <span class="bg-destructive text-foreground rounded-sm px-1 py-1">
+              ERROR:
+            </span>
+            The preview directory does not exist. Please check the 'dir'
+            parameter.
+          </div>
+        </ClientOnly>
       </div>
     </div>
     <PreviewGroup v-if="parsedFiles.length > 0" :files="parsedFiles">

docs/.vitepress/config/zh.mts

@@ -154,15 +154,19 @@ function sidebarComponents(): DefaultTheme.SidebarItem[] {
       items: [
         {
           link: 'common-ui/vben-modal',
-          text: 'Vben Modal 模态框',
+          text: 'Modal 模态框',
         },
         {
           link: 'common-ui/vben-drawer',
-          text: 'Vben Drawer 抽屉',
+          text: 'Drawer 抽屉',
         },
         {
           link: 'common-ui/vben-form',
-          text: 'Vben Form 表单',
+          text: 'Form 表单',
+        },
+        {
+          link: 'common-ui/vben-count-to-animator',
+          text: 'CountToAnimator 数字动画',
         },
       ],
     },

docs/.vitepress/theme/components/site-layout.vue

@@ -1,30 +1,92 @@
 <script lang="ts" setup>
-import { nextTick, onMounted, watch } from 'vue';
+import {
+  computed,
+  nextTick,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  watch,
+} from 'vue';
 
+// import { useAntdDesignTokens } from '@vben/hooks';
+// import { initPreferences } from '@vben/preferences';
+
+import { ConfigProvider, theme } from 'ant-design-vue';
 import mediumZoom from 'medium-zoom';
 import { useRoute } from 'vitepress';
 import DefaultTheme from 'vitepress/theme';
 
 const { Layout } = DefaultTheme;
 const route = useRoute();
+// const { tokens } = useAntdDesignTokens();
 
 const initZoom = () => {
   // mediumZoom('[data-zoomable]', { background: 'var(--vp-c-bg)' });
   mediumZoom('.VPContent img', { background: 'var(--vp-c-bg)' });
 };
 
+const isDark = ref(true);
+
 watch(
   () => route.path,
   () => nextTick(() => initZoom()),
 );
 
+// initPreferences({
+//   namespace: 'docs',
+// });
+
 onMounted(() => {
   initZoom();
 });
+
+// 使用该函数
+const observer = watchDarkModeChange((dark) => {
+  isDark.value = dark;
+});
+
+onBeforeUnmount(() => {
+  observer?.disconnect();
+});
+
+function watchDarkModeChange(callback: (isDark: boolean) => void) {
+  if (typeof window === 'undefined') {
+    return;
+  }
+  const htmlElement = document.documentElement;
+
+  const observer = new MutationObserver(() => {
+    const isDark = htmlElement.classList.contains('dark');
+    callback(isDark);
+  });
+
+  observer.observe(htmlElement, {
+    attributeFilter: ['class'],
+    attributes: true,
+  });
+
+  const initialIsDark = htmlElement.classList.contains('dark');
+  callback(initialIsDark);
+
+  return observer;
+}
+
+const tokenTheme = computed(() => {
+  const algorithm = isDark.value
+    ? [theme.darkAlgorithm]
+    : [theme.defaultAlgorithm];
+
+  return {
+    algorithm,
+    // token: tokens,
+  };
+});
 </script>
 
 <template>
-  <Layout />
+  <ConfigProvider :theme="tokenTheme">
+    <Layout />
+  </ConfigProvider>
 </template>
 
 <style>

docs/.vitepress/theme/styles/base.css

@@ -5,3 +5,7 @@ html.dark {
 .dark .VPContent {
   /* background-color: #14161a; */
 }
+
+.form-valid-error p {
+  margin: 0;
+}

docs/package.json

@@ -7,10 +7,17 @@
     "dev": "vitepress dev",
     "docs:preview": "vitepress preview"
   },
+  "imports": {
+    "#/*": "./src/_env/*"
+  },
   "dependencies": {
     "@vben-core/shadcn-ui": "workspace:*",
     "@vben/common-ui": "workspace:*",
+    "@vben/hooks": "workspace:*",
+    "@vben/locales": "workspace:*",
+    "@vben/preferences": "workspace:*",
     "@vben/styles": "workspace:*",
+    "ant-design-vue": "catalog:",
     "lucide-vue-next": "catalog:",
     "medium-zoom": "catalog:",
     "radix-vue": "catalog:",

docs/src/_env/adapter/form.ts

@@ -0,0 +1,127 @@
+import type {
+  BaseFormComponentType,
+  VbenFormSchema as FormSchema,
+  VbenFormProps,
+} from '@vben/common-ui';
+
+import { h } from 'vue';
+
+import { setupVbenForm, useVbenForm as useForm, z } from '@vben/common-ui';
+import { $t } from '@vben/locales';
+
+import {
+  AutoComplete,
+  Button,
+  Checkbox,
+  CheckboxGroup,
+  DatePicker,
+  Divider,
+  Input,
+  InputNumber,
+  InputPassword,
+  Mentions,
+  Radio,
+  RadioGroup,
+  RangePicker,
+  Rate,
+  Select,
+  Space,
+  Switch,
+  Textarea,
+  TimePicker,
+  TreeSelect,
+  Upload,
+} from 'ant-design-vue';
+
+// 这里需要自行根据业务组件库进行适配，需要用到的组件都需要在这里类型说明
+export type FormComponentType =
+  | 'AutoComplete'
+  | 'Checkbox'
+  | 'CheckboxGroup'
+  | 'DatePicker'
+  | 'Divider'
+  | 'Input'
+  | 'InputNumber'
+  | 'InputPassword'
+  | 'Mentions'
+  | 'Radio'
+  | 'RadioGroup'
+  | 'RangePicker'
+  | 'Rate'
+  | 'Select'
+  | 'Space'
+  | 'Switch'
+  | 'Textarea'
+  | 'TimePicker'
+  | 'TreeSelect'
+  | 'Upload'
+  | BaseFormComponentType;
+
+// 初始化表单组件，并注册到form组件内部
+setupVbenForm<FormComponentType>({
+  components: {
+    AutoComplete,
+    Checkbox,
+    CheckboxGroup,
+    DatePicker,
+    // 自定义默认的重置按钮
+    DefaultResetActionButton: (props, { attrs, slots }) => {
+      return h(Button, { ...props, attrs, type: 'default' }, slots);
+    },
+    // 自定义默认的提交按钮
+    DefaultSubmitActionButton: (props, { attrs, slots }) => {
+      return h(Button, { ...props, attrs, type: 'primary' }, slots);
+    },
+    Divider,
+    Input,
+    InputNumber,
+    InputPassword,
+    Mentions,
+    Radio,
+    RadioGroup,
+    RangePicker,
+    Rate,
+    Select,
+    Space,
+    Switch,
+    Textarea,
+    TimePicker,
+    TreeSelect,
+    Upload,
+  },
+  config: {
+    // ant design vue组件库默认都是 v-model:value
+    baseModelPropName: 'value',
+
+    // 一些组件是 v-model:checked 或者 v-model:fileList
+    modelPropNameMap: {
+      Checkbox: 'checked',
+      Radio: 'checked',
+      Switch: 'checked',
+      Upload: 'fileList',
+    },
+  },
+  defineRules: {
+    // 输入项目必填国际化适配
+    required: (value, _params, ctx) => {
+      if (value === undefined || value === null || value.length === 0) {
+        return $t('formRules.required', [ctx.label]);
+      }
+      return true;
+    },
+    // 选择项目必填国际化适配
+    selectRequired: (value, _params, ctx) => {
+      if (value === undefined || value === null) {
+        return $t('formRules.selectRequired', [ctx.label]);
+      }
+      return true;
+    },
+  },
+});
+
+const useVbenForm = useForm<FormComponentType>;
+
+export { useVbenForm, z };
+
+export type VbenFormSchema = FormSchema<FormComponentType>;
+export type { VbenFormProps };

docs/src/_env/adapter/index.ts

@@ -0,0 +1 @@
+export * from './form';