@qin-ui/vant-pro 1.0.4 → 1.1.0

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

@@ -0,0 +1,340 @@
+<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,
+  Teleport,
+  useAttrs,
+} from 'vue';
+import { cloneDeep, omit } from '../../../../shared/core';
+import type { Field as FieldType } 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';
+import { Field as VanField } from '../../../../shared/ui';
+
+defineOptions({ name: 'BaseField', inheritAttrs: false });
+
+const uiFieldPropsKeys = Object.keys(VanField.props || {});
+
+type Props = {
+  component?: string | Component;
+  path?: string;
+};
+const { component = undefined, path = '' } = defineProps<Props>();
+
+const form = useForm(false);
+const { getFormData, setFormData, formPopup } = form;
+const { popupFieldPath, popupFieldValue } = formPopup;
+
+const componentRef = ref<any>();
+const fieldRef = ref<any>();
+
+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);
+  },
+});
+
+const popupCloseEventName = computed(() => {
+  let confirm = 'onConfirm';
+  let cancel = 'onCancel';
+  if (component === 'cascader') {
+    confirm = 'onFinish';
+    cancel = 'onClose';
+  } else if (component === 'signature') {
+    confirm = 'onSubmit';
+  }
+  return { confirm, cancel };
+});
+
+/*
+ * 将注入的默认 props、外部传入的 attrs、field 配置合并为最终属性
+ * 属性分为多类：组件绑定属性、Field UI 属性等
+ */
+const groupedAttrs = computed(() => {
+  const initProps = getInitProps({
+    component: component,
+    type: attrs.type,
+  } as unknown as FieldType);
+  const modelPropName = attrs.modelProp ?? initProps.modelProp ?? 'modelValue';
+  const mergedProps = mergeProps(
+    initProps,
+    attrs,
+    { disabled: attrs.disabled ?? initProps.disabled },
+    { modelProp: modelPropName }
+  ) as Required<FieldType>;
+
+  // prettier-ignore
+  const { valueFormatter, displayFormatter, modelProp, slots, fieldClass, fieldStyle, componentContainer, popup, ...rest } = mergedProps
+  const modelBindingProp = modelProp ?? 'modelValue';
+  // 从剩余属性中移除 v-model 绑定属性，避免重复绑定
+  const bindAttrs = omit(rest as Record<string, any>, [
+    modelBindingProp,
+    `onUpdate:${modelBindingProp}`,
+  ]);
+  if (popup) {
+    const {
+      [popupCloseEventName.value.confirm]: confirmEvent,
+      [popupCloseEventName.value.cancel]: cancelEvent,
+    } = bindAttrs as any;
+    Object.assign(bindAttrs, {
+      [popupCloseEventName.value.confirm]: (...args: any[]) => {
+        value.value = popupFieldValue.value;
+        formPopup.close();
+        confirmEvent?.(...args);
+      },
+      [popupCloseEventName.value.cancel]: (...args: any[]) => {
+        formPopup.close();
+        cancelEvent?.(...args);
+      },
+    });
+  }
+
+  const fieldAttrs = Object.keys(bindAttrs).reduce(
+    (acc, key) => {
+      if (
+        (uiFieldPropsKeys.includes(key) || key.startsWith('on')) &&
+        key !== 'type'
+      ) {
+        acc[key] = (bindAttrs as any)[key];
+      }
+      return acc;
+    },
+    { class: fieldClass, style: fieldStyle } as Record<string, any>
+  );
+
+  return {
+    attrs: bindAttrs,
+    fieldAttrs,
+    slots,
+    componentContainer,
+    modelProp: modelBindingProp,
+    valueFormatter,
+    displayFormatter,
+    popup,
+  };
+});
+
+// 从 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;
+});
+
+// 处理 Popup 相关的逻辑
+const popupAble = computed(() => !!groupedAttrs.value.popup);
+const popupContainer = computed(() =>
+  typeof groupedAttrs.value.popup === 'boolean'
+    ? undefined
+    : groupedAttrs.value.popup?.container
+);
+
+// 获取要展示在只读 Field 上的文字
+const displayValue = computed(() => {
+  const { displayFormatter } = groupedAttrs.value;
+  if (displayFormatter && typeof displayFormatter === 'function') {
+    return displayFormatter(value.value);
+  }
+  return value.value;
+});
+
+const onFieldClick = () => {
+  const attrs = groupedAttrs.value.attrs as any;
+  if (!popupAble.value || attrs.disabled || attrs.readonly) return;
+
+  const popupProps =
+    typeof groupedAttrs.value.popup === 'object'
+      ? groupedAttrs.value.popup
+      : {};
+  formPopup.updateProps(popupProps);
+  popupFieldValue.value = value.value;
+  formPopup.open(path);
+};
+
+defineExpose({
+  getComponentRef: () => componentRef.value || fieldRef.value,
+  getComponentComputedProps: () => groupedAttrs.value.attrs as any,
+});
+</script>
+
+<template>
+  <ContainerFragment :component="groupedAttrs.componentContainer" :path="path">
+    <template v-if="popupAble">
+      <VanField
+        ref="fieldRef"
+        v-bind="{
+          readonly: true,
+          clickable: true,
+          isLink: true,
+          ...groupedAttrs.fieldAttrs,
+        }"
+        :model-value="displayValue"
+        @click="onFieldClick"
+      />
+      <ContainerFragment
+        v-if="popupFieldPath === path"
+        :component="Teleport"
+        to="#pro-form-popup-content"
+        defer
+      >
+        <ContainerFragment :component="popupContainer" :path="path">
+          <component
+            :is="is"
+            v-if="is"
+            v-bind="groupedAttrs.attrs"
+            v-model:[`${groupedAttrs.modelProp}`]="popupFieldValue"
+          >
+            <template
+              v-for="(slot, name) in groupedAttrs.slots"
+              :key="name"
+              #[name]="scoped"
+            >
+              <SlotComponent :path="path" v-bind="scoped" :component="slot" />
+            </template>
+          </component>
+        </ContainerFragment>
+      </ContainerFragment>
+    </template>
+
+    <template v-else-if="typeof component === 'string'">
+      <component
+        :is="is"
+        v-if="component === 'field'"
+        v-bind="groupedAttrs.attrs"
+        ref="componentRef"
+        v-model:[`${groupedAttrs.modelProp}`]="value"
+        :name="path"
+      >
+        <template
+          v-for="(slot, name) in groupedAttrs.slots"
+          :key="name"
+          #[name]="scoped"
+        >
+          <SlotComponent :path="path" v-bind="scoped" :component="slot" />
+        </template>
+      </component>
+
+      <VanField
+        v-else
+        ref="fieldRef"
+        v-bind="groupedAttrs.fieldAttrs"
+        :name="path"
+      >
+        <template #input>
+          <component
+            :is="is"
+            v-if="is"
+            v-bind="groupedAttrs.attrs"
+            ref="componentRef"
+            v-model:[`${groupedAttrs.modelProp}`]="value"
+          >
+            <template
+              v-for="(slot, name) in groupedAttrs.slots"
+              :key="name"
+              #[name]="scoped"
+            >
+              <SlotComponent :path="path" v-bind="scoped" :component="slot" />
+            </template>
+          </component>
+        </template>
+      </VanField>
+    </template>
+
+    <template v-else>
+      <component
+        :is="is"
+        v-if="is"
+        v-bind="groupedAttrs.attrs"
+        ref="componentRef"
+        v-model:[`${groupedAttrs.modelProp}`]="value"
+      >
+        <template
+          v-for="(slot, name) in groupedAttrs.slots"
+          :key="name"
+          #[name]="scoped"
+        >
+          <SlotComponent :path="path" v-bind="scoped" :component="slot" />
+        </template>
+      </component>
+    </template>
+  </ContainerFragment>
+</template>

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

