@yetuzi/vue3-query-components 1.2.0 → 1.2.3

package/dist/index.d.ts

@@ -41,7 +41,7 @@ import { VNodeProps } from 'vue';
 declare const __VLS_component: DefineComponent<CommonConfigProviderProps, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<CommonConfigProviderProps> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 declare const __VLS_component_2: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
-form: CommonFormPropForm<AnyObject>;
+form: CommonFormItemArray<AnyObject>;
 layouts: Array<CommonQueryTableLayoutsUnite>;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {
 CommonFormRef: ShallowUnwrapRef<CommonFormExpose<AnyObject>> | null;
@@ -336,94 +336,280 @@ export declare const CommonForm: <T extends AnyObject>(__VLS_props: NonNullable<
 };
 
 /**
- * 多选框
+ * 多选框组件表单项
+ *
+ * @typeParam T - 表单数据对象类型
+ *
+ * @example
+ * ```ts
+ * const checkboxItem: CommonFormCheckboxItem<UserData> = {
+ *   is: 'check-box',
+ *   prop: 'hobbies',
+ *   label: '爱好',
+ *   props: {
+ *     options: [
+ *       { label: '阅读', value: 'reading' },
+ *       { label: '运动', value: 'sports' }
+ *     ]
+ *   }
+ * }
+ * ```
  */
-export declare interface CommonFormCheckboxItem<T extends AnyObject> extends CommonFormSupplement<'check-box', CommonCheckboxProps, T> {
+export declare interface CommonFormCheckboxItem<T extends AnyObject> extends CommonFormItemBase<'check-box', CommonCheckboxProps, T> {
 }
 
 /**
- * 自定义组件
+ * 自定义组件表单项
+ * 允许使用任意 Vue 组件作为表单项
+ *
+ * @typeParam T - 表单数据对象类型
+ * @typeParam C - 自定义组件类型，默认为 Component
+ * @typeParam P - 组件 Props 类型，默认从组件推导
+ *
+ * @example
+ * ```ts
+ * import MyCustomComponent from './MyCustomComponent.vue'
+ *
+ * const customItem: CommonFormCustomItem<UserData> = {
+ *   is: MyCustomComponent,
+ *   prop: 'custom',
+ *   label: '自定义字段',
+ *   props: {
+ *     // 传递给自定义组件的属性
+ *     customProp: 'value'
+ *   }
+ * }
+ * ```
  */
-export declare interface CommonFormCustomComponentsItem<T extends AnyObject, C extends Component = Component, P = ComponentProps<C>> extends CommonFormSupplement<C, P, T> {
+export declare interface CommonFormCustomItem<T extends AnyObject, C extends Component = Component, P = ComponentProps<C>> extends CommonFormItemBase<C, P, T> {
 }
 
 /**
- * 表单数据类型，支持通过prop访问
+ * 表单数据类型
+ * 支持通过 prop 访问表单字段值，并允许额外的字符串索引
+ *
+ * @typeParam T - 表单数据对象类型
  */
-export declare type CommonFormData<T extends AnyObject> = T & {
-    [key: string]: any;
-};
+export declare type CommonFormData<T extends AnyObject> = T & Record<string, any>;
 
 /**
- * 日期选择器
+ * 日期选择器组件表单项
+ *
+ * @typeParam T - 表单数据对象类型
+ *
+ * @example
+ * ```ts
+ * const dateItem: CommonFormDatePickerItem<UserData> = {
+ *   is: 'date-picker',
+ *   prop: 'birthday',
+ *   label: '生日',
+ *   props: {
+ *     type: 'date',
+ *     placeholder: '请选择日期'
+ *   }
+ * }
+ * ```
  */
-export declare interface CommonFormDatePickerItem<T extends AnyObject> extends CommonFormSupplement<'date-picker', CommonDatePickerProps, T> {
+export declare interface CommonFormDatePickerItem<T extends AnyObject> extends CommonFormItemBase<'date-picker', CommonDatePickerProps, T> {
 }
 
 /**
  * CommonForm 组件实例暴露类型
- * 继承 FormInstance 的所有方法，可直接调用 validate()、resetFields() 等
- * 并且 导出 formData 数据
+ * 继承 Element Plus FormInstance 的所有方法，并提供表单数据访问
+ *
+ * @typeParam T - 表单数据对象类型，默认为 AnyObject
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { ref } from 'vue'
+ *
+ * const formRef = ref<CommonFormExpose<UserData>>()
+ *
+ * const handleSubmit = async () => {
+ *   // 调用 FormInstance 方法
+ *   await formRef.value?.validate()
+ *
+ *   // 访问表单数据
+ *   console.log(formRef.value?.formData)
+ * }
+ * </script>
+ * ```
  */
 export declare interface CommonFormExpose<T extends AnyObject = AnyObject> extends FormInstance {
-    /** 表单数据对象 */
+    /**
+     * 表单数据响应式对象
+     * 包含所有表单字段的当前值
+     */
     formData: Reactive<CommonFormData<T>>;
 }
 
 /**
- * 输入框组件
+ * 输入框组件表单项
+ *
+ * @typeParam T - 表单数据对象类型
+ *
+ * @example
+ * ```ts
+ * const inputItem: CommonFormInputItem<UserData> = {
+ *   is: 'input',
+ *   prop: 'name',
+ *   label: '姓名',
+ *   props: {
+ *     placeholder: '请输入姓名',
+ *     clearable: true
+ *   }
+ * }
+ * ```
  */
-export declare interface CommonFormInputItem<T extends AnyObject> extends CommonFormSupplement<'input', CommonInputProps, T> {
+export declare interface CommonFormInputItem<T extends AnyObject> extends CommonFormItemBase<'input', CommonInputProps, T> {
 }
 
 /**
  * 表单项类型数组
  * 用于 CommonForm 的 form 属性，也可用于类型标注
  *
+ * @typeParam T - 表单数据对象类型
+ *
  * @example
  * ```ts
- * import type { CommonFormPropForm } from '@yetuzi/vue3-query-components'
+ * import type { CommonFormItemArray } from '@yetuzi/vue3-query-components'
  *
- * const form: CommonFormPropForm<MyDataType> = [
+ * const form: CommonFormItemArray<MyDataType> = [
  *   { is: 'input', prop: 'name', label: '用户名' },
  *   { is: 'select', prop: 'status', label: '状态' }
  * ]
  * ```
  */
-export declare type CommonFormPropForm<T extends AnyObject> = Array<CommonFormSelectItem<T> | CommonFormInputItem<T> | CommonFormDatePickerItem<T> | CommonFormRadioItem<T> | CommonFormCustomComponentsItem<T> | CommonFormCheckboxItem<T> | CommonFormSwitchItem<T>>;
+export declare type CommonFormItemArray<T extends AnyObject> = Array<CommonFormSelectItem<T> | CommonFormInputItem<T> | CommonFormDatePickerItem<T> | CommonFormRadioItem<T> | CommonFormCustomItem<T> | CommonFormCheckboxItem<T> | CommonFormSwitchItem<T>>;
 
 /**
- * form 组件props
+ * 表单项基础接口
+ * 所有表单项类型的公共属性定义
+ *
+ * @typeParam T - 组件类型，可以是内置组件类型字符串或自定义组件
+ * @typeParam P - 组件的 Props 类型
+ * @typeParam D - 表单数据对象类型
+ * @typeParam V - 初始值的类型，默认为 any
+ *
+ * @example 内置组件
+ * ```ts
+ * const inputItem: CommonFormInputItem<UserData> = {
+ *   is: 'input',
+ *   prop: 'name',
+ *   label: '姓名'
+ * }
+ * ```
+ *
+ * @example 自定义组件
+ * ```ts
+ * import MyComponent from './MyComponent.vue'
+ *
+ * const customItem: CommonFormCustomItem<UserData> = {
+ *   is: MyComponent,
+ *   prop: 'custom',
+ *   label: '自定义字段'
+ * }
+ * ```
  */
-export declare interface CommonFormProps<T extends AnyObject> extends ExtractPropTypes<FormProps> {
-    form?: CommonFormPropForm<T>;
+declare interface CommonFormItemBase<T, P, D extends AnyObject, V = any> {
+    /**
+     * 组件类型标识
+     * - 内置组件：'input' | 'select' | 'date-picker' | 'radio' | 'check-box' | 'switch'
+     * - 自定义组件：直接传入组件对象
+     */
+    is: T | (string & {});
+    /** 表单项标签 */
+    label?: string;
+    /** 表单字段名，支持表单数据类型的 key 或任意字符串 */
+    prop: keyof D | (string & {});
+    /** 传递给组件的额外属性 */
+    props?: Partial<P>;
+    /** 字段初始值 */
+    initialValue?: V;
+    /** ElFormItem 的额外属性配置（不包含 prop 和 label） */
+    formItem?: Partial<Omit<FormItemProps, 'prop' | 'label'>>;
 }
 
 /**
- * 单选框
+ * CommonForm 组件 Props
+ *
+ * @typeParam T - 表单数据对象类型
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <CommonForm :form="formConfig" v-model="formData" />
+ * </template>
+ * ```
  */
-export declare interface CommonFormRadioItem<T extends AnyObject> extends CommonFormSupplement<'radio', CommonRadioProps, T> {
+export declare interface CommonFormProps<T extends AnyObject> extends ExtractPropTypes<FormProps> {
+    /** 表单项配置数组 */
+    form?: CommonFormItemArray<T>;
 }
 
 /**
- * 选择器组件
+ * 单选框组件表单项
+ *
+ * @typeParam T - 表单数据对象类型
+ *
+ * @example
+ * ```ts
+ * const radioItem: CommonFormRadioItem<UserData> = {
+ *   is: 'radio',
+ *   prop: 'gender',
+ *   label: '性别',
+ *   props: {
+ *     options: [
+ *       { label: '男', value: 'male' },
+ *       { label: '女', value: 'female' }
+ *     ]
+ *   }
+ * }
+ * ```
  */
-export declare interface CommonFormSelectItem<T extends AnyObject> extends CommonFormSupplement<'select', CommonSelectProps, T> {
+export declare interface CommonFormRadioItem<T extends AnyObject> extends CommonFormItemBase<'radio', CommonRadioProps, T> {
 }
 
-declare interface CommonFormSupplement<T, P, D extends AnyObject, V = any> {
-    is: T | (string & {});
-    label?: string;
-    prop: keyof D | (string & {});
-    props?: Partial<P>;
-    initialValue?: V;
-    formItem?: Partial<Omit<FormItemProps, 'prop' | 'label'>>;
+/**
+ * 选择器组件表单项
+ *
+ * @typeParam T - 表单数据对象类型
+ *
+ * @example
+ * ```ts
+ * const selectItem: CommonFormSelectItem<UserData> = {
+ *   is: 'select',
+ *   prop: 'city',
+ *   label: '城市',
+ *   props: {
+ *     options: [
+ *       { label: '北京', value: 'beijing' },
+ *       { label: '上海', value: 'shanghai' }
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+export declare interface CommonFormSelectItem<T extends AnyObject> extends CommonFormItemBase<'select', CommonSelectProps, T> {
 }
 
 /**
- * 开关
+ * 开关组件表单项
+ *
+ * @typeParam T - 表单数据对象类型
+ *
+ * @example
+ * ```ts
+ * const switchItem: CommonFormSwitchItem<UserData> = {
+ *   is: 'switch',
+ *   prop: 'enabled',
+ *   label: '是否启用',
+ *   initialValue: true
+ * }
+ * ```
  */
-export declare interface CommonFormSwitchItem<T extends AnyObject> extends CommonFormSupplement<'switch', CommonSwitchProps, T> {
+export declare interface CommonFormSwitchItem<T extends AnyObject> extends CommonFormItemBase<'switch', CommonSwitchProps, T> {
 }
 
 export declare const CommonInput: __VLS_WithTemplateSlots_5<typeof __VLS_component_5, __VLS_TemplateResult_5["slots"]>;
@@ -461,7 +647,7 @@ export declare interface CommonQueryTableProps<T extends AnyObject = AnyObject>
      * 表单配置数组
      * 定义查询表单的字段和属性
      */
-    form?: CommonFormPropForm<T>;
+    form?: CommonFormItemArray<T>;
     /**
      * 表格列配置
      * 定义表格的列结构和展示方式
@@ -545,6 +731,8 @@ export declare const CommonTable: <T extends AnyObject>(__VLS_props: NonNullable
  * 表格列类型数组
  * 用于 CommonTable 的 columns 属性，也可用于类型标注
  *
+ * @typeParam T - 表格数据行类型
+ *
  * @example
  * ```ts
  * import type { CommonTableArrayColumns } from '@yetuzi/vue3-query-components'
@@ -558,31 +746,138 @@ export declare const CommonTable: <T extends AnyObject>(__VLS_props: NonNullable
  */
 export declare type CommonTableArrayColumns<T extends AnyObject> = Array<CommonTableColumnRoot<T>>;
 
+/**
+ * 表格列配置类型
+ * 支持数组形式和对象形式的列配置
+ *
+ * @typeParam T - 表格数据行类型
+ *
+ * @example 数组形式
+ * ```ts
+ * const columns: CommonTableArrayColumns<UserData> = [
+ *   { prop: 'name', label: '姓名' },
+ *   { prop: 'age', label: '年龄' }
+ * ]
+ * ```
+ *
+ * @example 对象形式
+ * ```ts
+ * const columns: CommonTableObjectColumns<UserData> = {
+ *   name: { prop: 'name', label: '姓名' },
+ *   age: { prop: 'age', label: '年龄' }
+ * }
+ * ```
+ */
 export declare type CommonTableColumn<T extends AnyObject> = CommonTableArrayColumns<T> | CommonTableObjectColumns<T>;
 
 /**
- * Column 根类型 要求 prop 、label 为必传
+ * 表格列定义根类型
+ * 包含所有列类型的联合类型
+ *
+ * @typeParam T - 表格数据行类型
  */
-export declare type CommonTableColumnRoot<T extends AnyObject> = TableColumnSupplement<T> | TableColumnTypeIndex<T> | TableColumnTypeSelection<T> | TableColumnTypeExpand<T> | TableColumnTypeDate<T> | TableColumnTypeDateTime<T>;
+export declare type CommonTableColumnRoot<T extends AnyObject> = TableColumnBase<T> | TableColumnTypeIndex<T> | TableColumnTypeSelection<T> | TableColumnTypeExpand<T> | TableColumnTypeDate<T> | TableColumnTypeDateTime<T>;
 
-/** CommonTable 暴露给父组件的实例类型（包含 ElTable 所有方法） */
+/**
+ * CommonTable 暴露给父组件的实例类型
+ * 包含 ElTable 的所有方法和属性
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { ref } from 'vue'
+ *
+ * const tableRef = ref<CommonTableExpose>()
+ *
+ * const clearSelection = () => {
+ *   tableRef.value?.clearSelection()
+ * }
+ *
+ * const toggleRowSelection = (row: UserData) => {
+ *   tableRef.value?.toggleRowSelection(row, true)
+ * }
+ * </script>
+ * ```
+ */
 export declare interface CommonTableExpose extends TableInstance {
 }
 
 /**
  * CommonTable 组件实例暴露类型
+ * 提供 Element Plus Table 实例访问
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { ref } from 'vue'
+ *
+ * const tableRef = ref<CommonTableInstance>()
+ *
+ * const scrollToBottom = () => {
+ *   tableRef.value?.elTableRef.value?.scrollTo({
+ *     top: 10000,
+ *     behavior: 'smooth'
+ *   })
+ * }
+ * </script>
+ * ```
  */
 export declare interface CommonTableInstance {
     /** ElTable 组件实例引用 */
     elTableRef: Ref<TableInstance | undefined>;
 }
 
-/** Columns 为 Object 时的ts类型 */
+/**
+ * 表格列对象形式类型
+ * 以键值对的方式配置列
+ *
+ * @typeParam T - 表格数据行类型
+ *
+ * @example
+ * ```ts
+ * const columns: CommonTableObjectColumns<UserData> = {
+ *   name: { prop: 'name', label: '姓名' },
+ *   age: { prop: 'age', label: '年龄' }
+ * }
+ * ```
+ */
 declare type CommonTableObjectColumns<T extends AnyObject> = Record<keyof T | (string & {}), CommonTableColumnRoot<T>>;
 
+/**
+ * CommonTable 组件 Props
+ * 基于 Element Plus Table 封装，提供开箱即用的表格功能
+ *
+ * @typeParam T - 表格数据行类型
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <CommonTable :columns="columns" :data="tableData" />
+ * </template>
+ *
+ * <script setup lang="ts">
+ * import type { CommonTableArrayColumns } from '@yetuzi/vue3-query-components'
+ *
+ * interface UserData {
+ *   id: number
+ *   name: string
+ *   email: string
+ * }
+ *
+ * const columns: CommonTableArrayColumns<UserData> = [
+ *   { prop: 'id', label: 'ID', type: 'index' },
+ *   { prop: 'name', label: '姓名' },
+ *   { prop: 'email', label: '邮箱' }
+ * ]
+ *
+ * const tableData: UserData[] = [...]
+ * </script>
+ * ```
+ */
 export declare interface CommonTableProps<T extends AnyObject = AnyObject> extends ExtractPropTypes<Omit<TableProps<T>, 'data' | 'headerCellStyle'>> {
-    /** table 表格需要的表头 */
+    /** 表格列配置 */
     columns: CommonTableColumn<T>;
+    /** 表格数据 */
     data: T[];
 }
 
@@ -683,25 +978,6 @@ export declare function getCommonProviderConfig(): {
  */
 export declare function getFirstValidValue<T>(...args: T[]): T | undefined;
 
-/**
- * 表单项类型守卫辅助函数
- * 用于检查表单项的 is 属性是否为指定类型
- *
- * @param item - 表单项对象
- * @param type - 要检查的类型字符串
- * @returns 是否为指定类型
- *
- * @example
- * ```ts
- * if (isFormItemType(item, 'select')) {
- *   // item 在这里被推断为 CommonFormSelectItem
- * }
- * ```
- */
-export declare function isFormItemType<T extends AnyObject>(item: CommonFormPropForm<T>[number], type: string): item is CommonFormPropForm<T>[number] & {
-    is: string;
-};
-
 /**
  * 列表请求 参数要求,包含分页
  */
@@ -743,56 +1019,132 @@ export declare type RequiredSomeFields<T extends object, K extends keyof T> = Om
     [P in K]-?: T[P];
 };
 
-/** 增强 TableColumn 的类型 */
-declare interface TableColumnSupplement<T extends AnyObject> extends Partial<Omit<TableColumnCtx<T>, 'prop' | 'type'>> {
+/**
+ * 表格列基础接口
+ * 所有列类型的公共属性定义
+ *
+ * @typeParam T - 表格数据行类型
+ */
+declare interface TableColumnBase<T extends AnyObject> extends Partial<Omit<TableColumnCtx<T>, 'prop' | 'type'>> {
+    /** 列字段名，支持数据类型的 key 或任意字符串 */
     prop: keyof T | (string & {});
+    /** 列类型 */
     type?: TableColumnType | (string & {});
 }
 
 /**
- * 表格列类型
+ * 表格列类型标识
  * 从 CommonTableColumnRoot 中自动提取 type 字段的类型
+ *
+ * @example
+ * ```ts
+ * let columnType: TableColumnType
+ *
+ * columnType = 'index'      // ✓ 索引列
+ * columnType = 'selection'  // ✓ 选择列
+ * columnType = 'expand'     // ✓ 展开列
+ * columnType = 'date'       // ✓ 日期列
+ * columnType = 'dateTime'   // ✓ 日期时间列
+ * ```
  */
 export declare type TableColumnType = Extract<CommonTableColumnRoot<AnyObject>, {
     type: any;
 }>['type'];
 
 /**
- * 日期时间
+ * 日期列类型
+ * 自动格式化日期显示
+ *
+ * @typeParam T - 表格数据行类型
+ *
+ * @example
+ * ```ts
+ * const dateColumn: TableColumnTypeDate<UserData> = {
+ *   type: 'date',
+ *   prop: 'createTime',
+ *   label: '创建日期'
+ * }
+ * ```
  */
-declare interface TableColumnTypeDate<T extends AnyObject> extends TableColumnSupplement<T> {
-    /** 时间内容 */
+declare interface TableColumnTypeDate<T extends AnyObject> extends TableColumnBase<T> {
     type: 'date';
 }
 
 /**
- * 日期时间
+ * 日期时间列类型
+ * 自动格式化日期时间显示
+ *
+ * @typeParam T - 表格数据行类型
+ *
+ * @example
+ * ```ts
+ * const dateTimeColumn: TableColumnTypeDateTime<UserData> = {
+ *   type: 'dateTime',
+ *   prop: 'updateTime',
+ *   label: '更新时间'
+ * }
+ * ```
  */
-declare interface TableColumnTypeDateTime<T extends AnyObject> extends TableColumnSupplement<T> {
-    /** 时间内容 */
+declare interface TableColumnTypeDateTime<T extends AnyObject> extends TableColumnBase<T> {
     type: 'dateTime';
 }
 
 /**
- * 可展开的按钮
+ * 展开列类型
+ * 提供行展开功能
+ *
+ * @typeParam T - 表格数据行类型
+ *
+ * @example
+ * ```ts
+ * const expandColumn: TableColumnTypeExpand<UserData> = {
+ *   type: 'expand',
+ *   label: '详情'
+ * }
+ * ```
  */
-declare interface TableColumnTypeExpand<T extends AnyObject> extends OptionalFields<TableColumnSupplement<T>, 'prop'> {
+declare interface TableColumnTypeExpand<T extends AnyObject> extends OptionalFields<TableColumnBase<T>, 'prop'> {
     type: 'expand';
 }
 
 /**
- * 下标
+ * 索引列类型
+ * 自动显示行号
+ *
+ * @typeParam T - 表格数据行类型
+ *
+ * @example
+ * ```ts
+ * const indexColumn: TableColumnTypeIndex<UserData> = {
+ *   type: 'index',
+ *   label: '序号',
+ *   width: 60
+ * }
+ * ```
  */
-declare interface TableColumnTypeIndex<T extends AnyObject> extends OptionalFields<TableColumnSupplement<T>, 'prop'> {
+declare interface TableColumnTypeIndex<T extends AnyObject> extends OptionalFields<TableColumnBase<T>, 'prop'> {
     type: 'index';
 }
 
 /**
- * 选择器
+ * 选择列类型
+ * 提供多选功能
+ *
+ * @typeParam T - 表格数据行类型
+ *
+ * @example
+ * ```ts
+ * const selectionColumn: TableColumnTypeSelection<UserData> = {
+ *   type: 'selection',
+ *   selectable: (row, index) => row.status === 'active'
+ * }
+ * ```
  */
-declare interface TableColumnTypeSelection<T extends AnyObject> extends OptionalFields<TableColumnSupplement<T>, 'prop'> {
+declare interface TableColumnTypeSelection<T extends AnyObject> extends OptionalFields<TableColumnBase<T>, 'prop'> {
     type: 'selection';
+    /** 行可选择的条件函数 */
     selectable?: (row: T, index: number) => boolean;
+    /** 是否保留之前的选择 */
     'reserve-selection'?: boolean;
 }