@qin-ui/vant-pro 1.0.4 → 1.1.0

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

@@ -0,0 +1,109 @@
+import {
+  Field,
+  Button,
+  Picker,
+  DatePicker,
+  TimePicker,
+  Cascader,
+  Area,
+  Signature,
+  Switch,
+  Stepper,
+  Rate,
+  Slider,
+  Uploader,
+  CheckboxGroup,
+  RadioGroup,
+} from '../../../shared/ui';
+
+/**
+ * 内置组件映射表
+ * @description Vant 内置支持的组件类型映射
+ */
+export type BaseComponentMap = {
+  field: typeof Field;
+  switch: typeof Switch;
+  stepper: typeof Stepper;
+  rate: typeof Rate;
+  slider: typeof Slider;
+  uploader: typeof Uploader;
+  'checkbox-group': typeof CheckboxGroup;
+  'radio-group': typeof RadioGroup;
+  picker: typeof Picker;
+  'date-picker': typeof DatePicker;
+  'time-picker': typeof TimePicker;
+  cascader: typeof Cascader;
+  area: typeof Area;
+  signature: typeof Signature;
+  button: typeof Button;
+};
+
+/**
+ * 组件映射扩展接口
+ * @description 通过 TypeScript 声明合并添加自定义组件
+ *
+ * @example
+ * ```ts
+ * declare module '@qin-ui/vant-pro' {
+ *   interface ComponentMap {
+ *     'my-custom': typeof MyComponent;
+ *   }
+ * }
+ * ```
+ 
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface ComponentMap {}
+
+/**
+ * 组件名称联合类型
+ * @description 所有支持的组件名称
+ 
+ * @public
+ */
+export type ComponentName =
+  | keyof BaseComponentMap
+  | keyof ComponentMap
+  | 'custom';
+
+/**
+ * 根据组件名获取组件类型
+ * @template K - 组件名称
+ */
+export type GetComponentType<K extends ComponentName> =
+  K extends keyof ComponentMap
+    ? ComponentMap[K]
+    : K extends keyof BaseComponentMap
+      ? BaseComponentMap[K]
+      : never;
+
+/**
+ * 组件名称到 Vant 组件的映射
+ */
+export const componentMap: BaseComponentMap = {
+  field: Field,
+  switch: Switch,
+  stepper: Stepper,
+  rate: Rate,
+  slider: Slider,
+  uploader: Uploader,
+  'checkbox-group': CheckboxGroup,
+  'radio-group': RadioGroup,
+  picker: Picker,
+  'date-picker': DatePicker,
+  'time-picker': TimePicker,
+  cascader: Cascader,
+  area: Area,
+  signature: Signature,
+  button: Button,
+};
+
+/**
+ * Teleport 组件名称前缀
+ * @description 用于通过插槽动态替换指定 path 的组件
+ */
+export const TeleportComponentNamePrefix = 'TeleportComponent_';
+
+// inject keys
+export { InjectionFormKey, InjectionPathKey } from '../../../shared/core';

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

@@ -0,0 +1,6 @@
+export * from './useForm';
+export * from './useFields';
+export * from './useFormRef';
+export * from './useFormPopup';
+
+export { useFormData } from '../../../shared/core';

package/src/components/form/hooks/useFields.ts

