@qin-ui/antd-vue-pro 2.1.14 → 2.2.0

package/src/components/component-provider/types/index.ts

@@ -0,0 +1,90 @@
+import { GridItemProps, FormItemProps, TableProps } from '../../../shared/ui';
+import { Base, Grid } from '../../form/types';
+import { ProFormProps } from '../../form';
+import { ProTableProps } from '../../table';
+import { AllowedComponentProps } from 'vue';
+
+import { GetComponentType, ComponentName } from '../../form/constants';
+import type { ComponentProps } from 'vue-component-type-helpers';
+
+type PP<T extends Record<string, any>> = Partial<T & AllowedComponentProps>;
+
+type FP<T extends Record<string, any>> = Partial<
+  T &
+    Pick<Base, 'valueFormatter' | 'componentContainer' | 'modelProp'> &
+    AllowedComponentProps
+>;
+
+/**
+ * @qin-ui/antd-vue-pro 全局配置变量类型
+ *
+ * @description 定义可通过 ProComponentProvider 配置的所有组件默认属性。
+ * 支持配置表单、表格、表单项以及所有内置组件的默认属性。
+ *
+ * @example
+ * ```ts
+ * // 通过 ProComponentProvider 配置全局默认值
+ * const componentVars: ComponentVars = {
+ *   'pro-form': {
+ *     grid: { gutter: 24 },
+ *     labelCol: { span: 4 },
+ *   },
+ *   'input': {
+ *     placeholder: '请输入内容',
+ *     maxlength: 200,
+ *   },
+ *   'select': {
+ *     placeholder: '请选择',
+ *   },
+ * }
+ * ```
+ */
+export type RequiredComponentVars = {
+  /** ProTable 全局默认属性 */
+  'pro-table': PP<
+    TableProps &
+      Pick<
+        ProTableProps,
+        | 'control'
+        | 'searchFormConfig'
+        | 'immediateSearch'
+        | 'addIndexColumn'
+        | 'tableContainer'
+      >
+  >;
+  /** ProForm 全局默认属性，grid 必须为 GridProps 对象而非 boolean */
+  'pro-form': PP<
+    Omit<ProFormProps, 'form' | 'grid'> & {
+      grid: Exclude<Grid, undefined | boolean>;
+    }
+  >;
+  /** ProFormItem 全局默认属性 */
+  'pro-form-item': PP<
+    FormItemProps &
+      Pick<GridItemProps, 'span' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'> &
+      Pick<Base, 'formItemContainer'>
+  >;
+  // field
+  /** DatePicker date 模式全局默认属性 */
+  'date-picker.date': FP<ComponentProps<GetComponentType<'date-picker'>>>;
+  /** DatePicker week 模式全局默认属性 */
+  'date-picker.week': FP<ComponentProps<GetComponentType<'date-picker'>>>;
+  /** DatePicker month 模式全局默认属性 */
+  'date-picker.month': FP<ComponentProps<GetComponentType<'date-picker'>>>;
+  /** DatePicker year 模式全局默认属性 */
+  'date-picker.year': FP<ComponentProps<GetComponentType<'date-picker'>>>;
+  /** DatePicker quarter 模式全局默认属性 */
+  'date-picker.quarter': FP<ComponentProps<GetComponentType<'date-picker'>>>;
+} & {
+  /** 其他所有内置组件的全局默认属性 */
+  [K in Exclude<ComponentName, 'custom'>]: FP<
+    ComponentProps<GetComponentType<K>>
+  >;
+};
+
+/**
+ * 组件全局配置
+ * @description RequiredComponentVars 的 Partial 版本，用于 ProComponentProvider 的 props
+ * @public
+ */
+export type ComponentVars = Partial<RequiredComponentVars>;

package/src/components/form/components/BaseField/index.vue

