@qin-ui/element-plus-pro 1.0.8 → 1.1.0

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';
+import BaseFormItem from './BaseFormItem/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 { ProForm, BaseFormItem };
+
+// instance
+export type ProFormInstance = ComponentExposed<typeof ProForm>;
+export type ProFormProps = ComponentProps<typeof ProForm>;
+
+export type ProFormItemInstance = ComponentExposed<typeof BaseFormItem>;
+export type ProFormItemProps = ComponentProps<typeof BaseFormItem>;

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

@@ -0,0 +1,116 @@
+import {
+  Cascader,
+  CheckboxGroup,
+  DatePicker,
+  AutoComplete,
+  Input,
+  InputNumber,
+  RadioGroup,
+  Select,
+  Slider,
+  Switch,
+  TimePicker,
+  TimeSelect,
+  Transfer,
+  TreeSelect,
+} from '../../../shared/ui';
+
+/**
+ * FormItem 插槽名称列表
+ * @description 用于在字段配置中透传 FormItem 的插槽（Element Plus 版本）
+ */
+// prettier-ignore
+export const FORM_ITEM_SLOT_KEYS = ['label', 'error'] as const;
+
+/**
+ * 内置组件映射表
+ * @description Element Plus 内置支持的组件类型映射
+ */
+// prettier-ignore
+export type BaseComponentMap = {
+  'input': typeof Input;
+  'input-number': typeof InputNumber;
+  'autocomplete': typeof AutoComplete;
+  'select': typeof Select;
+  'cascader': typeof Cascader;
+  'date-picker': typeof DatePicker;
+  'time-picker': typeof TimePicker;
+  'time-select': typeof TimeSelect;
+  '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
+ * declare module '@qin-ui/element-plus-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;
+
+/**
+ * 组件名称到 Element Plus 组件的映射
+ */
+// prettier-ignore
+export const componentMap: BaseComponentMap = {
+  'input': Input,
+  'input-number': InputNumber,
+  'autocomplete': AutoComplete,
+  'select': Select,
+  'cascader': Cascader,
+  'date-picker': DatePicker,
+  'time-picker': TimePicker,
+  'time-select': TimeSelect,
+  '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`，将泛型参数绑定为 Element Plus 的本地类型：
+ * - 字段类型 F -> `Field<ComponentName, D>`（支持 Element Plus 组件类型推导）
+ * - FormItem 实例 -> Element Plus 的 `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 绑定为 Element Plus 的 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      - 底层 Element Plus 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`，将泛型参数绑定为 Element Plus 的本地类型：
+ * - 字段类型 F -> `Field<ComponentName, D>`（支持 Element Plus 所有内置组件类型推导）
+ * - 表单实例 -> Element Plus 的 `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`，将泛型参数绑定为 Element Plus 的 `FormInstance`，
+ * 使 formRef 获取到完整的 Element Plus Form 组件 API 类型提示（如 `validate()`、`resetFields()` 等）。
+ *
+ * `formRef` 由 ProForm 组件内部自动通过 `setFormRef` 绑定，无需手动调用。
+ *
+ * @returns 表单组件实例引用管理对象：
+ * - `formRef` — Element Plus 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;