@@ -0,0 +1,67 @@
+import { FieldInstance } from '../../../shared/ui';
+import {
+  useFields as coreUseFields,
+  type UseFieldsReturn,
+} from '../../../shared/core';
+import type { Data } from '../../../shared/core';
+import type { Field, Fields } from '../types';
+import type { ComponentName } from '../constants';
+
+/**
+ * 字段配置管理 Hook
+ *
+ * @description 基于 `@qin-ui/pro-components-core` 的 `useFields`，将泛型参数绑定为 Vant 的本地类型：
+ * - 字段类型 F -> `Field<ComponentName, D>`（支持 Vant 组件类型推导）
+ * - Field 实例 -> Vant 的 `FieldInstance`
+ *
+ * 提供对字段配置数组的增删改查操作，支持：
+ * - 通过路径字符串或查找函数定位字段
+ * - 深层嵌套字段的遍历和匹配
+ * - 字段配置的合并/覆盖更新
+ * - 字段的添加、插入、删除
+ * - 父级字段查找
+ *
+ * @template D - 表单数据类型
+ * @param {Fields<D>} [initFields] - 初始字段配置数组
+ *
+ * @returns 字段操作对象，包含以下属性：
+ * - `fields` - 字段配置数组（响应式 Ref\<F[]\>）
+ * - `getField(path)` - 获取字段配置，支持路径字符串或查找函数
+ * - `setField(path, field, options?)` - 更新字段配置，默认合并模式
+ * - `deleteField(path, options?)` - 删除字段配置
+ * - `appendField(path, field, options?)` - 在指定字段后追加
+ * - `prependField(path, field, options?)` - 在指定字段前插入
+ * - `getParentField(path, options?)` - 获取父级字段配置
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number }
+ *
+ * const { fields, getField, setField } = useFields<User>([
+ *   { path: 'name', label: '姓名', component: 'field' },
+ *   { path: 'age', label: '年龄', component: 'stepper' },
+ * ])
+ *
+ * // 通过路径获取
+ * getField('name')
+ * // 通过查找函数获取
+ * getField(f => f.label === '姓名')
+ * // 更新字段（合并模式）
+ * setField('name', { label: '用户名', disabled: true })
+ * ```
+ *
+ * @see {@link coreUseFields} 底层核心实现（来自 @qin-ui/pro-components-core）
+ *
+ * @public
+ */
+export function useFields<D extends Data = Data>(
+  initFields?: Fields<D>
+): UseFieldsReturn<D, Field<ComponentName, D>, FieldInstance>;
+export function useFields(initFields?: any) {
+  return coreUseFields(initFields);
+}
+
+/** useFields 返回值类型
+ * @public
+ */
+export type UseFields<D extends Data = Data> = ReturnType<typeof useFields<D>>;

package/src/components/form/hooks/useForm.ts

