Merge branch 'main' of https://github.com/vbenjs/vue-vben-admin into dev

apps/web-antd/src/adapter/component/index.ts

@@ -131,7 +131,13 @@ async function initComponentAdapter() {
     IconPicker: (props, { attrs, slots }) => {
       return h(
         IconPicker,
-        { iconSlot: 'addonAfter', inputComponent: Input, ...props, ...attrs },
+        {
+          iconSlot: 'addonAfter',
+          inputComponent: Input,
+          modelValueProp: 'value',
+          ...props,
+          ...attrs,
+        },
         slots,
       );
     },

apps/web-antd/src/bootstrap.ts

@@ -1,7 +1,7 @@
 import { createApp, watchEffect } from 'vue';
 
 import { registerAccessDirective } from '@vben/access';
-import { initTippy } from '@vben/common-ui';
+import { initTippy, registerLoadingDirective } from '@vben/common-ui';
 import { MotionPlugin } from '@vben/plugins/motion';
 import { preferences } from '@vben/preferences';
 import { initStores } from '@vben/stores';
@@ -34,6 +34,11 @@ async function bootstrap(namespace: string) {
 
   // 全局组件
   setupGlobalComponent(app);
+  // 注册v-loading指令
+  registerLoadingDirective(app, {
+    loading: 'loading', // 在这里可以自定义指令名称，也可以明确提供false表示不注册这个指令
+    spinning: 'spinning',
+  });
 
   // 国际化 i18n 配置
   await setupI18n(app);

docs/src/components/common-ui/vben-count-to-animator.md

@@ -42,11 +42,18 @@ outline: deep
 | transition | 动画效果       | `string`  | `linear` |
 | decimals   | 保留小数点位数 | `number`  | `0`      |
 
+### Events
+
+| 事件名         | 描述           | 类型           |
+| -------------- | -------------- | -------------- |
+| started        | 动画已开始     | `()=>void`     |
+| finished       | 动画已结束     | `()=>void`     |
+| ~~onStarted~~  | ~~动画已开始~~ | ~~`()=>void`~~ |
+| ~~onFinished~~ | ~~动画已结束~~ | ~~`()=>void`~~ |
+
 ### Methods
 
-以下事件，只有在 `useVbenModal({onCancel:()=>{}})` 中传入才会生效。
+| 方法名 | 描述         | 类型       |
-
-| 事件名 | 描述         | 类型       |
 | ------ | ------------ | ---------- |
 | start  | 开始执行动画 | `()=>void` |
 | reset  | 重置         | `()=>void` |

docs/src/components/common-ui/vben-form.md

@@ -445,9 +445,9 @@ export interface FormSchema<
   /** 字段名，也作为自定义插槽的名称 */
   fieldName: string;
   /** 帮助信息 */
-  help?: string;
+  help?: CustomRenderType;
-  /** 表单项 */
+  /** 表单的标签（如果是一个string，会用于默认必选规则的消息提示） */
-  label?: string;
+  label?: CustomRenderType;
   /** 自定义组件内部渲染  */
   renderComponentContent?: RenderComponentContentType;
   /** 字段规则 */

docs/src/guide/essentials/settings.md

@@ -538,4 +538,6 @@ interface Preferences {
 
 - `overridesPreferences`方法只需要覆盖项目中的一部分配置，不需要的配置不用覆盖，会自动使用默认配置。
 - 任何配置项都可以覆盖，只需要在`overridesPreferences`方法内覆盖即可，不要修改默认配置文件。
-- 更改配置后请清空缓存，否则可能不生效。:::
+- 更改配置后请清空缓存，否则可能不生效。
+
+:::

packages/@core/base/icons/src/lucide.ts

@@ -1,9 +1,7 @@
 export {
   ArrowDown,
   ArrowLeft,
-  ArrowLeftFromLine as MdiMenuOpen,
   ArrowLeftToLine,
-  ArrowRightFromLine as MdiMenuClose,
   ArrowRightLeft,
   ArrowRightToLine,
   ArrowUp,
@@ -16,6 +14,8 @@ export {
   ChevronRight,
   ChevronsLeft,
   ChevronsRight,
+  Circle,
+  CircleCheckBig,
   CircleHelp,
   Copy,
   CornerDownLeft,
@@ -29,6 +29,7 @@ export {
   Github,
   Grip,
   GripVertical,
+  Menu as IconDefault,
   Info,
   InspectionPanel,
   Languages,
@@ -37,7 +38,8 @@ export {
   LogOut,
   MailCheck,
   Maximize,
-  Menu as IconDefault,
+  ArrowRightFromLine as MdiMenuClose,
+  ArrowLeftFromLine as MdiMenuOpen,
   Menu,
   Minimize,
   Minimize2,

packages/@core/ui-kit/form-ui/src/form-render/form-field.vue

@@ -193,7 +193,7 @@ const fieldProps = computed(() => {
   const rules = fieldRules.value;
   return {
     keepValue: true,
-    label,
+    label: isString(label) ? label : '',
     ...(rules ? { rules } : {}),
     ...(formFieldProps as Record<string, any>),
   };
@@ -285,7 +285,7 @@ function autofocus() {
         'pb-6': !compact,
         'pb-2': compact,
       }"
-      class="flex"
+      class="relative flex"
       v-bind="$attrs"
     >
       <FormLabel
@@ -301,59 +301,64 @@ function autofocus() {
           )
         "
         :help="help"
+        :colon="colon"
+        :label="label"
         :required="shouldRequired && !hideRequiredMark"
         :style="labelStyle"
       >
         <template v-if="label">
-          <span>{{ label }}</span>
+          <VbenRenderContent :content="label" />
-          <span v-if="colon" class="ml-[2px]">:</span>
         </template>
       </FormLabel>
-      <div :class="cn('relative flex w-full items-center', wrapperClass)">
+      <div class="w-full overflow-hidden">
-        <FormControl :class="cn(controlClass)">
+        <div :class="cn('relative flex w-full items-center', wrapperClass)">
-          <slot
+          <div class="flex-auto overflow-hidden p-[2px]">
-            v-bind="{
+            <FormControl :class="cn(controlClass)">
-              ...slotProps,
+              <slot
-              ...createComponentProps(slotProps),
+                v-bind="{
-              disabled: shouldDisabled,
+                  ...slotProps,
-              isInValid,
+                  ...createComponentProps(slotProps),
-            }"
+                  disabled: shouldDisabled,
-          >
-            <component
-              :is="FieldComponent"
-              ref="fieldComponentRef"
-              :class="{
-                'border-destructive focus:border-destructive hover:border-destructive/80 focus:shadow-[0_0_0_2px_rgba(255,38,5,0.06)]':
                   isInValid,
-              }"
+                }"
-              v-bind="createComponentProps(slotProps)"
-              :disabled="shouldDisabled"
-            >
-              <template
-                v-for="name in renderContentKey"
-                :key="name"
-                #[name]="renderSlotProps"
               >
-                <VbenRenderContent
+                <component
-                  :content="customContentRender[name]"
+                  :is="FieldComponent"
-                  v-bind="{ ...renderSlotProps, formContext: slotProps }"
+                  ref="fieldComponentRef"
-                />
+                  :class="{
-              </template>
+                    'border-destructive focus:border-destructive hover:border-destructive/80 focus:shadow-[0_0_0_2px_rgba(255,38,5,0.06)]':
-              <!-- <slot></slot> -->
+                      isInValid,
-            </component>
+                  }"
-          </slot>
+                  v-bind="createComponentProps(slotProps)"
-        </FormControl>
+                  :disabled="shouldDisabled"
-        <!-- 自定义后缀 -->
+                >
-        <div v-if="suffix" class="ml-1">
+                  <template
-          <VbenRenderContent :content="suffix" />
+                    v-for="name in renderContentKey"
+                    :key="name"
+                    #[name]="renderSlotProps"
+                  >
+                    <VbenRenderContent
+                      :content="customContentRender[name]"
+                      v-bind="{ ...renderSlotProps, formContext: slotProps }"
+                    />
+                  </template>
+                  <!-- <slot></slot> -->
+                </component>
+              </slot>
+            </FormControl>
+          </div>
+
+          <!-- 自定义后缀 -->
+          <div v-if="suffix" class="ml-1">
+            <VbenRenderContent :content="suffix" />
+          </div>
+          <FormDescription v-if="description" class="ml-1">
+            <VbenRenderContent :content="description" />
+          </FormDescription>
         </div>
 
-        <FormDescription v-if="description">
-          <VbenRenderContent :content="description" />
-        </FormDescription>
-
         <Transition name="slide-up">
-          <FormMessage class="absolute -bottom-[22px]" />
+          <FormMessage class="absolute bottom-1" />
         </Transition>
       </div>
     </FormItem>

packages/@core/ui-kit/form-ui/src/form-render/form-label.vue

@@ -1,10 +1,18 @@
 <script setup lang="ts">
-import { FormLabel, VbenHelpTooltip } from '@vben-core/shadcn-ui';
+import type { CustomRenderType } from '../types';
+
+import {
+  FormLabel,
+  VbenHelpTooltip,
+  VbenRenderContent,
+} from '@vben-core/shadcn-ui';
 import { cn } from '@vben-core/shared/utils';
 
 interface Props {
   class?: string;
-  help?: string;
+  colon?: boolean;
+  help?: CustomRenderType;
+  label?: CustomRenderType;
   required?: boolean;
 }
 
@@ -20,6 +28,8 @@ const props = defineProps<Props>();
       <span class="whitespace-pre-line">
         {{ help }}
       </span>
+      <VbenRenderContent :content="help" />
     </VbenHelpTooltip>
+    <span v-if="colon && label" class="ml-[2px]">:</span>
   </FormLabel>
 </template>

packages/@core/ui-kit/form-ui/src/types.ts

@@ -244,13 +244,13 @@ export interface FormSchema<
   /** 依赖 */
   dependencies?: FormItemDependencies;
   /** 描述 */
-  description?: string;
+  description?: CustomRenderType;
   /** 字段名 */
   fieldName: string;
   /** 帮助信息 */
-  help?: string;
+  help?: CustomRenderType;
   /** 表单项 */
-  label?: string;
+  label?: CustomRenderType;
   // 自定义组件内部渲染
   renderComponentContent?: RenderComponentContentType;
   /** 字段规则 */

packages/@core/ui-kit/shadcn-ui/src/components/button/button-group.vue

@@ -0,0 +1,98 @@
+<script lang="ts" setup>
+import { cn } from '@vben-core/shared/utils';
+
+defineOptions({ name: 'VbenButtonGroup' });
+
+withDefaults(
+  defineProps<{
+    border?: boolean;
+    gap?: number;
+    size?: 'large' | 'middle' | 'small';
+  }>(),
+  { border: false, gap: 0, size: 'middle' },
+);
+</script>
+<template>
+  <div
+    :class="
+      cn(
+        'vben-button-group rounded-md',
+        `size-${size}`,
+        gap ? 'with-gap' : 'no-gap',
+        $attrs.class as string,
+      )
+    "
+    :style="{ gap: gap ? `${gap}px` : '0px' }"
+  >
+    <slot></slot>
+  </div>
+</template>
+
+<style lang="scss" scoped>
+.vben-button-group {
+  display: inline-flex;
+
+  &.size-large :deep(button) {
+    height: 2.25rem;
+    padding: 0.5rem 0.75rem;
+    font-size: 0.875rem;
+    line-height: 1.25rem;
+
+    .icon-wrapper {
+      margin-right: 0.4rem;
+
+      svg {
+        width: 1rem;
+        height: 1rem;
+      }
+    }
+  }
+
+  &.size-middle :deep(button) {
+    height: 2rem;
+    padding: 0.25rem 0.5rem;
+    font-size: 0.75rem;
+    line-height: 1rem;
+
+    .icon-wrapper {
+      margin-right: 0.2rem;
+
+      svg {
+        width: 0.75rem;
+        height: 0.75rem;
+      }
+    }
+  }
+
+  &.size-small :deep(button) {
+    height: 1.75rem;
+    padding: 0.2rem 0.4rem;
+    font-size: 0.65rem;
+    line-height: 0.75rem;
+
+    .icon-wrapper {
+      margin-right: 0.1rem;
+
+      svg {
+        width: 0.65rem;
+        height: 0.65rem;
+      }
+    }
+  }
+
+  &.no-gap > :deep(button):nth-of-type(1) {
+    border-radius: calc(var(--radius) - 2px) 0 0 calc(var(--radius) - 2px);
+  }
+
+  &.no-gap > :deep(button):last-of-type {
+    border-radius: 0 calc(var(--radius) - 2px) calc(var(--radius) - 2px) 0;
+  }
+
+  &.no-gap {
+    :deep(button + button) {
+      border-left-width: 0;
+      border-radius: 0;
+    }
+  }
+}
+</style>

packages/@core/ui-kit/shadcn-ui/src/components/button/button.ts

@@ -1,4 +1,5 @@
 import type { AsTag } from 'radix-vue';
+
 import type { Component } from 'vue';
 
 import type { ButtonVariants, ButtonVariantSize } from '../../ui';
@@ -21,3 +22,21 @@ export interface VbenButtonProps {
   size?: ButtonVariantSize;
   variant?: ButtonVariants;
 }
+
+export type CustomRenderType = (() => Component | string) | string;
+
+export type ValueType = boolean | number | string;
+
+export interface VbenButtonGroupProps
+  extends Pick<VbenButtonProps, 'disabled'> {
+  beforeChange?: (
+    value: ValueType,
+    isChecked: boolean,
+  ) => boolean | PromiseLike<boolean | undefined> | undefined;
+  btnClass?: any;
+  gap?: number;
+  multiple?: boolean;
+  options?: { label: CustomRenderType; value: ValueType }[];
+  showIcon?: boolean;
+  size?: 'large' | 'middle' | 'small';
+}

packages/@core/ui-kit/shadcn-ui/src/components/button/check-button-group.vue

@@ -0,0 +1,163 @@
+<script lang="ts" setup>
+import type { Arrayable } from '@vueuse/core';
+
+import type { ValueType, VbenButtonGroupProps } from './button';
+
+import { computed, ref, watch } from 'vue';
+
+import { Circle, CircleCheckBig, LoaderCircle } from '@vben-core/icons';
+import { VbenRenderContent } from '@vben-core/shadcn-ui';
+import { cn, isFunction } from '@vben-core/shared/utils';
+
+import { objectOmit } from '@vueuse/core';
+
+import VbenButtonGroup from './button-group.vue';
+import Button from './button.vue';
+
+const props = withDefaults(defineProps<VbenButtonGroupProps>(), {
+  gap: 0,
+  multiple: false,
+  showIcon: true,
+  size: 'middle',
+});
+
+const btnDefaultProps = computed(() => {
+  return {
+    ...objectOmit(props, ['options', 'btnClass', 'size', 'disabled']),
+    class: cn(props.btnClass),
+  };
+});
+const modelValue = defineModel<Arrayable<ValueType> | undefined>();
+
+const innerValue = ref<Array<ValueType>>([]);
+const loadingValues = ref<Array<ValueType>>([]);
+watch(
+  () => props.multiple,
+  (val) => {
+    if (val) {
+      modelValue.value = innerValue.value;
+    } else {
+      modelValue.value =
+        innerValue.value.length > 0 ? innerValue.value[0] : undefined;
+    }
+  },
+  { immediate: true },
+);
+
+watch(
+  () => modelValue.value,
+  (val) => {
+    if (Array.isArray(val)) {
+      const arrVal = val.filter((v) => v !== undefined);
+      if (arrVal.length > 0) {
+        innerValue.value = props.multiple
+          ? [...arrVal]
+          : [arrVal[0] as ValueType];
+      } else {
+        innerValue.value = [];
+      }
+    } else {
+      innerValue.value = val === undefined ? [] : [val as ValueType];
+    }
+  },
+  { deep: true },
+);
+
+async function onBtnClick(value: ValueType) {
+  if (props.beforeChange && isFunction(props.beforeChange)) {
+    try {
+      loadingValues.value.push(value);
+      const canChange = await props.beforeChange(
+        value,
+        !innerValue.value.includes(value),
+      );
+      if (canChange === false) {
+        return;
+      }
+    } finally {
+      loadingValues.value.splice(loadingValues.value.indexOf(value), 1);
+    }
+  }
+
+  if (props.multiple) {
+    if (innerValue.value.includes(value)) {
+      innerValue.value = innerValue.value.filter((item) => item !== value);
+    } else {
+      innerValue.value.push(value);
+    }
+    modelValue.value = innerValue.value;
+  } else {
+    innerValue.value = [value];
+    modelValue.value = value;
+  }
+}
+</script>
+<template>
+  <VbenButtonGroup
+    :size="props.size"
+    :gap="props.gap"
+    class="vben-check-button-group"
+  >
+    <Button
+      v-for="(btn, index) in props.options"
+      :key="index"
+      :class="cn('border', props.btnClass)"
+      :disabled="
+        props.disabled ||
+        loadingValues.includes(btn.value) ||
+        (!props.multiple && loadingValues.length > 0)
+      "
+      v-bind="btnDefaultProps"
+      :variant="innerValue.includes(btn.value) ? 'default' : 'outline'"
+      @click="onBtnClick(btn.value)"
+    >
+      <div class="icon-wrapper" v-if="props.showIcon">
+        <LoaderCircle
+          class="animate-spin"
+          v-if="loadingValues.includes(btn.value)"
+        />
+        <CircleCheckBig v-else-if="innerValue.includes(btn.value)" />
+        <Circle v-else />
+      </div>
+      <slot name="option" :label="btn.label" :value="btn.value">
+        <VbenRenderContent :content="btn.label" />
+      </slot>
+    </Button>
+  </VbenButtonGroup>
+</template>
+<style lang="scss" scoped>
+.vben-check-button-group {
+  &:deep(.size-large) button {
+    .icon-wrapper {
+      margin-right: 0.3rem;
+
+      svg {
+        width: 1rem;
+        height: 1rem;
+      }
+    }
+  }
+
+  &:deep(.size-middle) button {
+    .icon-wrapper {
+      margin-right: 0.2rem;
+
+      svg {
+        width: 0.75rem;
+        height: 0.75rem;
+      }
+    }
+  }
+
+  &:deep(.size-small) button {
+    .icon-wrapper {
+      margin-right: 0.1rem;
+
+      svg {
+        width: 0.65rem;
+        height: 0.65rem;
+      }
+    }
+  }
+}
+</style>

packages/@core/ui-kit/shadcn-ui/src/components/button/index.ts

@@ -1,3 +1,5 @@
 export type * from './button';
+export { default as VbenButtonGroup } from './button-group.vue';
 export { default as VbenButton } from './button.vue';
+export { default as VbenCheckButtonGroup } from './check-button-group.vue';
 export { default as VbenIconButton } from './icon-button.vue';

packages/@core/ui-kit/shadcn-ui/src/components/count-to-animator/count-to-animator.vue

@@ -37,7 +37,18 @@ const props = withDefaults(defineProps<Props>(), {
   useEasing: true,
 });
 
-const emit = defineEmits(['onStarted', 'onFinished']);
+const emit = defineEmits<{
+  finished: [];
+  /**
+   * @deprecated 请使用{@link finished}事件
+   */
+  onFinished: [];
+  /**
+   * @deprecated 请使用{@link started}事件
+   */
+  onStarted: [];
+  started: [];
+}>();
 
 const source = ref(props.startVal);
 const disabled = ref(false);
@@ -73,8 +84,14 @@ function run() {
   outputValue = useTransition(source, {
     disabled,
     duration: props.duration,
-    onFinished: () => emit('onFinished'),
+    onFinished: () => {
-    onStarted: () => emit('onStarted'),
+      emit('finished');
+      emit('onFinished');
+    },
+    onStarted: () => {
+      emit('started');
+      emit('onStarted');
+    },
     ...(props.useEasing
       ? { transition: TransitionPresets[props.transition] }
       : {}),

packages/@core/ui-kit/shadcn-ui/src/components/spinner/loading.vue

@@ -31,7 +31,7 @@ const props = withDefaults(defineProps<Props>(), {
 });
 // const startTime = ref(0);
 const showSpinner = ref(false);
-const renderSpinner = ref(true);
+const renderSpinner = ref(false);
 const timer = ref<ReturnType<typeof setTimeout>>();
 
 watch(
@@ -69,7 +69,7 @@ function onTransitionEnd() {
   <div
     :class="
       cn(
-        'z-100 dark:bg-overlay bg-overlay-content pointer-events-none absolute left-0 top-0 flex size-full flex-col items-center justify-center transition-all duration-500',
+        'z-100 dark:bg-overlay bg-overlay-content absolute left-0 top-0 flex size-full flex-col items-center justify-center transition-all duration-500',
         {
           'invisible opacity-0': !showSpinner,
         },
@@ -78,15 +78,18 @@ function onTransitionEnd() {
     "
     @transitionend="onTransitionEnd"
   >
-    <span class="dot relative inline-block size-9 text-3xl">
+    <slot name="icon" v-if="renderSpinner">
-      <i
+      <span class="dot relative inline-block size-9 text-3xl">
-        v-for="index in 4"
+        <i
-        :key="index"
+          v-for="index in 4"
-        class="bg-primary absolute block size-4 origin-[50%_50%] scale-75 rounded-full opacity-30"
+          :key="index"
-      ></i>
+          class="bg-primary absolute block size-4 origin-[50%_50%] scale-75 rounded-full opacity-30"
-    </span>
+        ></i>
+      </span>
+    </slot>
 
-    <div v-if="text" class="mt-4 text-xs">{{ text }}</div>
+    <div v-if="text" class="text-primary mt-4 text-xs">{{ text }}</div>
+    <slot></slot>
   </div>
 </template>
 

packages/@core/ui-kit/shadcn-ui/src/components/spinner/spinner.vue

@@ -25,7 +25,7 @@ const props = withDefaults(defineProps<Props>(), {
 });
 // const startTime = ref(0);
 const showSpinner = ref(false);
-const renderSpinner = ref(true);
+const renderSpinner = ref(false);
 const timer = ref<ReturnType<typeof setTimeout>>();
 
 watch(
@@ -74,6 +74,7 @@ function onTransitionEnd() {
   >
     <div
       :class="{ paused: !renderSpinner }"
+      v-if="renderSpinner"
       class="loader before:bg-primary/50 after:bg-primary relative size-12 before:absolute before:left-0 before:top-[60px] before:h-[5px] before:w-12 before:rounded-[50%] before:content-[''] after:absolute after:left-0 after:top-0 after:h-full after:w-full after:rounded after:content-['']"
     ></div>
   </div>

packages/effects/common-ui/src/components/count-to/count-to.vue

@@ -53,7 +53,7 @@ const numMain = computed(() => {
   const result = currentValue.value
     .toFixed(props.decimals)
     .split('.')[0]
-    ?.replaceAll(/\B(?=(\d{3})+(?!\d))/g, ',');
+    ?.replaceAll(/\B(?=(\d{3})+(?!\d))/g, props.separator);
   return result;
 });
 

packages/effects/common-ui/src/components/index.ts

@@ -7,6 +7,7 @@ export * from './ellipsis-text';
 export * from './icon-picker';
 export * from './json-preview';
 export * from './json-viewer';
+export * from './loading';
 export * from './markdown';
 export * from './page';
 export * from './resize';
@@ -17,6 +18,8 @@ export * from '@vben-core/popup-ui';
 // 给文档用
 export {
   VbenButton,
+  VbenButtonGroup,
+  VbenCheckButtonGroup,
   VbenCountToAnimator,
   VbenInputPassword,
   VbenLoading,

packages/effects/common-ui/src/components/loading/directive.ts

@@ -0,0 +1,132 @@
+import type { App, Directive, DirectiveBinding } from 'vue';
+
+import { h, render } from 'vue';
+
+import { VbenLoading, VbenSpinner } from '@vben-core/shadcn-ui';
+import { isString } from '@vben-core/shared/utils';
+
+const LOADING_INSTANCE_KEY = Symbol('loading');
+const SPINNER_INSTANCE_KEY = Symbol('spinner');
+
+const CLASS_NAME_RELATIVE = 'spinner-parent--relative';
+
+const loadingDirective: Directive = {
+  mounted(el, binding) {
+    const instance = h(VbenLoading, getOptions(binding));
+    render(instance, el);
+
+    el.classList.add(CLASS_NAME_RELATIVE);
+    el[LOADING_INSTANCE_KEY] = instance;
+  },
+  unmounted(el) {
+    const instance = el[LOADING_INSTANCE_KEY];
+    el.classList.remove(CLASS_NAME_RELATIVE);
+    render(null, el);
+    instance.el.remove();
+
+    el[LOADING_INSTANCE_KEY] = null;
+  },
+
+  updated(el, binding) {
+    const instance = el[LOADING_INSTANCE_KEY];
+    const options = getOptions(binding);
+    if (options && instance?.component) {
+      try {
+        Object.keys(options).forEach((key) => {
+          instance.component.props[key] = options[key];
+        });
+        instance.component.update();
+      } catch (error) {
+        console.error(
+          'Failed to update loading component in directive:',
+          error,
+        );
+      }
+    }
+  },
+};
+
+function getOptions(binding: DirectiveBinding) {
+  if (binding.value === undefined) {
+    return { spinning: true };
+  } else if (typeof binding.value === 'boolean') {
+    return { spinning: binding.value };
+  } else {
+    return { ...binding.value };
+  }
+}
+
+const spinningDirective: Directive = {
+  mounted(el, binding) {
+    const instance = h(VbenSpinner, getOptions(binding));
+    render(instance, el);
+
+    el.classList.add(CLASS_NAME_RELATIVE);
+    el[SPINNER_INSTANCE_KEY] = instance;
+  },
+  unmounted(el) {
+    const instance = el[SPINNER_INSTANCE_KEY];
+    el.classList.remove(CLASS_NAME_RELATIVE);
+    render(null, el);
+    instance.el.remove();
+
+    el[SPINNER_INSTANCE_KEY] = null;
+  },
+
+  updated(el, binding) {
+    const instance = el[SPINNER_INSTANCE_KEY];
+    const options = getOptions(binding);
+    if (options && instance?.component) {
+      try {
+        Object.keys(options).forEach((key) => {
+          instance.component.props[key] = options[key];
+        });
+        instance.component.update();
+      } catch (error) {
+        console.error(
+          'Failed to update spinner component in directive:',
+          error,
+        );
+      }
+    }
+  },
+};
+
+type loadingDirectiveParams = {
+  /** 是否注册loading指令。如果提供一个string，则将指令注册为指定的名称 */
+  loading?: boolean | string;
+  /** 是否注册spinning指令。如果提供一个string，则将指令注册为指定的名称 */
+  spinning?: boolean | string;
+};
+
+/**
+ * 注册loading指令
+ * @param app
+ * @param params
+ */
+export function registerLoadingDirective(
+  app: App,
+  params?: loadingDirectiveParams,
+) {
+  // 注入一个样式供指令使用，确保容器是相对定位
+  const style = document.createElement('style');
+  style.id = CLASS_NAME_RELATIVE;
+  style.innerHTML = `
+    .${CLASS_NAME_RELATIVE} {
+      position: relative !important;
+    }
+  `;
+  document.head.append(style);
+  if (params?.loading !== false) {
+    app.directive(
+      isString(params?.loading) ? params.loading : 'loading',
+      loadingDirective,
+    );
+  }
+  if (params?.spinning !== false) {
+    app.directive(
+      isString(params?.spinning) ? params.spinning : 'spinning',
+      spinningDirective,
+    );
+  }
+}

packages/effects/common-ui/src/components/loading/index.ts

@@ -0,0 +1,3 @@
+export * from './directive';
+export { default as Loading } from './loading.vue';
+export { default as Spinner } from './spinner.vue';

packages/effects/common-ui/src/components/loading/loading.vue

@@ -0,0 +1,39 @@
+<script lang="ts" setup>
+import { VbenLoading } from '@vben-core/shadcn-ui';
+import { cn } from '@vben-core/shared/utils';
+
+interface LoadingProps {
+  class?: string;
+  /**
+   * @zh_CN 最小加载时间
+   * @en_US Minimum loading time
+   */
+  minLoadingTime?: number;
+
+  /**
+   * @zh_CN loading状态开启
+   */
+  spinning?: boolean;
+  /**
+   * @zh_CN 文字
+   */
+  text?: string;
+}
+
+defineOptions({ name: 'Loading' });
+const props = defineProps<LoadingProps>();
+</script>
+<template>
+  <div :class="cn('relative min-h-20', props.class)">
+    <slot></slot>
+    <VbenLoading
+      :min-loading-time="props.minLoadingTime"
+      :spinning="props.spinning"
+      :text="props.text"
+    >
+      <template v-if="$slots.icon" #icon>
+        <slot name="icon"></slot>
+      </template>
+    </VbenLoading>
+  </div>
+</template>

packages/effects/common-ui/src/components/loading/spinner.vue

@@ -0,0 +1,28 @@
+<script lang="ts" setup>
+import { VbenSpinner } from '@vben-core/shadcn-ui';
+import { cn } from '@vben-core/shared/utils';
+
+interface SpinnerProps {
+  class?: string;
+  /**
+   * @zh_CN 最小加载时间
+   * @en_US Minimum loading time
+   */
+  minLoadingTime?: number;
+  /**
+   * @zh_CN loading状态开启
+   */
+  spinning?: boolean;
+}
+defineOptions({ name: 'Spinner' });
+const props = defineProps<SpinnerProps>();
+</script>
+<template>
+  <div :class="cn('relative min-h-20', props.class)">
+    <slot></slot>
+    <VbenSpinner
+      :min-loading-time="props.minLoadingTime"
+      :spinning="props.spinning"
+    />
+  </div>
+</template>

packages/effects/plugins/src/vxe-table/use-vxe-grid.vue

@@ -355,7 +355,7 @@ onUnmounted(() => {
         <div
           v-if="formOptions"
           v-show="showSearchForm !== false"
-          :class="cn('relative rounded py-3', isCompactForm ? 'pb-6' : 'pb-4')"
+          :class="cn('relative rounded py-3', isCompactForm ? 'pb-8' : 'pb-4')"
         >
           <slot name="form">
             <Form>

packages/utils/src/helpers/generate-routes-backend.ts

@@ -1,9 +1,10 @@
+import type { RouteRecordRaw } from 'vue-router';
+
 import type {
   ComponentRecordType,
   GenerateMenuAndRoutesOptions,
   RouteRecordStringComponent,
 } from '@vben-core/typings';
-import type { RouteRecordRaw } from 'vue-router';
 
 import { mapTree } from '@vben-core/shared/utils';
 

playground/src/adapter/component/index.ts

@@ -3,11 +3,15 @@
  * 可用于 vben-form、vben-modal、vben-drawer 等组件使用,
  */
 
-import type { BaseFormComponentType } from '@vben/common-ui';
 import type { Component, SetupContext } from 'vue';
 
+import type { BaseFormComponentType } from '@vben/common-ui';
+
+import { h } from 'vue';
+
 import { ApiComponent, globalShareState, IconPicker } from '@vben/common-ui';
 import { $t } from '@vben/locales';
+
 import {
   AutoComplete,
   Button,
@@ -32,7 +36,6 @@ import {
   TreeSelect,
   Upload,
 } from 'ant-design-vue';
-import { h } from 'vue';
 
 const withDefaultPlaceholder = <T extends Component>(
   component: T,
@@ -123,7 +126,13 @@ async function initComponentAdapter() {
     IconPicker: (props, { attrs, slots }) => {
       return h(
         IconPicker,
-        { iconSlot: 'addonAfter', inputComponent: Input, ...props, ...attrs },
+        {
+          iconSlot: 'addonAfter',
+          inputComponent: Input,
+          modelValueProp: 'value',
+          ...props,
+          ...attrs,
+        },
         slots,
       );
     },

playground/src/bootstrap.ts

@@ -1,7 +1,7 @@
 import { createApp, watchEffect } from 'vue';
 
 import { registerAccessDirective } from '@vben/access';
-import { initTippy } from '@vben/common-ui';
+import { initTippy, registerLoadingDirective } from '@vben/common-ui';
 import { MotionPlugin } from '@vben/plugins/motion';
 import { preferences } from '@vben/preferences';
 import { initStores } from '@vben/stores';
@@ -32,6 +32,12 @@ async function bootstrap(namespace: string) {
 
   const app = createApp(App);
 
+  // 注册v-loading指令
+  registerLoadingDirective(app, {
+    loading: 'loading', // 在这里可以自定义指令名称，也可以明确提供false表示不注册这个指令
+    spinning: 'spinning',
+  });
+
   // 国际化 i18n 配置
   await setupI18n(app);
 

playground/src/locales/langs/en-US/examples.json

@@ -12,6 +12,7 @@
   "form": {
     "title": "Form",
     "basic": "Basic Form",
+    "layout": "Custom Layout",
     "query": "Query Form",
     "rules": "Form Rules",
     "dynamic": "Dynamic Form",
@@ -62,5 +63,8 @@
   },
   "layout": {
     "col-page": "ColPage Layout"
+  },
+  "button-group": {
+    "title": "Button Group"
   }
 }

playground/src/locales/langs/zh-CN/examples.json

@@ -15,6 +15,7 @@
   "form": {
     "title": "表单",
     "basic": "基础表单",
+    "layout": "自定义布局",
     "query": "查询表单",
     "rules": "表单校验",
     "dynamic": "动态表单",
@@ -62,5 +63,8 @@
   },
   "layout": {
     "col-page": "双列布局"
+  },
+  "button-group": {
+    "title": "按钮组"
   }
 }

playground/src/router/routes/modules/examples.ts

@@ -53,6 +53,14 @@ const routes: RouteRecordRaw[] = [
               title: $t('examples.form.dynamic'),
             },
           },
+          {
+            name: 'FormLayoutExample',
+            path: '/examples/form/custom-layout',
+            component: () => import('#/views/examples/form/custom-layout.vue'),
+            meta: {
+              title: $t('examples.form.layout'),
+            },
+          },
           {
             name: 'FormCustomExample',
             path: '/examples/form/custom',
@@ -282,6 +290,24 @@ const routes: RouteRecordRaw[] = [
           title: 'CountTo',
         },
       },
+      {
+        name: 'Loading',
+        path: '/examples/loading',
+        component: () => import('#/views/examples/loading/index.vue'),
+        meta: {
+          icon: 'mdi:circle-double',
+          title: 'Loading',
+        },
+      },
+      {
+        name: 'ButtonGroup',
+        path: '/examples/button-group',
+        component: () => import('#/views/examples/button-group/index.vue'),
+        meta: {
+          icon: 'mdi:check-circle',
+          title: $t('examples.button-group.title'),
+        },
+      },
     ],
   },
 ];

playground/src/views/examples/button-group/index.vue

@@ -0,0 +1,194 @@
+<script lang="ts" setup>
+import type { Recordable } from '@vben/types';
+
+import { reactive, ref } from 'vue';
+
+import {
+  Page,
+  VbenButton,
+  VbenButtonGroup,
+  VbenCheckButtonGroup,
+} from '@vben/common-ui';
+
+import { Button, Card, message } from 'ant-design-vue';
+
+import { useVbenForm } from '#/adapter/form';
+
+const radioValue = ref<string | undefined>('a');
+const checkValue = ref(['a', 'b']);
+
+const options = [
+  { label: '选项1', value: 'a' },
+  { label: '选项2', value: 'b' },
+  { label: '选项3', value: 'c' },
+  { label: '选项4', value: 'd' },
+  { label: '选项5', value: 'e' },
+  { label: '选项6', value: 'f' },
+];
+
+function resetValues() {
+  radioValue.value = undefined;
+  checkValue.value = [];
+}
+
+function beforeChange(v: any, isChecked: boolean) {
+  return new Promise((resolve) => {
+    message.loading({
+      content: `正在设置${v}为${isChecked ? '选中' : '未选中'}...`,
+      duration: 0,
+      key: 'beforeChange',
+    });
+    setTimeout(() => {
+      message.success({ content: `${v} 已设置成功`, key: 'beforeChange' });
+      resolve(true);
+    }, 2000);
+  });
+}
+
+const compProps = reactive({
+  beforeChange: undefined,
+  disabled: false,
+  gap: 0,
+  showIcon: true,
+  size: 'middle',
+} as Recordable<any>);
+
+const [Form] = useVbenForm({
+  handleValuesChange(values) {
+    Object.keys(values).forEach((k) => {
+      if (k === 'beforeChange') {
+        compProps[k] = values[k] ? beforeChange : undefined;
+      } else {
+        compProps[k] = values[k];
+      }
+    });
+  },
+  schema: [
+    {
+      component: 'RadioGroup',
+      componentProps: {
+        options: [
+          { label: '大', value: 'large' },
+          { label: '中', value: 'middle' },
+          { label: '小', value: 'small' },
+        ],
+      },
+      defaultValue: compProps.size,
+      fieldName: 'size',
+      label: '尺寸',
+    },
+    {
+      component: 'RadioGroup',
+      componentProps: {
+        options: [
+          { label: '无', value: 0 },
+          { label: '小', value: 5 },
+          { label: '中', value: 15 },
+          { label: '大', value: 30 },
+        ],
+      },
+      defaultValue: compProps.gap,
+      fieldName: 'gap',
+      label: '间距',
+    },
+    {
+      component: 'Switch',
+      defaultValue: compProps.showIcon,
+      fieldName: 'showIcon',
+      label: '显示图标',
+    },
+    {
+      component: 'Switch',
+      defaultValue: compProps.disabled,
+      fieldName: 'disabled',
+      label: '禁用',
+    },
+    {
+      component: 'Switch',
+      defaultValue: false,
+      fieldName: 'beforeChange',
+      label: '前置回调',
+    },
+  ],
+  showDefaultActions: false,
+  submitOnChange: true,
+});
+
+function onBtnClick(value: any) {
+  const opt = options.find((o) => o.value === value);
+  if (opt) {
+    message.success(`点击了按钮${opt.label}，value = ${value}`);
+  }
+}
+</script>
+<template>
+  <Page
+    title="VbenButtonGroup 按钮组"
+    description="VbenButtonGroup是一个按钮容器，用于包裹一组按钮，协调整体样式。VbenCheckButtonGroup则可以作为一个表单组件，提供单选或多选功能"
+  >
+    <Card title="基本用法">
+      <template #extra>
+        <Button type="primary" @click="resetValues">清空值</Button>
+      </template>
+      <p class="mt-4">按钮组：</p>
+      <div class="mt-2 flex flex-col gap-2">
+        <VbenButtonGroup v-bind="compProps" border>
+          <VbenButton
+            v-for="btn in options"
+            :key="btn.value"
+            variant="link"
+            @click="onBtnClick(btn.value)"
+          >
+            {{ btn.label }}
+          </VbenButton>
+        </VbenButtonGroup>
+        <VbenButtonGroup v-bind="compProps" border>
+          <VbenButton
+            v-for="btn in options"
+            :key="btn.value"
+            variant="outline"
+            @click="onBtnClick(btn.value)"
+          >
+            {{ btn.label }}
+          </VbenButton>
+        </VbenButtonGroup>
+      </div>
+      <p class="mt-4">单选：{{ radioValue }}</p>
+      <div class="mt-2 flex flex-col gap-2">
+        <VbenCheckButtonGroup
+          v-model="radioValue"
+          :options="options"
+          v-bind="compProps"
+        />
+      </div>
+      <p class="mt-4">单选插槽：{{ radioValue }}</p>
+      <div class="mt-2 flex flex-col gap-2">
+        <VbenCheckButtonGroup
+          v-model="radioValue"
+          :options="options"
+          v-bind="compProps"
+        >
+          <template #option="{ label, value }">
+            <div class="flex items-center">
+              <span>{{ label }}</span>
+              <span class="ml-2 text-gray-400">{{ value }}</span>
+            </div>
+          </template>
+        </VbenCheckButtonGroup>
+      </div>
+      <p class="mt-4">多选{{ checkValue }}</p>
+      <div class="mt-2 flex flex-col gap-2">
+        <VbenCheckButtonGroup
+          v-model="checkValue"
+          multiple
+          :options="options"
+          v-bind="compProps"
+        />
+      </div>
+    </Card>
+
+    <Card title="设置" class="mt-4">
+      <Form />
+    </Card>
+  </Page>
+</template>

playground/src/views/examples/form/basic.vue

@@ -1,15 +1,17 @@
 <script lang="ts" setup>
-import { useVbenForm } from '#/adapter/form';
-import { getAllMenusApi } from '#/api';
-import { Page } from '@vben/common-ui';
-import { useDebounceFn } from '@vueuse/core';
-import { Button, Card, message, Spin, TabPane, Tabs } from 'ant-design-vue';
-import dayjs from 'dayjs';
 import { h, ref } from 'vue';
 
+import { Page } from '@vben/common-ui';
+
+import { useDebounceFn } from '@vueuse/core';
+import { Button, Card, message, Spin, Tag } from 'ant-design-vue';
+import dayjs from 'dayjs';
+
+import { useVbenForm, z } from '#/adapter/form';
+import { getAllMenusApi } from '#/api';
+
 import DocButton from '../doc-button.vue';
 
-const activeTab = ref('basic');
 const keyword = ref('');
 const fetching = ref(false);
 // 模拟远程获取数据
@@ -108,6 +110,7 @@ const [BaseForm, baseFormApi] = useVbenForm({
           notFoundContent: fetching.value ? h(Spin) : undefined,
         };
       },
+      rules: 'selectRequired',
     },
     {
       component: 'ApiTreeSelect',
@@ -115,10 +118,10 @@ const [BaseForm, baseFormApi] = useVbenForm({
       componentProps: {
         // 菜单接口
         api: getAllMenusApi,
-        childrenField: 'children',
         // 菜单接口转options格式
         labelField: 'name',
         valueField: 'path',
+        childrenField: 'children',
       },
       // 字段名
       fieldName: 'apiTree',
@@ -148,6 +151,7 @@ const [BaseForm, baseFormApi] = useVbenForm({
       label: '图标',
     },
     {
+      colon: false,
       component: 'Select',
       componentProps: {
         allowClear: true,
@@ -166,7 +170,7 @@ const [BaseForm, baseFormApi] = useVbenForm({
         showSearch: true,
       },
       fieldName: 'options',
-      label: '下拉选',
+      label: () => h(Tag, { color: 'warning' }, () => '😎自定义：'),
     },
     {
       component: 'RadioGroup',
@@ -222,6 +226,9 @@ const [BaseForm, baseFormApi] = useVbenForm({
           default: () => ['我已阅读并同意'],
         };
       },
+      rules: z
+        .boolean()
+        .refine((v) => v, { message: '为什么不同意？勾上它！' }),
     },
     {
       component: 'Mentions',
@@ -252,6 +259,8 @@ const [BaseForm, baseFormApi] = useVbenForm({
         class: 'w-auto',
       },
       fieldName: 'switch',
+      help: () =>
+        ['这是一个多行帮助信息', '第二行', '第三行'].map((v) => h('p', v)),
       label: '开关',
     },
     {
@@ -321,75 +330,6 @@ const [BaseForm, baseFormApi] = useVbenForm({
   wrapperClass: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
 });
 
-const [CustomLayoutForm] = useVbenForm({
-  // 所有表单项共用，可单独在表单内覆盖
-  commonConfig: {
-    // 所有表单项
-    componentProps: {
-      class: 'w-full',
-    },
-  },
-  layout: 'horizontal',
-  schema: [
-    {
-      component: 'Select',
-      fieldName: 'field1',
-      label: '字符串',
-    },
-    {
-      component: 'TreeSelect',
-      fieldName: 'field2',
-      label: '字符串',
-    },
-    {
-      component: 'Mentions',
-      fieldName: 'field3',
-      label: '字符串',
-    },
-    {
-      component: 'Input',
-      fieldName: 'field4',
-      label: '字符串',
-    },
-    {
-      component: 'InputNumber',
-      fieldName: 'field5',
-      // 从第三列开始 相当于中间空了一列
-      formItemClass: 'col-start-3',
-      label: '前面空了一列',
-    },
-    {
-      component: 'Textarea',
-      fieldName: 'field6',
-      // 占满三列空间 基线对齐
-      formItemClass: 'col-span-3 items-baseline',
-      label: '占满三列',
-    },
-    {
-      component: 'Input',
-      fieldName: 'field7',
-      // 占满2列空间 从第二列开始 相当于前面空了一列
-      formItemClass: 'col-span-2 col-start-2',
-      label: '占满2列',
-    },
-    {
-      component: 'Input',
-      fieldName: 'field8',
-      // 左右留空
-      formItemClass: 'col-start-2',
-      label: '左右留空',
-    },
-    {
-      component: 'InputPassword',
-      fieldName: 'field9',
-      formItemClass: 'col-start-1',
-      label: '字符串',
-    },
-  ],
-  // 一共三列
-  wrapperClass: 'grid-cols-3',
-});
-
 function onSubmit(values: Record<string, any>) {
   message.success({
     content: `form values: ${JSON.stringify(values)}`,
@@ -425,7 +365,6 @@ function handleSetFormValue() {
   <Page
     content-class="flex flex-col gap-4"
     description="表单组件基础示例，请注意，该页面用到的参数代码会添加一些简单注释，方便理解，请仔细查看。"
-    header-class="pb-0"
     title="表单组件"
   >
     <template #description>
@@ -434,22 +373,15 @@ function handleSetFormValue() {
           表单组件基础示例，请注意，该页面用到的参数代码会添加一些简单注释，方便理解，请仔细查看。
         </p>
       </div>
-      <Tabs v-model:active-key="activeTab" :tab-bar-style="{ marginBottom: 0 }">
-        <TabPane key="basic" tab="基础示例" />
-        <TabPane key="layout" tab="自定义布局" />
-      </Tabs>
     </template>
     <template #extra>
       <DocButton class="mb-2" path="/components/common-ui/vben-form" />
     </template>
-    <Card v-show="activeTab === 'basic'" title="基础示例">
+    <Card title="基础示例">
       <template #extra>
         <Button type="primary" @click="handleSetFormValue">设置表单值</Button>
       </template>
       <BaseForm />
     </Card>
-    <Card v-show="activeTab === 'layout'" title="使用tailwind自定义布局">
-      <CustomLayoutForm />
-    </Card>
   </Page>
 </template>

playground/src/views/examples/form/custom-layout.vue

@@ -0,0 +1,111 @@
+<script lang="ts" setup>
+import { h } from 'vue';
+
+import { Page } from '@vben/common-ui';
+
+import { Card } from 'ant-design-vue';
+
+import { useVbenForm } from '#/adapter/form';
+
+import DocButton from '../doc-button.vue';
+
+const [CustomLayoutForm] = useVbenForm({
+  // 所有表单项共用，可单独在表单内覆盖
+  commonConfig: {
+    // 所有表单项
+    componentProps: {
+      class: 'w-full',
+    },
+  },
+  layout: 'horizontal',
+  schema: [
+    {
+      component: 'Select',
+      fieldName: 'field1',
+      label: '字符串',
+    },
+    {
+      component: 'TreeSelect',
+      fieldName: 'field2',
+      label: '字符串',
+    },
+    {
+      component: 'Mentions',
+      fieldName: 'field3',
+      label: '字符串',
+    },
+    {
+      component: 'Input',
+      fieldName: 'field4',
+      label: '字符串',
+    },
+    {
+      component: 'InputNumber',
+      fieldName: 'field5',
+      // 从第三列开始 相当于中间空了一列
+      formItemClass: 'col-start-3',
+      label: '前面空了一列',
+    },
+    {
+      component: 'Divider',
+      fieldName: '_divider',
+      formItemClass: 'col-span-3',
+      hideLabel: true,
+      renderComponentContent: () => {
+        return {
+          default: () => h('div', '分割线'),
+        };
+      },
+    },
+    {
+      component: 'Textarea',
+      fieldName: 'field6',
+      // 占满三列空间 基线对齐
+      formItemClass: 'col-span-3 items-baseline',
+      label: '占满三列',
+    },
+    {
+      component: 'Input',
+      fieldName: 'field7',
+      // 占满2列空间 从第二列开始 相当于前面空了一列
+      formItemClass: 'col-span-2 col-start-2',
+      label: '占满2列',
+    },
+    {
+      component: 'Input',
+      fieldName: 'field8',
+      // 左右留空
+      formItemClass: 'col-start-2',
+      label: '左右留空',
+    },
+    {
+      component: 'InputPassword',
+      fieldName: 'field9',
+      formItemClass: 'col-start-1',
+      label: '字符串',
+    },
+  ],
+  // 一共三列
+  wrapperClass: 'grid-cols-3',
+});
+</script>
+
+<template>
+  <Page
+    content-class="flex flex-col gap-4"
+    description="使用tailwind自定义表单项的布局"
+    title="表单自定义布局"
+  >
+    <template #description>
+      <div class="text-muted-foreground">
+        <p>使用tailwind自定义表单项的布局，使用Divider分割表单。</p>
+      </div>
+    </template>
+    <template #extra>
+      <DocButton class="mb-2" path="/components/common-ui/vben-form" />
+    </template>
+    <Card title="使用tailwind自定义布局">
+      <CustomLayoutForm />
+    </Card>
+  </Page>
+</template>

playground/src/views/examples/form/rules.vue

@@ -150,7 +150,9 @@ const [Form, formApi] = useVbenForm({
           default: () => ['我已阅读并同意'],
         };
       },
-      rules: 'selectRequired',
+      rules: z.boolean().refine((value) => value, {
+        message: '请勾选',
+      }),
     },
     {
       component: 'DatePicker',

playground/src/views/examples/loading/index.vue

@@ -0,0 +1,101 @@
+<script lang="ts" setup>
+import { Loading, Page, Spinner } from '@vben/common-ui';
+import { IconifyIcon } from '@vben/icons';
+
+import { refAutoReset } from '@vueuse/core';
+import { Button, Card, Spin } from 'ant-design-vue';
+
+const spinning = refAutoReset(false, 3000);
+const loading = refAutoReset(false, 3000);
+
+const spinningV = refAutoReset(false, 3000);
+const loadingV = refAutoReset(false, 3000);
+</script>
+<template>
+  <Page
+    title="Vben Loading"
+    description="加载中状态组件。这个组件可以为其它作为容器的组件添加一个加载中的遮罩层。使用它们时，容器需要relative定位。"
+  >
+    <Card title="Antd Spin">
+      <template #actions>这是Antd 组件库自带的Spin组件演示</template>
+      <Spin :spinning="spinning" tip="加载中...">
+        <Button type="primary" @click="spinning = true">显示Spin</Button>
+      </Spin>
+    </Card>
+
+    <Card title="Vben Loading" v-loading="loadingV" class="mt-4">
+      <template #extra>
+        <Button type="primary" @click="loadingV = true">
+          v-loading 指令
+        </Button>
+      </template>
+      <template #actions>
+        Loading组件可以设置文字，并且也提供了icon插槽用于替换加载图标。
+      </template>
+      <div class="flex gap-4">
+        <div class="size-40">
+          <Loading
+            :spinning="loading"
+            text="正在加载..."
+            class="flex h-full w-full items-center justify-center"
+          >
+            <Button type="primary" @click="loading = true">默认动画</Button>
+          </Loading>
+        </div>
+        <div class="size-40">
+          <Loading
+            :spinning="loading"
+            class="flex h-full w-full items-center justify-center"
+          >
+            <Button type="primary" @click="loading = true">自定义动画1</Button>
+            <template #icon>
+              <IconifyIcon
+                icon="svg-spinners:ring-resize"
+                class="text-primary size-10"
+              />
+            </template>
+          </Loading>
+        </div>
+        <div class="size-40">
+          <Loading
+            :spinning="loading"
+            class="flex h-full w-full items-center justify-center"
+          >
+            <Button type="primary" @click="loading = true">自定义动画2</Button>
+            <template #icon>
+              <IconifyIcon
+                icon="svg-spinners:bars-scale"
+                class="text-primary size-10"
+              />
+            </template>
+          </Loading>
+        </div>
+      </div>
+    </Card>
+
+    <Card
+      title="Vben Spinner"
+      v-spinning="spinningV"
+      class="mt-4 overflow-hidden"
+      :body-style="{
+        position: 'relative',
+        overflow: 'hidden',
+      }"
+    >
+      <template #extra>
+        <Button type="primary" @click="spinningV = true">
+          v-spinning 指令
+        </Button>
+      </template>
+      <template #actions>
+        Spinner组件是Loading组件的一个特例，只有一个固定的统一样式。
+      </template>
+      <Spinner
+        :spinning="spinning"
+        class="flex size-40 items-center justify-center"
+      >
+        <Button type="primary" @click="spinning = true">显示Spinner</Button>
+      </Spinner>
+    </Card>
+  </Page>
+</template>