@@ -0,0 +1,14 @@
+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;
+  if (typeof component === 'string') {
+    const config = getInjectConfig(component);
+    if (!config) return {};
+    const injectProps = inject(config.injectionKey, config.default);
+    return injectProps;
+  }
+  return {};
+};

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

@@ -0,0 +1,77 @@
+<script lang="ts" setup>
+/**
+ * @component BaseFormItem
+ * @description 表单字段渲染引擎
+ *
+ * 负责将字段配置数组渲染为实际的表单项，支持：
+ * - 字段分组（嵌套 fields 递归渲染）
+ * - Field 包装（label、rules、校验等）
+ * - 组件绑定（通过 BaseField 渲染具体组件，如 Popup 选择器等）
+ * - 插槽透传（label 等 Field 插槽）
+ *
+ * ## 渲染流程
+ *
+ * 1. 遍历 fields 数组，过滤 hidden 字段
+ * 2. 对每个字段：
+ *    a. 通过 PathProvider 提供当前字段路径
+ *    b. 通过 GroupedFieldAttrs 将 field 配置拆分
+ *    c. 如果字段有 `fields` 子字段 → 递归渲染 BaseFormItem（嵌套表单）
+ *    d. 否则 → 渲染 BaseField（输入组件）
+ * 3. 通过 ref 回调收集 Field 实例，注入到 field 对象上
+ *
+ * @param {Fields<D>} [fields] - 字段配置数组
+ *
+ * @internal
+ */
+import { computed, toValue } from 'vue';
+import { toPath } from '../../../../shared/core';
+import type { Fields } from '../../types';
+import {
+  BaseField,
+  ContainerFragment,
+  GroupedFieldAttrs,
+  PathProvider,
+} from '..';
+
+defineOptions({ name: 'BaseFormItem', inheritAttrs: false });
+
+type Props = {
+  fields?: Fields;
+};
+
+const props = defineProps<Props>();
+
+const validFields = computed(() => {
+  const f = toValue(props.fields);
+  if (!Array.isArray(f)) return [];
+  return f.filter(field => !toValue(field.hidden));
+});
+</script>
+
+<template>
+  <template
+    v-for="(field, index) in validFields"
+    :key="toPath(toValue(field.path || index)).join('.') || index"
+  >
+    <PathProvider :path="toValue(field.path) as any">
+      <template #default="{ path }">
+        <GroupedFieldAttrs :field="field">
+          <template #default="{ componentProps }">
+            <template v-if="field.fields">
+              <ContainerFragment
+                :component="field.fieldContainer"
+                :path="path"
+                v-bind="componentProps"
+              >
+                <BaseFormItem :fields="field.fields" />
+              </ContainerFragment>
+            </template>
+            <template v-else>
+              <BaseField v-bind="componentProps" :path="path" />
+            </template>
+          </template>
+        </GroupedFieldAttrs>
+      </template>
+    </PathProvider>
+  </template>
+</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,51 @@
+<script lang="ts" setup>
+/**
+ * @component GroupedFieldAttrs
+ * @description 字段属性分组器，将 field 配置对象拆分为多类属性
+ *
+ * ## 属性分发逻辑
+ *
+ * 单个 field 对象包含多种属性，需要分发到不同的渲染目标：
+ *
+ * 1. **fieldAttrs** — 字段包装层属性（label、rules、required 等），传递给 VanField
+ * 2. **componentProps** — 组件属性（placeholder、clearable 等），传递给内部组件
+ * 3. **fieldSlots** — VanField 的具名插槽
+ *
+ * 分组依据：
+ * - 匹配 vant Field 的 props key → fieldAttrs
+ * - 其余所有属性 → componentProps
+ * - 属于 FIELD_SLOT_KEYS 的插槽 → fieldSlots
+ * - 其余插槽 → componentProps.slots
+ */
+import { computed } from 'vue';
+import type { Field } from '../../types';
+import { isPlainObject } from '../../../../shared/core';
+
+type Props = {
+  field: Field;
+};
+const props = defineProps<Props>();
+
+type GroupedFieldAttrs = {
+  componentProps: Record<string, any>;
+};
+
+// 将 field 配置按 key 分发到各属性分组中
+const groupedAttributes = computed<GroupedFieldAttrs>(() => {
+  let componentProps: Record<string, any> = {};
+
+  if (isPlainObject(props.field)) {
+    // prettier-ignore
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { path, formItemContainer, fields, hidden, extraProps, ...rest } =
+    props.field as any;
+    componentProps = rest;
+  }
+
+  return { componentProps };
+});
+</script>
+
+<template>
+  <slot v-bind="groupedAttributes"></slot>
+</template>

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