@@ -0,0 +1,126 @@
+import {
+  useForm as coreUseForm,
+  type Form as _Form,
+} from '../../../shared/core';
+import type { Data, ExtendWithAny, DeepPartial } from '../../../shared/core';
+import type { Field } from '../types';
+import type { ComponentName } from '../constants';
+import type { FormInstance } from '../../../shared/ui';
+import { useFormPopup, type FormPopup } from './useFormPopup';
+
+/**
+ * 表单实例类型
+ *
+ * @description 在 core Form 类型的基础上，将字段类型 F 绑定为本地 Field<ComponentName, D>，
+ * 将底层表单实例 I 绑定为 Vant 的 FormInstance，使 formRef 获得完整的类型提示。
+ * 额外包含 formPopup 对象，用于管理弹出层表单。
+ *
+ * @template D - 表单数据类型
+ * @template F - 字段配置类型，默认使用本地 Field 类型
+ *
+ * @property formData  - 响应式表单数据对象，可直接读写，支持深层路径如 `formData.address.city`
+ * @property getFormData - 获取指定路径的表单数据，支持点号分隔的深层路径，如 `getFormData('address.city')`
+ * @property setFormData - 设置表单数据，支持三种调用方式：<br>
+ *   1. `setFormData(path, value)` - 设置指定路径的值<br>
+ *   2. `setFormData(path, prev => newVal)` - 函数式更新<br>
+ *   3. `setFormData({ ... })` - 批量覆盖整个表单
+ * @property fields      - 字段配置数组（响应式 Ref），ProForm 根据此数组渲染表单字段
+ * @property getField     - 获取字段配置，支持路径字符串（如 `'name'`）或查找函数（如 `f => f.label === '姓名'`）
+ * @property setField     - 更新字段配置，默认合并模式（Object.assign），可通过 `{ updateType: 'rewrite' }` 覆盖
+ * @property deleteField  - 删除字段配置，支持 `{ all: true }` 批量删除所有匹配项
+ * @property appendField  - 在指定字段后追加新字段，传 `undefined` 则在末尾追加
+ * @property prependField - 在指定字段前插入新字段，传 `undefined` 则在开头插入
+ * @property getParentField - 获取指定字段的父级字段配置，用于嵌套字段场景
+ * @property formRef      - 底层 Vant Form 组件实例的响应式引用（Ref），可调用 `validate()`、`resetValidation()` 等方法
+ * @property setFormRef   - 设置底层 Form 组件实例，由 ProForm 内部自动调用，一般无需手动使用
+ * @property formPopup    - 弹出层表单管理对象，提供 `open(path)`、`close()` 等方法，用于移动端弹窗表单
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number }
+ * const form: Form<User> = useForm({ name: '张三', age: 25 })
+ *
+ * form.formData.name           // 直接读写响应式数据
+ * form.getFormData('name')     // 通过路径读取
+ * form.setFormData('name', '李四')  // 更新数据
+ * form.formRef.value?.validate()    // 访问底层 Form 实例
+ * form.formPopup.open('address')    // 打开弹出层表单
+ * ```
+ *
+ * @public
+ */
+export type Form<
+  D extends Data = Data,
+  F extends Field<ComponentName, D> = Field<ComponentName, D>,
+> = _Form<D, F, FormInstance> & { formPopup: FormPopup };
+
+/**
+ * 创建表单实例的 Hook
+ *
+ * @description 基于 `@qin-ui/pro-components-core` 的 `useForm`，将泛型参数绑定为 Vant 的本地类型：
+ * - 字段类型 F -> `Field<ComponentName, D>`（支持 Vant 组件类型推导）
+ * - 表单实例 -> Vant 的 `FormInstance`（使 formRef 获得完整的类型提示）
+ *
+ * 在 core useForm 基础上额外提供 formPopup，用于移动端弹窗表单场景。
+ *
+ * 表单实例组合了四个子模块的能力：
+ * - **useFormData**：表单数据管理（响应式数据、读写、批量更新）
+ * - **useFields**：字段配置管理（增删改查字段配置，支持嵌套）
+ * - **useFormRef**：底层 Form 组件实例引用
+ * - **useFormPopup**：弹出层表单管理（Vant 专属）
+ *
+ * @template D - 表单数据类型
+ *
+ * @param {ExtendWithAny<DeepPartial<D>>} [initFormData] - 初始表单数据
+ * @param {Field<ComponentName, D>[]} [initFields] - 初始字段配置数组
+ * @param {boolean} [root=true] - 是否为根表单。设为 `false` 时尝试从父组件注入获取表单实例
+ *
+ * @returns {Form<D>} 表单实例，包含数据操作、字段操作、ref 操作和弹出层管理
+ *
+ * @example
+ * ```ts
+ * interface User { name: string; age: number }
+ *
+ * // 方式一：同时传入初始数据和字段
+ * const form = useForm<User>(
+ *   { name: '张三', age: 25 },
+ *   [
+ *     { path: 'name', label: '姓名', component: 'field' },
+ *   ],
+ *   true
+ * )
+ *
+ * // 方式二：仅设置 root 标识
+ * const form = useForm<User>(true)
+ *
+ * // 使用
+ * const { formData, formRef, fields, setFormData, formPopup } = form
+ * setFormData('name', '李四')
+ * formPopup.open('address') // 打开弹出层表单
+ * ```
+ *
+ * @see {@link coreUseForm} 底层核心实现（来自 @qin-ui/pro-components-core）
+ *
+ * @public
+ */
+export function useForm<D extends Data = Data>(
+  initFormData?: ExtendWithAny<DeepPartial<D>>,
+  initFields?: Field<ComponentName, D>[],
+  root?: boolean
+): Form<D, Field<ComponentName, D>>;
+export function useForm<D extends Data = Data>(
+  root?: boolean
+): Form<D, Field<ComponentName, D>>;
+export function useForm(...args: any[]) {
+  let root = true;
+  if (args.length === 1) {
+    root = args[0] as boolean;
+  } else if (args.length >= 2) {
+    root = (args[2] as boolean) ?? root;
+  }
+
+  const form = coreUseForm(...args);
+  const formPopup = useFormPopup(root);
+
+  return { ...form, formPopup };
+}

package/src/components/form/hooks/useFormPopup.ts

