@yetuzi/vue3-query-components 1.5.0 → 1.5.1

package/dist/index.d.ts

@@ -64,10 +64,10 @@ onChange?: ((args_0: PaginationParam) => any) | undefined;
 "onUpdate:pageSize"?: ((value: number) => any) | undefined;
 }>, {
 readonly background: boolean;
-readonly teleported: EpPropMergeType<BooleanConstructor, unknown, unknown>;
-readonly layout: string;
 readonly total: number;
+readonly layout: string;
 readonly pageSizes: number[];
+readonly teleported: EpPropMergeType<BooleanConstructor, unknown, unknown>;
 }, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
 
 declare const __VLS_component_4: DefineComponent<__VLS_PublicProps_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {
@@ -109,7 +109,7 @@ declare type __VLS_PrettifyLocal_2<T> = {
     [K in keyof T]: T[K];
 } & {};
 
-/** 组件Props定义，提供默认值 */
+/** 组件 Props 定义，默认不传表单配置时使用空数组 */
 declare type __VLS_Props = CommonQueryTableProps;
 
 declare type __VLS_Props_10 = CommonCheckboxProps;
@@ -117,7 +117,12 @@ declare type __VLS_Props_10 = CommonCheckboxProps;
 /** 组件Props定义，提供默认值 */
 declare type __VLS_Props_11 = CommonSwitchProps;
 
-/** 组件Props定义，提供默认值 */
+/**
+ * 组件 Props 定义。
+ *
+ * 在 Element Plus 原生分页属性基础上补充默认值，
+ * 让业务场景下可以直接使用常见分页布局。
+ */
 declare type __VLS_Props_2 = CommonPaginationProps;
 
 /** 组件Props定义，提供默认值 */
@@ -359,9 +364,8 @@ export declare interface CommonCheckboxProps extends ExtractPublicPropTypes<Chec
 export declare const CommonConfigProvider: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 
 /**
- * CommonConfigProvider组件属性类型
- * 继承自深度部分配置类型，支持配置项的部分覆盖
- * 使用@vue-ignore忽略Vue类型检查
+ * CommonConfigProvider 组件 Props 类型
+ * 支持以深度可选的方式覆盖任意层级配置项
  */
 export declare interface CommonConfigProviderProps extends /* @vue-ignore */ DeepPartial<Config> {
 }
@@ -398,246 +402,85 @@ export declare const CommonForm: <T extends AnyObject>(__VLS_props: NonNullable<
     __ctx?: Awaited<typeof __VLS_setup>;
 };
 
-/**
- * 级联选择器组件表单项
- *
- * @typeParam T - 表单数据对象类型
- *
- * @example
- * ```ts
- * const cascaderItem: CommonFormCascaderItem<UserData> = {
- *   is: 'cascader',
- *   prop: 'region',
- *   label: '地区',
- *   props: {
- *     options: regionOptions,
- *     props: {
- *       value: 'code',
- *       label: 'name',
- *       children: 'children'
- *     }
- *   }
- * }
- * ```
- */
+/** 级联选择器表单项 */
 export declare interface CommonFormCascaderItem<T extends AnyObject> extends CommonFormItemBase<'cascader', CommonCascaderProps, T> {
 }
 
-/**
- * 多选框组件表单项
- *
- * @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 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'
- *   }
- * }
- * ```
+ * 允许任意 Vue 组件作为表单项渲染
  */
 export declare interface CommonFormCustomItem<T extends AnyObject, C extends Component = Component, P = ComponentProps<C>> extends CommonFormItemBase<C, P, T> {
 }
 
 /**
  * 表单数据类型
- * 支持通过 prop 访问表单字段值，并允许额外的字符串索引
+ * 既支持通过已知字段访问，也允许额外的动态字段
  *
  * @typeParam T - 表单数据对象类型
  */
 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 CommonFormItemBase<'date-picker', CommonDatePickerProps, T> {
 }
 
 /**
- * CommonForm 组件实例暴露类型
- * 继承 Element Plus FormInstance 的所有方法，并提供表单数据访问
+ * CommonForm 暴露实例类型
+ * 继承 Element Plus `FormInstance`，并附带 `formData`
  *
- * @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>
- * ```
+ * @typeParam T - 表单数据对象类型
  */
 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 CommonFormItemBase<'input', CommonInputProps, T> {
 }
 
-/**
- * 数字输入框组件表单项
- *
- * @typeParam T - 表单数据对象类型
- *
- * @example
- * ```ts
- * const inputNumberItem: CommonFormInputNumberItem<UserData> = {
- *   is: 'input-number',
- *   prop: 'age',
- *   label: '年龄',
- *   props: {
- *     min: 0,
- *     max: 150,
- *     step: 1
- *   }
- * }
- * ```
- */
+/** 数字输入框表单项 */
 export declare interface CommonFormInputNumberItem<T extends AnyObject> extends CommonFormItemBase<'input-number', CommonInputNumberProps, T> {
 }
 
 /**
- * 表单项类型数组
- * 用于 CommonForm 的 form 属性，也可用于类型标注
+ * 表单项数组类型
+ * 用于 CommonForm 的 `form` 属性，也可用于独立类型标注
  *
  * @typeParam T - 表单数据对象类型
- *
- * @example
- * ```ts
- * import type { CommonFormItemArray } from '@yetuzi/vue3-query-components'
- *
- * const form: CommonFormItemArray<MyDataType> = [
- *   { is: 'input', prop: 'name', label: '用户名' },
- *   { is: 'select', prop: 'status', label: '状态' }
- * ]
- * ```
  */
 export declare type CommonFormItemArray<T extends AnyObject> = Array<CommonFormSelectItem<T> | CommonFormInputItem<T> | CommonFormInputNumberItem<T> | CommonFormDatePickerItem<T> | CommonFormTimePickerItem<T> | CommonFormCascaderItem<T> | CommonFormRadioItem<T> | CommonFormCustomItem<T> | CommonFormCheckboxItem<T> | CommonFormSwitchItem<T>>;
 
 /**
  * 表单项基础接口
- * 所有表单项类型的公共属性定义
+ * 定义所有表单项共享的公共属性
  *
- * @typeParam T - 组件类型，可以是内置组件类型字符串或自定义组件
- * @typeParam P - 组件的 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: '自定义字段'
- * }
- * ```
+ * @typeParam V - 初始值类型
  */
 declare interface CommonFormItemBase<T, P, D extends AnyObject, V = any> {
     /**
      * 组件类型标识
-     * - 内置组件：'input' | 'input-number' | 'select' | 'date-picker' | 'time-picker' | 'cascader' | 'radio' | 'check-box' | 'switch'
+     * - 内置组件：`input`、`input-number`、`select`、`date-picker`、`time-picker`、`cascader`、`radio`、`check-box`、`switch`
      * - 自定义组件：直接传入组件对象
      */
     is: T | (string & {});
     /** 表单项标签 */
     label?: string;
-    /** 表单字段名，支持表单数据类型的 key 或任意字符串 */
+    /** 表单字段名 */
     prop: keyof D | (string & {});
     /** 传递给组件的额外属性 */
     props?: Partial<P>;
     /** 字段初始值 */
     initialValue?: V;
-    /** ElFormItem 的额外属性配置（不包含 prop 和 label） */
+    /** ElFormItem 的额外配置，不包含 `prop` 和 `label` */
     formItem?: Partial<Omit<FormItemProps, 'prop' | 'label'>>;
 }
 
@@ -645,100 +488,25 @@ declare interface CommonFormItemBase<T, P, D extends AnyObject, V = any> {
  * CommonForm 组件 Props
  *
  * @typeParam T - 表单数据对象类型
- *
- * @example
- * ```vue
- * <template>
- *   <CommonForm :form="formConfig" v-model="formData" />
- * </template>
- * ```
  */
 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 CommonFormRadioItem<T extends AnyObject> extends CommonFormItemBase<'radio', CommonRadioProps, T> {
 }
 
-/**
- * 选择器组件表单项
- *
- * @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 CommonFormItemBase<'switch', CommonSwitchProps, T> {
 }
 
-/**
- * 时间选择器组件表单项
- *
- * @typeParam T - 表单数据对象类型
- *
- * @example
- * ```ts
- * const timeItem: CommonFormTimePickerItem<UserData> = {
- *   is: 'time-picker',
- *   prop: 'startTime',
- *   label: '开始时间',
- *   props: {
- *     placeholder: '请选择时间'
- *   }
- * }
- * ```
- */
+/** 时间选择器表单项 */
 export declare interface CommonFormTimePickerItem<T extends AnyObject> extends CommonFormItemBase<'time-picker', CommonTimePickerProps, T> {
 }
 
@@ -761,9 +529,10 @@ export declare interface CommonInputProps extends /* @vue-ignore */ ExtractDefau
 export declare const CommonPagination: __VLS_WithTemplateSlots_3<typeof __VLS_component_3, __VLS_TemplateResult_3["slots"]>;
 
 /**
- * CommonPagination组件属性类型
- * 直接继承Element Plus分页组件的属性，所有属性均为可选
- * Element Plus内部已用ExtractPropTypes处理过类型
+ * `CommonPagination` 组件属性类型。
+ *
+ * 组件在 Element Plus `PaginationProps` 基础上做轻量封装，
+ * 因此直接复用其大部分属性定义，并将字段统一声明为可选。
  */
 export declare interface CommonPaginationProps extends Partial<PaginationProps> {
 }
@@ -771,36 +540,32 @@ export declare interface CommonPaginationProps extends Partial<PaginationProps>
 export declare const CommonQueryTable: __VLS_WithTemplateSlots_2<typeof __VLS_component_2, __VLS_TemplateResult_2["slots"]>;
 
 /**
- * CommonQueryTable 组件实例方法
+ * CommonQueryTable 组件暴露方法
+ * 可通过 `ref` 直接调用
+ *
+ * @typeParam T - 表格行数据类型
  */
 export declare interface CommonQueryTableExpose<T = AnyObject> {
-    /**
-     * 刷新列表数据
-     * 使用当前查询条件和分页参数重新请求数据
-     */
+    /** 使用当前条件刷新列表数据 */
     refresh: () => void;
-    /**
-     * 重置查询条件和分页
-     * 重置表单字段到初始值，重置分页到第一页，并重新请求数据
-     */
+    /** 重置查询条件和分页，并重新获取列表数据 */
     reset: () => void;
-    /**
-     * 获取表单数据
-     * @returns 当前表单的值对象
-     */
+    /** 获取当前表单数据 */
     getFormData: () => Partial<T>;
-    /**
-     * 获取表格选中的行数据
-     * @returns 选中的行数据数组
-     */
+    /** 获取当前表格选中行数据 */
     getSelectionRows: () => T[];
 }
 
+/**
+ * CommonQueryTable 组件 Props
+ * 将查询表单、数据表格和分页能力组合到一个组件中
+ *
+ * @typeParam T - 表格行数据类型
+ */
 export declare interface CommonQueryTableProps<T extends AnyObject = AnyObject> {
     /**
      * 数据获取函数
-     * @param params - 查询参数，包含分页和表单查询条件
-     * @returns Promise 包含数据列表和总数的对象
+     * 接收查询参数并返回包含列表和总数的 Promise
      */
     fetch: (params?: ListParam) => Promise<{
         list: T[];
@@ -808,12 +573,12 @@ export declare interface CommonQueryTableProps<T extends AnyObject = AnyObject>
     }>;
     /**
      * 表单配置数组
-     * 定义查询表单的字段和属性
+     * 用于定义查询表单的字段结构和属性
      */
     form?: CommonFormItemArray<T>;
     /**
      * 表格列配置
-     * 定义表格的列结构和展示方式
+     * 定义列表表格的列结构与展示方式
      */
     columns: CommonTableColumn<T>;
 }
@@ -875,7 +640,7 @@ export declare const CommonTable: <T extends AnyObject>(__VLS_props: NonNullable
         row: any;
         column: any;
         index: any;
-        value: any;
+        value: T[keyof T] | undefined;
     }) => any>> & {
         empty?(_: {}): any;
     };
@@ -885,10 +650,10 @@ export declare const CommonTable: <T extends AnyObject>(__VLS_props: NonNullable
 };
 
 /**
- * 表格列类型数组
- * 用于 CommonTable 的 columns 属性，也可用于类型标注
+ * 表格列数组类型
+ * 用于 CommonTable 的 `columns` 属性，也可用于独立类型标注
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  *
  * @example
  * ```ts
@@ -897,7 +662,7 @@ export declare const CommonTable: <T extends AnyObject>(__VLS_props: NonNullable
  * const columns: CommonTableArrayColumns<MyDataType> = [
  *   { prop: 'id', label: 'ID', type: 'index' },
  *   { prop: 'name', label: '用户名' },
- *   { prop: 'createTime', label: '创建时间', type: 'dateTime' }
+ *   { prop: 'createTime', label: '创建时间', type: 'dateTime' },
  * ]
  * ```
  */
@@ -905,15 +670,15 @@ export declare type CommonTableArrayColumns<T extends AnyObject> = Array<CommonT
 
 /**
  * 表格列配置类型
- * 支持数组形式和对象形式的列配置
+ * 支持数组形式和对象形式两种列配置写法
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  *
  * @example 数组形式
  * ```ts
  * const columns: CommonTableArrayColumns<UserData> = [
  *   { prop: 'name', label: '姓名' },
- *   { prop: 'age', label: '年龄' }
+ *   { prop: 'age', label: '年龄' },
  * ]
  * ```
  *
@@ -921,33 +686,34 @@ export declare type CommonTableArrayColumns<T extends AnyObject> = Array<CommonT
  * ```ts
  * const columns: CommonTableObjectColumns<UserData> = {
  *   name: { prop: 'name', label: '姓名' },
- *   age: { prop: 'age', label: '年龄' }
+ *   age: { prop: 'age', label: '年龄' },
  * }
  * ```
  */
 export declare type CommonTableColumn<T extends AnyObject> = CommonTableArrayColumns<T> | CommonTableObjectColumns<T>;
 
 /**
- * 表格列定义根类型
- * 包含所有列类型的联合类型
+ * 表格列根类型
+ * 包含所有列类型的联合定义
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  */
 export declare type CommonTableColumnRoot<T extends AnyObject> = TableColumnBase<T> | TableColumnTypeDefault<T> | TableColumnTypeIndex<T> | TableColumnTypeSelection<T> | TableColumnTypeExpand<T> | TableColumnTypeDate<T> | TableColumnTypeDateTime<T> | TableColumnTypeDict<T>;
 
 /**
  * 表格列类型标识
- * 从 CommonTableColumnRoot 中自动提取 type 字段的类型
+ * 从 `CommonTableColumnRoot` 中自动提取 `type` 字段类型
  *
  * @example
  * ```ts
  * let columnType: CommonTableColumnType
  *
- * columnType = 'index'      // ✓ 索引列
- * columnType = 'selection'  // ✓ 选择列
- * columnType = 'expand'     // ✓ 展开列
- * columnType = 'date'       // ✓ 日期列
- * columnType = 'dateTime'   // ✓ 日期时间列
+ * columnType = 'index'
+ * columnType = 'selection'
+ * columnType = 'expand'
+ * columnType = 'date'
+ * columnType = 'dateTime'
+ * columnType = 'dict'
  * ```
  */
 export declare type CommonTableColumnType = Extract<CommonTableColumnRoot<AnyObject>, {
@@ -962,6 +728,7 @@ export declare type CommonTableColumnType = Extract<CommonTableColumnRoot<AnyObj
  * ```vue
  * <script setup lang="ts">
  * import { ref } from 'vue'
+ * import type { CommonTableExpose } from '@yetuzi/vue3-query-components'
  *
  * const tableRef = ref<CommonTableExpose>()
  *
@@ -980,15 +747,15 @@ export declare interface CommonTableExpose extends TableInstance {
 
 /**
  * 表格列对象形式类型
- * 以键值对的方式配置列
+ * 以键值对的方式配置列，键名通常会作为默认 prop 使用
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  *
  * @example
  * ```ts
  * const columns: CommonTableObjectColumns<UserData> = {
  *   name: { prop: 'name', label: '姓名' },
- *   age: { prop: 'age', label: '年龄' }
+ *   age: { prop: 'age', label: '年龄' },
  * }
  * ```
  */
@@ -996,9 +763,9 @@ declare type CommonTableObjectColumns<T extends AnyObject> = Record<keyof T | (s
 
 /**
  * CommonTable 组件 Props
- * 基于 Element Plus Table 封装，提供开箱即用的表格功能
+ * 基于 Element Plus Table 封装，提供开箱即用的表格能力
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  *
  * @example
  * ```vue
@@ -1018,10 +785,10 @@ declare type CommonTableObjectColumns<T extends AnyObject> = Record<keyof T | (s
  * const columns: CommonTableArrayColumns<UserData> = [
  *   { prop: 'id', label: 'ID', type: 'index' },
  *   { prop: 'name', label: '姓名' },
- *   { prop: 'email', label: '邮箱' }
+ *   { prop: 'email', label: '邮箱' },
  * ]
  *
- * const tableData: UserData[] = [...]
+ * const tableData: UserData[] = []
  * </script>
  * ```
  */
@@ -1202,10 +969,10 @@ export declare type ListParam<T extends AnyObject = AnyObject> = PaginationParam
  */
 export declare type OptionalFields<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 
-/** 当前页码，支持v-model双向绑定 */
+/** 当前页码，支持 `v-model:pageNo`。 */
 declare const pageNo: ModelRef<number, string, number, number>;
 
-/** 每页显示条数，支持v-model双向绑定 */
+/** 每页条数，支持 `v-model:pageSize`。 */
 declare const pageSize: ModelRef<number, string, number, number>;
 
 /**
@@ -1235,9 +1002,9 @@ export declare type RequiredSomeFields<T extends object, K extends keyof T> = Om
 
 /**
  * 表格列基础接口
- * 所有列类型的公共属性定义
+ * 定义所有列类型共享的公共属性
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  */
 declare interface TableColumnBase<T extends AnyObject> extends Partial<Omit<TableColumnCtx<T>, 'prop' | 'type'>> {
     /** 列字段名，支持数据类型的 key 或任意字符串 */
@@ -1250,14 +1017,14 @@ declare interface TableColumnBase<T extends AnyObject> extends Partial<Omit<Tabl
  * 日期列类型
  * 自动格式化日期显示
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  *
  * @example
  * ```ts
  * const dateColumn: TableColumnTypeDate<UserData> = {
  *   type: 'date',
  *   prop: 'createTime',
- *   label: '创建日期'
+ *   label: '创建日期',
  * }
  * ```
  */
@@ -1269,14 +1036,14 @@ declare interface TableColumnTypeDate<T extends AnyObject> extends TableColumnBa
  * 日期时间列类型
  * 自动格式化日期时间显示
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  *
  * @example
  * ```ts
  * const dateTimeColumn: TableColumnTypeDateTime<UserData> = {
  *   type: 'dateTime',
  *   prop: 'updateTime',
- *   label: '更新时间'
+ *   label: '更新时间',
  * }
  * ```
  */
@@ -1284,6 +1051,10 @@ declare interface TableColumnTypeDateTime<T extends AnyObject> extends TableColu
     type: 'dateTime';
 }
 
+/**
+ * 默认列类型
+ * 普通数据列，通常只需要配置 `prop`、`label` 等基础属性
+ */
 declare interface TableColumnTypeDefault<T extends AnyObject> extends OptionalFields<TableColumnBase<T>, 'prop'> {
     type: 'default';
 }
@@ -1292,7 +1063,7 @@ declare interface TableColumnTypeDefault<T extends AnyObject> extends OptionalFi
  * 字典列类型
  * 根据配置的字典选项，将值转换为对应的标签显示
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  *
  * @example 使用 options
  * ```ts
@@ -1302,8 +1073,8 @@ declare interface TableColumnTypeDefault<T extends AnyObject> extends OptionalFi
  *   label: '状态',
  *   options: [
  *     { label: '启用', value: 1 },
- *     { label: '禁用', value: 0 }
- *   ]
+ *     { label: '禁用', value: 0 },
+ *   ],
  * }
  * ```
  *
@@ -1313,7 +1084,7 @@ declare interface TableColumnTypeDefault<T extends AnyObject> extends OptionalFi
  *   type: 'dict',
  *   prop: 'gender',
  *   label: '性别',
- *   dictName: 'gender'
+ *   dictName: 'gender',
  * }
  * ```
  */
@@ -1330,15 +1101,15 @@ export declare interface TableColumnTypeDict<T extends AnyObject> extends TableC
 
 /**
  * 展开列类型
- * 提供行展开功能
+ * 提供行展开能力
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  *
  * @example
  * ```ts
  * const expandColumn: TableColumnTypeExpand<UserData> = {
  *   type: 'expand',
- *   label: '详情'
+ *   label: '详情',
  * }
  * ```
  */
@@ -1350,14 +1121,14 @@ declare interface TableColumnTypeExpand<T extends AnyObject> extends OptionalFie
  * 索引列类型
  * 自动显示行号
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  *
  * @example
  * ```ts
  * const indexColumn: TableColumnTypeIndex<UserData> = {
  *   type: 'index',
  *   label: '序号',
- *   width: 60
+ *   width: 60,
  * }
  * ```
  */
@@ -1367,23 +1138,23 @@ declare interface TableColumnTypeIndex<T extends AnyObject> extends OptionalFiel
 
 /**
  * 选择列类型
- * 提供多选功能
+ * 提供多选能力
  *
- * @typeParam T - 表格数据行类型
+ * @typeParam T - 表格行数据类型
  *
  * @example
  * ```ts
  * const selectionColumn: TableColumnTypeSelection<UserData> = {
  *   type: 'selection',
- *   selectable: (row, index) => row.status === 'active'
+ *   selectable: (row) => row.status === 'active',
  * }
  * ```
  */
 declare interface TableColumnTypeSelection<T extends AnyObject> extends OptionalFields<TableColumnBase<T>, 'prop'> {
     type: 'selection';
-    /** 行可选择的条件函数 */
+    /** 行是否可选的条件函数 */
     selectable?: (row: T, index: number) => boolean;
-    /** 是否保留之前的选择 */
+    /** 是否保留之前的选中状态 */
     'reserve-selection'?: boolean;
 }