@@ -0,0 +1,188 @@
+<script lang="ts" setup>
+/**
+ * @component BaseField
+ * @description 字段级渲染组件，负责将 field 配置渲染为实际的输入组件
+ *
+ * ## 核心职责
+ *
+ * 1. **组件解析**：按优先级解析要渲染的组件（teleport 插槽 > 自定义组件 > 内置组件映射 > 原始值）
+ * 2. **v-model 双向绑定**：通过 computed getter/setter 将组件值与 formData 的深层路径绑定
+ * 3. **valueFormatter 处理**：支持 get/set 格式化函数，用于数据转换（如日期格式化）
+ * 4. **属性合并**：将注入的默认 props、组件传入的 attrs 合并为最终属性
+ *
+ * ## 组件解析优先级
+ *
+ * ```
+ * teleport 组件（ProForm 插槽注入）
+ *   ↓ 未匹配
+ * 自定义组件（ProComponentProvider 的 componentMap）
+ *   ↓ 未匹配
+ * 内置组件映射（componentMap: input → Input, select → Select ...）
+ *   ↓ 未匹配
+ * 原始 component 值（可能是字符串或 Vue 组件对象）
+ * ```
+ *
+ * @param {string | Component} [component] - 组件名或组件对象
+ * @param {string} [path] - 字段路径，用于绑定表单数据
+ *
+ * @slot default - 默认插槽（透传给组件）
+ */
+import {
+  type Component,
+  computed,
+  inject,
+  mergeProps,
+  ref,
+  useAttrs,
+} from 'vue';
+import { cloneDeep, omit } from '../../../../shared/core';
+import {
+  useInjectDisabled,
+  useInjectFormItemContext,
+} from '../../../../shared/ui';
+import type { Field } from '../../types';
+import { ContainerFragment, SlotComponent } from '..';
+import { componentMap, TeleportComponentNamePrefix } from '../../constants';
+import { INJECT_COMPONENTS } from '../../../component-provider/constants';
+import { useForm } from '../../hooks/useForm';
+import { getInitProps } from './utils';
+
+defineOptions({ name: 'BaseField', inheritAttrs: false });
+
+type Props = {
+  component?: string | Component;
+  path?: string;
+};
+const { component = undefined, path = '' } = defineProps<Props>();
+
+const form = useForm(false);
+const { getFormData, setFormData } = form;
+
+const componentRef = ref<any>();
+
+const formItemContext = useInjectFormItemContext();
+const triggerFormItemChange = () => {
+  formItemContext.onFieldChange();
+};
+
+const attrs: any = useAttrs();
+
+function getOldValue() {
+  return cloneDeep(getFormData?.(path));
+}
+
+// setter: 向 formData 写入值，支持 valueFormatter / valueFormatter.set 转换
+const value = computed({
+  get() {
+    let val = getFormData?.(path);
+    const { valueFormatter } = groupedAttrs.value;
+    if (
+      typeof valueFormatter === 'object' &&
+      typeof valueFormatter.get === 'function'
+    ) {
+      val = valueFormatter.get(val);
+    }
+    return val;
+  },
+  set(val) {
+    let newVal = val;
+    const { valueFormatter } = groupedAttrs.value;
+    if (valueFormatter) {
+      if (typeof valueFormatter === 'function') {
+        newVal = valueFormatter(val, getOldValue());
+      } else if (typeof valueFormatter.set === 'function') {
+        newVal = valueFormatter.set(val, getOldValue());
+      }
+    }
+    setFormData?.(path, newVal);
+    triggerFormItemChange();
+  },
+});
+
+const parentDisabled = useInjectDisabled();
+
+/*
+ * 将注入的默认 props、外部传入的 attrs、field 配置合并为最终属性
+ * 属性分为三类：绑定属性（v-model）、组件属性（传递给组件）、插槽（动态渲染）
+ */
+const groupedAttrs = computed(() => {
+  const initProps = getInitProps({
+    component: component,
+    picker: attrs.picker,
+  } as Field);
+  const mergedProps = mergeProps(
+    initProps,
+    attrs,
+    { class: attrs.componentClass, style: attrs.componentStyle },
+    { class: initProps.componentClass, style: initProps.componentStyle },
+    { disabled: attrs.disabled ?? parentDisabled.value ?? initProps.disabled },
+    { modelProp: attrs.modelProp ?? initProps.modelProp ?? 'value' }
+  ) as Required<Field>;
+
+  // prettier-ignore
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { valueFormatter, modelProp, slots, componentClass, componentStyle, componentContainer, ...rest } = mergedProps
+
+  // 从剩余属性中移除 v-model 绑定属性，避免重复绑定
+  const bindAttrs = omit(rest, [modelProp, `onUpdate:${modelProp}`]);
+
+  return {
+    attrs: bindAttrs,
+    slots,
+    componentContainer,
+    modelProp,
+    valueFormatter,
+  };
+});
+
+// 从 ProForm 插槽注入的 teleport 组件（优先级最高）
+const teleportComponent = inject(
+  `${TeleportComponentNamePrefix}${path}`,
+  undefined
+);
+
+// 从 ProComponentProvider 注入的自定义组件映射
+const customComponents = inject(INJECT_COMPONENTS, {});
+
+/*
+ * 按优先级解析最终要渲染的组件：
+ * teleport 插槽 → 自定义组件映射 → 内置组件映射 → 原始 component 值
+ */
+const is = computed(() => {
+  if (teleportComponent) return teleportComponent;
+  if (typeof component === 'string') {
+    return (
+      (customComponents as any)[component] ||
+      (componentMap as any)[component] ||
+      component
+    );
+  }
+  return component;
+});
+
+defineExpose({
+  getComponentRef: () => componentRef.value,
+  getComponentComputedProps: () => groupedAttrs.value.attrs as any,
+});
+</script>
+
+<template>
+  <ContainerFragment :component="groupedAttrs.componentContainer" :path="path">
+    <component
+      :is="is"
+      v-if="is"
+      v-bind="groupedAttrs.attrs"
+      ref="componentRef"
+      v-model:[`${groupedAttrs.modelProp}`]="value"
+      :path="path"
+    >
+      <template
+        v-for="(slot, name) in groupedAttrs.slots"
+        :key="name"
+        #[name]="scoped"
+      >
+        <SlotComponent :path="path" v-bind="scoped" :component="slot" />
+      </template>
+    </component>
+  </ContainerFragment>
+</template>