@@ -0,0 +1,111 @@
+import {
+  computed,
+  ComputedRef,
+  inject,
+  provide,
+  reactive,
+  Ref,
+  ref,
+} from 'vue';
+import { Popup } from '../../../shared/ui';
+import { ComponentProps } from 'vue-component-type-helpers';
+import { ContainerComponent } from '../types';
+
+/**
+ * Vant Popup 组件属性类型
+ * @description 用于配置表单弹出层的属性
+ 
+ * @public
+ */
+export type PopupProps = ComponentProps<typeof Popup> & {
+  container: ContainerComponent;
+};
+
+/**
+ * 表单弹出层管理对象
+ * @description Vant 移动端特有的表单弹出层功能
+ 
+ * @public
+ */
+export type FormPopup = {
+  /** Popup 组件属性 */
+  props: PopupProps;
+  /** 打开指定路径字段的弹出层 */
+  open: (path: string) => void;
+  /** 关闭弹出层 */
+  close: () => void;
+  /** 更新 Popup 组件属性 */
+  updateProps: (props: Partial<PopupProps>) => void;
+  /** 弹出层是否可见 */
+  visible: ComputedRef<boolean>;
+  /** 当前弹出层对应的字段路径 */
+  popupFieldPath: Ref<string | undefined>;
+  /** 当前弹出层字段的值 */
+  popupFieldValue: Ref<any | undefined>;
+};
+
+/** 弹出层注入 key */
+export const InjectionPopupKey = Symbol('form-popup');
+
+/**
+ * @qin-ui/vant-pro 表单弹出层管理 Hook
+ *
+ * @description 用于管理 Vant 移动端的表单弹出层（Popup）。
+ * 在移动端表单中，某些字段（如地址选择、日期选择）需要以弹出层形式展示。
+ *
+ * @returns {FormPopup} 弹出层管理对象
+ *
+ * @example
+ * ```ts
+ * const formPopup = useFormPopup(true)
+ * formPopup.open('address') // 打开地址选择弹出层
+ * formPopup.close()         // 关闭
+ * formPopup.updateProps({ position: 'top' })
+ * ```
+ 
+ * @public
+ */
+export function useFormPopup(root?: boolean): FormPopup;
+
+export function useFormPopup(initRoot?: boolean) {
+  if (!initRoot) {
+    const injectStore = inject(InjectionPopupKey, undefined);
+    if (injectStore) return injectStore as never;
+  }
+
+  const props = reactive<Partial<PopupProps>>({
+    safeAreaInsetBottom: true,
+    position: 'bottom',
+    round: true,
+  });
+
+  const popupFieldPath = ref<string>();
+  const popupFieldValue = ref();
+
+  function open(path: string) {
+    popupFieldPath.value = path;
+  }
+
+  function close() {
+    popupFieldPath.value = undefined;
+    popupFieldValue.value = undefined;
+  }
+
+  const visible = computed(() => !!popupFieldPath.value);
+
+  function updateProps(_props: Partial<PopupProps>) {
+    Object.assign(props, _props);
+  }
+
+  const store = {
+    props,
+    open,
+    close,
+    updateProps,
+    visible,
+    popupFieldPath,
+    popupFieldValue,
+  };
+  provide(InjectionPopupKey, store);
+  return store;
+}

package/src/components/form/hooks/useFormRef.ts