@@ -0,0 +1,18 @@
+<script lang="ts" setup>
+import { computed, provide } from 'vue';
+import { InjectionPathKey } from '../../constants';
+
+const props = defineProps<{ path?: string | number | (string | number)[] }>();
+
+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>

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

@@ -0,0 +1,114 @@
+<script lang="ts" setup generic="F extends Form<any> = Form">
+/**
+ * @component ProForm
+ * @description @qin-ui/vant-pro 配置驱动表单组件（移动端）
+ *
+ * 架构设计说明 (Architecture Overview)
+ *
+ * [ 数据层 (Core) ]  =>  [ 绑定层 (ProForm) ]  =>  [ 渲染层 (BaseFormItem / BaseField) ]
+ *
+ * 1. 数据隔离：ProForm 本身不负责存储和管理表单状态，所有核心状态（formData, fields, 校验规则）
+ *    均交由底层的 `useForm`（@qin-ui/pro-components-core）驱动。
+ * 2. 上下文透传：通过 `provide` 将核心状态下发给子组件，避免了深层嵌套的 Props 传递。
+ * 3. 递归渲染：具体字段的解析交由 `<BaseFormItem>` 递归完成，实现了 UI 布局与表单逻辑的解耦。
+ *
+ * 通过配置驱动的方式快速构建移动端表单，支持：
+ * - 字段联动、嵌套字段、自定义组件
+ * - 弹出层表单（Popup，适用于移动端选择器场景）
+ *
+ * @template F - 表单实例类型
+ * @param {Form<D>} [form] - useForm 返回的表单实例
+ *
+ * @slot default - 默认插槽
+ * @slot [path] - 以字段 path 命名的动态插槽
+ 
+ * @public
+ */
+import { Form as VanForm, Popup } from '../../../../shared/ui';
+import {
+  inject,
+  mergeProps,
+  provide,
+  type Slot,
+  watchEffect,
+  toValue,
+  computed,
+} from 'vue';
+import { INJECT_CONFIG } from '../../../component-provider/constants';
+import { BaseFormItem } from '..';
+import { InjectionFormKey, TeleportComponentNamePrefix } from '../../constants';
+import type { VModelProps, PathProps } from '../../types';
+import { Path, camelizeProperties } from '../../../../shared/core';
+import type { Form } from '../../hooks/useForm';
+import { useForm } from '../../hooks/useForm';
+
+defineOptions({ name: 'ProForm', inheritAttrs: false });
+
+type Props = { form?: F };
+const props = defineProps<Props>();
+
+const form = props.form || (useForm(true) as F);
+
+/**
+ * 依赖注入中心：
+ * 将 Core 包生成的 Form 实例注入到 Vue 的 Context 中。
+ * 供深层子组件（如 BaseFormItem, BaseField, 自定义插槽）跨层级直接访问数据和方法。
+ */
+provide(InjectionFormKey, form as F);
+
+const { fields, setFormRef, formPopup } = form as F;
+
+const formFields = computed(() => {
+  const f = toValue(fields);
+  return Array.isArray(f) ? f : [];
+});
+
+const config = INJECT_CONFIG['pro-form'];
+const injectAttrs = inject(config.injectionKey, config.default);
+
+type ExtractPath<T> = T extends Form<infer D> ? Path<D> : string;
+type FieldSlotProps = VModelProps &
+  PathProps & { disabled?: boolean; [x: string]: any };
+type FieldSlots = Record<ExtractPath<F>, Slot<FieldSlotProps>>;
+
+const slots = defineSlots<Partial<FieldSlots & { default: Slot }>>();
+/**
+ * 动态插槽映射中心 (Slot Teleporting)：
+ * 目的：将 ProForm 上以 Field Path 命名的插槽，动态注册为全局可访问的 Context。
+ * 实现：BaseField 组件在渲染对应字段时，会通过 inject 尝试获取对应的 Prefix+Path，
+ *      如果存在，则将插槽内容渲染到深层的具体位置，从而突破了组件嵌套层级的限制。
+ */
+watchEffect(() => {
+  Object.keys(slots).forEach(name => {
+    if (name === 'default') return;
+    provide(`${TeleportComponentNamePrefix}${name}`, (slots as any)[name]);
+  });
+});
+
+const popupProps = computed(() => {
+  // 从 ProComponentProvider 获取全局配置，与传入的 props 合并
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { container, ...rest } = formPopup.props;
+  return rest;
+});
+</script>
+
+<template>
+  <VanForm
+    :ref="(el: any) => setFormRef?.(el)"
+    v-bind="mergeProps(injectAttrs, camelizeProperties($attrs))"
+    class="pro-form"
+  >
+    <BaseFormItem :fields="formFields" />
+
+    <Popup
+      v-bind="popupProps"
+      :show="formPopup.visible.value"
+      @close="formPopup.close"
+    >
+      <div id="pro-form-popup-content"></div>
+    </Popup>
+
+    <slot />
+  </VanForm>
+</template>

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