package/src/components/form/components/BaseField/utils/index.ts

@@ -0,0 +1,16 @@
+import { Field } from '../../../types';
+import { getInjectConfig } from '../../../../component-provider/constants';
+import { inject } from 'vue';
+
+export const getInitProps = (field: Field): Record<string, any> => {
+  const { component } = field as any;
+  const picker = component === 'date-picker' ? '' : (field as any).picker;
+  if (typeof component === 'string') {
+    const k = [component, picker].filter(Boolean).join('.');
+    const config = getInjectConfig(k);
+    if (!config) return {};
+    const injectProps = inject(config.injectionKey, config.default);
+    return injectProps;
+  }
+  return {};
+};

package/src/components/form/components/BaseFormItem/index.vue

@@ -0,0 +1,163 @@
+<script lang="ts" setup>
+/**
+ * @component BaseFormItem
+ * @description 表单字段渲染引擎
+ *
+ * 负责将字段配置数组渲染为实际的表单项，支持：
+ * - 字段分组（嵌套 fields 递归渲染）
+ * - 网格布局（grid 属性控制）
+ * - FormItem 包装（label、rules、校验等）
+ * - 组件绑定（通过 BaseField 渲染具体组件）
+ * - 插槽透传（label、extra、help 等 FormItem 插槽）
+ *
+ * ## 渲染流程
+ *
+ * 1. 遍历 fields 数组，过滤 hidden 字段
+ * 2. 对每个字段：
+ *    a. 通过 PathProvider 提供当前字段路径
+ *    b. 通过 GroupedFieldAttrs 将 field 配置拆分为 gridItemProps / formItemProps / componentProps
+ *    c. 如果字段有 `fields` 子字段 → 递归渲染 BaseFormItem（嵌套表单）
+ *    d. 否则 → 渲染 BaseField（输入组件）
+ * 3. 通过 ref 回调收集 FormItem 和 Component 实例，注入到 field 对象上
+ *
+ * @param {Fields<D>} [fields] - 字段配置数组
+ * @param {boolean | GridProps} [grid] - 是否启用网格布局
+ * @param {boolean} [disabled] - 是否禁用所有子字段
+ *
+ * @internal
+ */
+import { getObject, toPath } from '../../../../shared/core';
+import {
+  FormItem,
+  Grid as AGrid,
+  GridItem as AGridItem,
+  GridProps,
+  useProviderDisabled,
+} from '../../../../shared/ui';
+import { computed, inject, toValue } from 'vue';
+import type { Fields, Grid } from '../../types';
+import { BaseField, SlotComponent, ContainerFragment } from '..';
+import PathProvider from '../PathProvider/index.vue';
+import GroupedFieldAttrs from '../GroupedFieldAttrs/index.vue';
+import { INJECT_CONFIG } from '../../../component-provider/constants';
+
+defineOptions({ name: 'BaseFormItem', inheritAttrs: false });
+
+type Props = {
+  grid?: Grid;
+  fields?: Fields;
+  disabled?: boolean;
+};
+const {
+  grid = undefined,
+  fields = [],
+  disabled = undefined,
+} = defineProps<Props>();
+
+const validFields = computed(() => fields.filter?.(field => !field.hidden));
+
+useProviderDisabled(computed(() => disabled));
+
+const config = INJECT_CONFIG['pro-form'];
+
+const { grid: injectGrid } = inject(config.injectionKey, config.default);
+
+const enableGrid = computed(() => {
+  if (grid !== undefined) return !!grid;
+  return !!injectGrid;
+});
+
+const computedGridProps = computed<GridProps>(() => {
+  return enableGrid.value
+    ? { ...getObject(injectGrid), ...getObject(grid) }
+    : {};
+});
+
+const formItemRefs: any[] = [];
+const componentRefs: any[] = [];
+
+const onFormItemMounted = (index: number, formItemProps?: any) => {
+  const field = validFields.value[index];
+  Object.assign(field, {
+    getFormItemRef: () => formItemRefs[index],
+    getFormItemComputedProps: () => formItemProps,
+  });
+};
+
+const onComponentMounted = (index: number) => {
+  const field = validFields.value[index];
+  Object.assign(field, {
+    getComponentRef: () => componentRefs[index]?.getComponentRef(),
+    getComponentComputedProps: () =>
+      componentRefs[index]?.getComponentComputedProps(),
+  });
+};
+</script>
+
+<template>
+  <ContainerFragment
+    :component="enableGrid ? AGrid : undefined"
+    v-bind="computedGridProps"
+  >
+    <PathProvider
+      v-for="({ path: _path, name: _name, ...field }, index) of validFields"
+      :key="toPath(toValue((_name ?? _path) as any)).join('.') || index"
+      v-bind="{ path: (_name ?? _path) as any }"
+    >
+      <template #default="{ path }">
+        <GroupedFieldAttrs :field="field">
+          <template
+            #default="{
+              gridItemProps,
+              formItemProps: { formItemContainer, ...formItemProps },
+              componentProps,
+              formItemSlots,
+            }"
+          >
+            <ContainerFragment
+              :component="enableGrid ? AGridItem : undefined"
+              v-bind="gridItemProps"
+            >
+              <ContainerFragment :component="formItemContainer" :path="path">
+                <FormItem
+                  v-bind="formItemProps"
+                  :ref="el => (formItemRefs[index] = el)"
+                  :name="toPath(path)"
+                  :path="path"
+                  @vue:mounted="onFormItemMounted(index, formItemProps)"
+                >
+                  <template
+                    v-for="(slot, name) in formItemSlots"
+                    :key="name"
+                    #[name]="scoped"
+                  >
+                    <SlotComponent
+                      :path="path"
+                      :component="slot"
+                      v-bind="scoped"
+                    />
+                  </template>
+                  <template v-if="field.fields">
+                    <BaseFormItem
+                      :grid="(field as any).grid ?? grid"
+                      :fields="field.fields"
+                      :disabled="toValue(field.disabled)"
+                    />
+                  </template>
+                  <template v-else>
+                    <BaseField
+                      :ref="el => (componentRefs[index] = el)"
+                      v-bind="componentProps"
+                      :path="path"
+                      @vue:mounted="onComponentMounted(index)"
+                    />
+                  </template>
+                </FormItem>
+              </ContainerFragment>
+            </ContainerFragment>
+          </template>
+        </GroupedFieldAttrs>
+      </template>
+    </PathProvider>
+  </ContainerFragment>
+</template>