@@ -0,0 +1,35 @@
+import {
+  useFormRef as coreUseFormRef,
+  type UseFormRefReturn,
+} from '../../../shared/core';
+import type { FormInstance } from '../../../shared/ui';
+
+/**
+ * 表单组件实例引用 Hook
+ *
+ * @description 基于 `@qin-ui/pro-components-core` 的 `useFormRef`，将泛型参数绑定为 Vant 的 `FormInstance`，
+ * 使 formRef 获取到完整的 Vant Form 组件 API 类型提示（如 `validate()`、`resetValidation()` 等）。
+ *
+ * `formRef` 由 ProForm 组件内部自动通过 `setFormRef` 绑定，无需手动调用。
+ *
+ * @returns 表单组件实例引用管理对象：
+ * - `formRef` — Vant Form 组件实例的响应式引用（`Ref<FormInstance | undefined>`）
+ * - `setFormRef(inst)` — 设置 Form 组件实例，由 ProForm 内部自动调用
+ *
+ * @example
+ * ```ts
+ * const { formRef, setFormRef } = useFormRef()
+ *
+ * // formRef 由 ProForm 自动绑定，可直接使用
+ * await formRef.value?.validate()
+ * formRef.value?.resetValidation()
+ * formRef.value?.scrollToField('username')
+ * ```
+ *
+ * @see {@link coreUseFormRef} 底层核心实现（来自 @qin-ui/pro-components-core）
+ *
+ * @public
+ */
+export function useFormRef(): UseFormRefReturn<FormInstance> {
+  return coreUseFormRef();
+}

package/src/components/form/index.ts

@@ -0,0 +1,27 @@
+import ProForm from './components/ProForm/index.vue';
+
+// 1. 仅导出核心 Vue 组件包装及外部可重用组件与类型
+export {
+  ContainerFragment,
+  SlotComponent,
+  type ProFormProps,
+  type ProFormInstance,
+} from './components';
+
+// 2. 仅导出允许模块合并扩展的 ComponentMap 以及组件名类型
+export { type ComponentMap, type ComponentName } from './constants';
+
+// 3. 仅导出核心表单配置 Schema 类型
+export { type Field, type Fields } from './types';
+
+// 4. 仅导出核心业务 Hooks
+export {
+  useForm,
+  useFields,
+  useFormRef,
+  useFormData,
+  type Form,
+  type UseFields,
+} from './hooks';
+
+export default ProForm;

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

