@qin-ui/antdv-next-pro 1.1.14 → 1.2.0

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

@@ -0,0 +1,140 @@
+import {
+  Cascader,
+  CheckboxGroup,
+  DatePicker,
+  AutoComplete,
+  Input,
+  InputNumber,
+  InputPassword,
+  InputSearch,
+  RadioGroup,
+  Select,
+  Slider,
+  Switch,
+  TextArea,
+  TimePicker,
+  TimeRangePicker,
+  Transfer,
+  TreeSelect,
+  RangePicker,
+  InputOTP,
+} from '../../../shared/ui';
+
+/**
+ * FormItem 插槽名称列表
+ * @description 用于在字段配置中透传 FormItem 的插槽
+ */
+// prettier-ignore
+export const FORM_ITEM_SLOT_KEYS = ['label', 'extra', 'help', 'tooltip'] as const;
+
+/**
+ * 内置组件映射表
+ * @description antdv-next 内置支持的组件类型映射。
+ * 每个 key 对应 Field 配置中 `component` 可使用的字符串值，
+ * value 为实际渲染的 antdv-next 组件。
+ *
+ * @public
+ */
+// prettier-ignore
+export type BaseComponentMap = {
+  'input': typeof Input;
+  'textarea': typeof TextArea;
+  'input-search': typeof InputSearch;
+  'input-password': typeof InputPassword;
+  'input-number': typeof InputNumber;
+  'input-otp': typeof InputOTP;
+  'auto-complete': typeof AutoComplete;
+  'select': typeof Select;
+  'cascader': typeof Cascader;
+  'date-picker': typeof DatePicker;
+  'range-picker': typeof RangePicker;
+  'time-picker': typeof TimePicker;
+  'time-range-picker': typeof TimeRangePicker;
+  'checkbox-group': typeof CheckboxGroup;
+  'radio-group': typeof RadioGroup;
+  'switch': typeof Switch;
+  'slider': typeof Slider;
+  'tree-select': typeof TreeSelect;
+  'transfer': typeof Transfer;
+}
+
+/**
+ * 组件映射扩展接口
+ * @description 暴露给外部扩充自定义组件类型的接口。
+ * 用户可通过 TypeScript 的声明合并（module augmentation）添加自定义组件。
+ *
+ * @example
+ * ```ts
+ * // 在项目中任意 .d.ts 文件中
+ * declare module '@qin-ui/antdv-next-pro' {
+ *   interface ComponentMap {
+ *     'my-custom-input': typeof MyCustomInput;
+ *   }
+ * }
+ * ```
+ 
+ * @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;
+
+/**
+ * 组件名称到 antdv-next 组件的运行时映射
+ * @description ProForm 通过此映射将 Field 配置中的 component 字符串解析为实际 Vue 组件。
+ * 例如 `component: 'input'` → `Input`, `component: 'select'` → `Select`。
+ *
+ * @public
+ */
+// prettier-ignore
+export const componentMap: BaseComponentMap = {
+  'input': Input,
+  'textarea': TextArea,
+  'input-search': InputSearch,
+  'input-password': InputPassword,
+  'input-number': InputNumber,
+  'input-otp': InputOTP,
+  'auto-complete': AutoComplete,
+  'select': Select,
+  'cascader': Cascader,
+  'date-picker': DatePicker,
+  'range-picker': RangePicker,
+  'time-picker': TimePicker,
+  'time-range-picker': TimeRangePicker,
+  'checkbox-group': CheckboxGroup,
+  'radio-group': RadioGroup,
+  'switch': Switch,
+  'slider': Slider,
+  'tree-select': TreeSelect,
+  'transfer': Transfer,
+}
+
+/**
+ * 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,5 @@
+export * from './useForm';
+export * from './useFields';
+export * from './useFormRef';
+
+export { useFormData } from '../../../shared/core';

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

@@ -0,0 +1,67 @@
+import { FormItemInstance } 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`，将泛型参数绑定为 antdv-next 的本地类型：
+ * - 字段类型 F → `Field<ComponentName, D>`（支持 antdv-next 组件类型推导）
+ * - FormItem 实例 → antdv-next 的 `FormItemInstance`
+ *
+ * 提供对字段配置数组的增删改查操作，支持：
+ * - 通过路径字符串或查找函数定位字段
+ * - 深层嵌套字段的遍历和匹配
+ * - 字段配置的合并/覆盖更新
+ * - 字段的添加、插入、删除
+ * - 父级字段查找
+ *
+ * @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: 'input' },
+ *   { path: 'age', label: '年龄', component: 'input-number' },
+ * ])
+ *
+ * // 通过路径获取
+ * 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>, FormItemInstance>;
+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,110 @@
+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';
+
+/**
+ * 表单实例类型
+ *
+ * @description 在 core Form 类型的基础上，将字段类型 F 绑定为本地 Field<ComponentName, D>，
+ * 将底层表单实例 I 绑定为 antdv-next 的 FormInstance，使 formRef 获得完整的类型提示。
+ *
+ * @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      - 底层 antdv-next Form 组件实例的响应式引用（Ref），可调用 `validate()`、`resetFields()` 等方法
+ * @property setFormRef   - 设置底层 Form 组件实例，由 ProForm 内部自动调用，一般无需手动使用
+ *
+ * @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 实例
+ * ```
+ *
+ * @public
+ */
+export type Form<
+  D extends Data = Data,
+  F extends Field<ComponentName, D> = Field<ComponentName, D>,
+> = _Form<D, F, FormInstance>;
+
+/**
+ * 创建表单实例的 Hook
+ *
+ * @description 基于 `@qin-ui/pro-components-core` 的 `useForm`，将泛型参数绑定为 antdv-next 的本地类型：
+ * - 字段类型 F → `Field<ComponentName, D>`（支持 antdv-next 所有内置组件类型推导）
+ * - 表单实例 → antdv-next 的 `FormInstance`（使 formRef 获得完整的类型提示）
+ *
+ * 表单实例组合了三个子模块的能力：
+ * - **useFormData**：表单数据管理（响应式数据、读写、批量更新）
+ * - **useFields**：字段配置管理（增删改查字段配置，支持嵌套）
+ * - **useFormRef**：底层 Form 组件实例引用
+ *
+ * @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: 'input' },
+ *     { path: 'age', label: '年龄', component: 'input-number' },
+ *   ],
+ *   true
+ * )
+ *
+ * // 方式二：仅设置 root 标识
+ * const form = useForm<User>(true)
+ *
+ * // 使用
+ * const { formData, formRef, fields, setFormData, getField } = form
+ * setFormData('name', '李四')
+ * await formRef.value?.validate()
+ * ```
+ *
+ * @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[]) {
+  return coreUseForm(...(args as any));
+}

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`，将泛型参数绑定为 antdv-next 的 `FormInstance`，
+ * 使 formRef 获取到完整的 antdv-next Form 组件 API 类型提示（如 `validate()`、`resetFields()` 等）。
+ *
+ * `formRef` 由 ProForm 组件内部自动通过 `setFormRef` 绑定，无需手动调用。
+ *
+ * @returns 表单组件实例引用管理对象：
+ * - `formRef` — antdv-next Form 组件实例的响应式引用（`Ref<FormInstance | undefined>`）
+ * - `setFormRef(inst)` — 设置 Form 组件实例，由 ProForm 内部自动调用
+ *
+ * @example
+ * ```ts
+ * const { formRef, setFormRef } = useFormRef()
+ *
+ * // formRef 由 ProForm 自动绑定，可直接使用
+ * await formRef.value?.validate()
+ * formRef.value?.resetFields()
+ * 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,29 @@
+import ProForm from './components/ProForm/index.vue';
+
+// 1. 仅导出核心 Vue 组件包装及外部可重用组件与类型
+export {
+  ContainerFragment,
+  SlotComponent,
+  type ProFormProps,
+  type ProFormInstance,
+  type ProFormItemProps,
+  type ProFormItemInstance,
+} 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;