package/src/components/form/components/ContainerFragment/index.vue

@@ -0,0 +1,24 @@
+<script lang="ts" setup>
+/**
+ * @component ContainerFragment
+ * @description 容器分片渲染组件。用于动态渲染表单行或表单项的外部包裹容器（例如 Grid 行、Col 列等布局容器）。
+ *
+ * @public
+ */
+import type { ContainerComponent } from '../../types';
+
+type Props = {
+  component?: ContainerComponent;
+};
+
+defineProps<Props>();
+
+defineOptions({ name: 'ContainerFragment', inheritAttrs: false });
+</script>
+
+<template>
+  <component :is="component" v-if="component" v-bind="$attrs">
+    <slot />
+  </component>
+  <slot v-else />
+</template>

package/src/components/form/components/GroupedFieldAttrs/index.vue

@@ -0,0 +1,118 @@
+<script lang="ts" setup>
+/**
+ * @component GroupedFieldAttrs
+ * @description 字段属性分组器，将 field 配置对象拆分为三类属性
+ *
+ * ## 属性分发逻辑
+ *
+ * 单个 field 对象包含多种属性，需要分发到不同的渲染目标：
+ *
+ * 1. **gridItemProps** — 网格布局属性（span、xs、sm、md、lg、xl、xxl 等），传递给 GridItem
+ * 2. **formItemProps** — 表单项属性（label、rules、required 等），传递给 FormItem
+ * 3. **componentProps** — 组件属性（placeholder、allowClear 等），传递给输入组件
+ * 4. **formItemSlots** — FormItem 的具名插槽（label、help、extra 等）
+ *
+ * 分组依据：
+ * - 匹配 antd-vue GridItem 的 props key → gridItemProps
+ * - 匹配 antd-vue FormItem 的 props key → formItemProps
+ * - 其余所有属性 → componentProps
+ * - 属于 FORM_ITEM_SLOT_KEYS 的插槽 → formItemSlots
+ * - 其余插槽 → componentProps.slots
+ */
+import { computed, inject, mergeProps, toValue } from 'vue';
+import {
+  GridItemProps,
+  FormItemProps,
+  gridItemProps,
+  formItemProps,
+} from '../../../../shared/ui';
+import { INJECT_CONFIG } from '../../../component-provider/constants';
+import type { Base, Field } from '../../types';
+import { FORM_ITEM_SLOT_KEYS } from '../../constants';
+import { isPlainObject } from '../../../../shared/core';
+
+const formItemPropKeys = Object.keys(formItemProps()).concat([
+  'formItemContainer',
+]);
+const gridItemPropKeys = Object.keys(gridItemProps());
+
+type Props = {
+  field: Field;
+};
+const props = defineProps<Props>();
+
+const config = INJECT_CONFIG['pro-form-item'];
+const injectFormItemProps = inject(config.injectionKey, config.default);
+
+type GroupedFieldAttrs = {
+  gridItemProps: GridItemProps;
+  formItemProps: FormItemProps & Pick<Base, 'formItemContainer'>;
+  formItemSlots: Record<(typeof FORM_ITEM_SLOT_KEYS)[number], any>;
+  componentProps: Record<string, any>;
+};
+
+// 将 field 配置按 key 分发到三类属性分组中
+const groupedAttributes = computed<GroupedFieldAttrs>(() => {
+  let gridItemProps: Record<string, any> = {};
+  let formItemProps: Record<string, any> = {};
+  const componentProps: Record<string, any> = { slots: {} };
+  const formItemSlots: Record<string, any> = {};
+
+  if (isPlainObject(props.field)) {
+    // prettier-ignore
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { path, name, fields, formItemClass, formItemStyle, hidden, span, getFormItemRef, getComponentRef, getFormItemComputedProps, getComponentComputedProps, slots = {}, formItemDataAttrs = {}, componentDataAttrs = {}, extraProps, ...rest } =
+    props.field as any;
+    const {
+      class: injectClassName,
+      style: injectStyle,
+      span: injectSpan,
+      xs,
+      sm,
+      md,
+      lg,
+      xl,
+      xxl,
+      ...injectRest
+    } = injectFormItemProps;
+
+    const initGridItemProps =
+      span || span === 0
+        ? { span }
+        : { xs, sm, md, lg, xl, xxl, span: injectSpan };
+
+    gridItemProps = fields ? { span: span ?? 24 } : initGridItemProps;
+    formItemProps = mergeProps(
+      injectRest,
+      { class: injectClassName, style: injectStyle },
+      { class: toValue(formItemClass), style: toValue(formItemStyle) },
+      formItemDataAttrs
+    );
+
+    Object.keys(rest).forEach(k => {
+      if (gridItemPropKeys.includes(k)) {
+        gridItemProps[k] = rest[k];
+      } else if (formItemPropKeys.includes(k)) {
+        formItemProps[k as keyof FormItemProps] = rest[k];
+      } else {
+        componentProps[k] = rest[k];
+      }
+    });
+
+    Object.assign(componentProps, componentDataAttrs);
+    Object.keys(slots).forEach(k => {
+      if (FORM_ITEM_SLOT_KEYS.includes(k as any)) {
+        formItemSlots[k] = slots[k];
+      } else {
+        componentProps['slots'][k] = slots[k];
+      }
+    });
+  }
+
+  return { gridItemProps, formItemProps, componentProps, formItemSlots };
+});
+</script>
+
+<template>
+  <slot v-bind="groupedAttributes"></slot>
+</template>

package/src/components/form/components/PathProvider/index.vue

@@ -0,0 +1,19 @@
+<script lang="ts" setup>
+import { computed, provide } from 'vue';
+import { InjectionPathKey } from '../../constants';
+import { NamePath } from '../../../../shared/ui';
+
+const props = defineProps<{ path?: NamePath }>();
+
+const namePath = computed(() => {
+  return Array.isArray(props.path)
+    ? props.path.join('.')
+    : (props.path as string | undefined);
+});
+
+provide(InjectionPathKey, namePath);
+</script>
+
+<template>
+  <slot :path="namePath" />
+</template>