@@ -0,0 +1,220 @@
+import { type FormInstance, type FieldProps } from '../../../shared/ui';
+import type {
+  ComponentProps,
+  ComponentSlots,
+} from 'vue-component-type-helpers';
+import {
+  type CSSProperties,
+  type Component,
+  type Raw,
+  type MaybeRef,
+  type ComputedRef,
+  VNodeProps,
+  DefineComponent,
+  VNodeTypes,
+  VNode,
+} from 'vue';
+import { ComponentName, GetComponentType } from '../constants';
+import type { Data, Path } from '../../../shared/core';
+import { PopupProps } from '../hooks/useFormPopup';
+
+export type { FormInstance };
+
+export type PathProps = { path?: string } & Data;
+
+export type VModelProps<T = any> = {
+  modelValue?: T;
+  'onUpdate:modelValue'?: (val: T) => void;
+};
+
+export type ValueFormatter =
+  | { (val: any, oldVal: any): any }
+  | { get?: (val: any) => any; set?: (val: any, oldVal: any) => any };
+
+export type DisplayFormatter = (val: any) => string;
+
+/**
+ * @description 自定义组件
+ */
+export type RenderComponentType = Component<VModelProps & PathProps>;
+
+/**
+ * @description 插槽组件类型
+ */
+export type SlotComponentType =
+  | Component<PathProps>
+  | VNode
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | ((...args: any[]) => SlotComponentType);
+
+/**
+ * @description 容器组件类型
+ */
+export type ContainerComponent =
+  | Component<PathProps>
+  | DefineComponent<PathProps>
+  | VNodeTypes
+  | symbol;
+
+/**
+ * @description 插槽对象类型
+ */
+export type Slots = {
+  [name: string]: SlotComponentType;
+};
+
+type BaseCommon<D extends Data = Data> = {
+  /**
+   * @description 字段标识namePath, 同name
+   */
+  path?: Path<D>;
+  /**
+   * @description 字段是否隐藏
+   */
+  hidden?: boolean;
+  /**
+   * @description 字段是否禁用
+   */
+  disabled?: boolean;
+  /**
+   * @description 字段中文名称，支持字符串或组件
+   */
+  label?: SlotComponentType;
+  /**
+   * @description 字段插槽配置
+   */
+  slots?: Slots;
+  /**
+   * @description 嵌套 fields 容器包裹组件
+   */
+  fieldContainer?: ContainerComponent;
+  /**
+   * @description 额外的自定义属性，不会被当作组件参数
+   */
+  extraProps?: Record<string, any>;
+};
+
+type BaseWithFields<D extends Data = Data> = BaseCommon<D> & {
+  /**
+   * @description 嵌套子字段配置 (Vant 中主要用于分组，或者通过 CellGroup 包裹)
+   */
+  fields: Fields<D>;
+  component?: never;
+  componentStyle?: never;
+  componentClass?: never;
+  componentContainer?: never;
+  fieldStyle?: never;
+  fieldClass?: never;
+  valueFormatter?: never;
+  displayFormatter?: never;
+  modelProp?: never;
+  popup?: never;
+};
+
+type BaseWithoutFields<D extends Data = Data> = BaseCommon<D> & {
+  fields?: undefined;
+  /**
+   * @description 表单字段component样式属性
+   */
+  componentStyle?: CSSProperties;
+  /**
+   * @description 表单字段component样式类名
+   */
+  componentClass?: any;
+  /**
+   * @description 表单字段外层 van-field 样式属性
+   */
+  fieldStyle?: CSSProperties;
+  /**
+   * @description 表单字段外层 van-field 样式类名
+   */
+  fieldClass?: any;
+  /**
+   * @description 字段component容器包裹组件
+   */
+  componentContainer?: ContainerComponent;
+  /**
+   * @description 字段值处理函数，在onUpdateValue前执行
+   */
+  valueFormatter?: ValueFormatter;
+  /**
+   * @description 针对 Popup 展现形式的组件，将选中值转化为输入框展示文字
+   */
+  displayFormatter?: DisplayFormatter;
+  /**
+   * @description 组件v-model双向绑定更新属性名
+   */
+  modelProp?: string;
+  /**
+   * @description 是否通过 Popup 弹窗展示该组件（为 true 或传递 PopupProps 配置对象时开启）
+   */
+  popup?: boolean | Partial<PopupProps>;
+};
+
+export type Base<D extends Data = Data> =
+  | BaseWithFields<D>
+  | BaseWithoutFields<D>;
+
+/**
+ * @type {FieldTypeMap} 字段类型集合
+ */
+export type FieldTypeMap<D extends Data = Data> = {
+  [K in ComponentName]: K extends 'custom'
+    ? WithCommon<{ slots?: Slots; [x: string]: any }, D> & {
+        component?: RenderComponentType | Raw<RenderComponentType>;
+      }
+    : WithComponent<GetComponentType<K>, D> & { component?: K };
+};
+
+type NotSupportedRefOrGetterProps =
+  | 'component'
+  | 'fieldContainer'
+  | 'componentContainer'
+  | 'valueFormatter'
+  | 'displayFormatter'
+  | 'fields'
+  | 'slots'
+  | 'modelProp'
+  | 'popup';
+
+type MaybeRefOrComputedRef<T = any> = MaybeRef<T> | ComputedRef<T>;
+
+export type WithRef<T> = {
+  [P in keyof T]: P extends NotSupportedRefOrGetterProps
+    ? T[P]
+    : T[P] extends (...args: any[]) => any
+      ? T[P]
+      : MaybeRefOrComputedRef<T[P]>;
+};
+
+type WithCommonBase<T = unknown> = T &
+  Partial<Omit<FieldProps, 'label' | 'name' | 'type'>>;
+
+type WithCommon<T, D extends Data = Data> = WithRef<
+  WithCommonBase<T> & BaseWithoutFields<D>
+>;
+
+type WithFields<D extends Data = Data> = WithRef<
+  WithCommonBase & BaseWithFields<D>
+>;
+
+type WithComponent<
+  T extends abstract new (...args: any) => any,
+  D extends Data = Data,
+> = WithCommon<
+  { slots?: Partial<ComponentSlots<T>> } & Partial<
+    Omit<ComponentProps<T>, keyof VNodeProps>
+  >,
+  D
+>;
+
+export type Field<
+  C extends ComponentName = ComponentName,
+  D extends Data = Data,
+> = FieldTypeMap<D>[C] | WithFields<D>;
+
+export type Fields<D extends Data = Data> = Array<Field<ComponentName, D>>;