@@ -0,0 +1,26 @@
+<script lang="ts" setup>
+/**
+ * @component SlotComponent
+ * @description 插槽渲染辅助组件。用于在表单或表格的自定义插槽中动态渲染外部传入的 VNode、渲染函数或静态字符串。
+ *
+ * @public
+ */
+import { isVNode } from 'vue';
+import { SlotComponentType } from '../../types';
+
+defineOptions({ name: 'SlotComponent', inheritAttrs: false });
+
+type Props = {
+  component?: SlotComponentType;
+};
+defineProps<Props>();
+</script>
+
+<template>
+  <component
+    :is="component"
+    v-if="isVNode(component) || typeof component === 'function'"
+    v-bind="$attrs"
+  />
+  <template v-else>{{ component }}</template>
+</template>

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

@@ -0,0 +1,15 @@
+import { ComponentProps, ComponentExposed } from 'vue-component-type-helpers';
+import ProForm from './ProForm/index.vue';
+
+export { default as BaseField } from './BaseField/index.vue';
+export { default as ContainerFragment } from './ContainerFragment/index.vue';
+export { default as SlotComponent } from './SlotComponent/index.vue';
+export { default as PathProvider } from './PathProvider/index.vue';
+export { default as GroupedFieldAttrs } from './GroupedFieldAttrs/index.vue';
+export { default as BaseFormItem } from './BaseFormItem/index.vue';
+
+export { ProForm };
+
+// instance
+export type ProFormInstance = ComponentExposed<typeof ProForm>;
+export type ProFormProps = ComponentProps<typeof ProForm>;