@qin-ui/element-plus-pro 1.3.5 → 1.4.0

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

@@ -4,27 +4,31 @@ import type {
   GridItemProps,
   FormInstance,
 } from '../../../shared/ui';
-import { FormItem } from '../../../shared/ui';
+import type { FormItem } from '../../../shared/ui';
 import type {
   ComponentProps,
   ComponentSlots,
 } from 'vue-component-type-helpers';
+import type { VNode, VNodeProps } from 'vue';
 import {
-  type CSSProperties,
+  type ClassValue,
   type Component,
   type Raw,
   type MaybeRef,
   type ComputedRef,
-  VNode,
-  VNodeProps,
+  type StyleValue,
 } from 'vue';
 import type { Data, Path } from '../../../shared/core';
-import { ComponentName, GetComponentType } from '../constants';
+import type { ComponentName, GetComponentType } from '../constants';
+import type { AdditionalMethods } from '../../../shared/core';
+import type { FormItemInstance } from '../../../shared/ui';
 
 export type { FormInstance };
 
+/** 路径属性：把字段路径随 props 下发给渲染组件 */
 export type PathProps = { path?: string } & Data;
 
+/** v-model 绑定属性：模型值与更新回调 */
 export type VModelProps<T = any> = {
   modelValue?: T;
   'onUpdate:modelValue'?: (val: T) => void;
@@ -59,13 +63,13 @@ export type ValueFormatter =
   | { get?: (val: any) => any; set?: (val: any, oldVal?: any) => any };
 
 /**
- * @description 自定义组件
+ * 自定义渲染组件类型
  * @example (p, ctx) => h('div', ctx.attrs)
  */
 export type RenderComponentType = Component<VModelProps & PathProps>;
 
 /**
- * @description 插槽组件类型
+ * 插槽组件类型：VNode、组件定义、渲染函数或文本
  */
 export type SlotComponentType =
   | Component<PathProps>
@@ -78,45 +82,49 @@ export type SlotComponentType =
   | ((...args: any[]) => SlotComponentType);
 
 /**
- * @description 容器组件类型
+ * 容器组件类型
  */
 export type ContainerComponent = Component<PathProps>;
 
 /**
- * @description 插槽对象类型
+ * 插槽对象类型，键为插槽名
  */
 export type Slots = {
   [name: string]: SlotComponentType;
 };
 
+/** 选项数据：label 展示、value 取值，可携带任意扩展字段 */
 export type Option = { label: string; value: any; [x: string]: any };
+/** 选项数据数组 */
 export type Options = Array<Option>;
 
+/** 网格布局配置：布尔即启用默认布局，传对象作为 GridProps */
 export type Grid = boolean | (GridProps & {});
 
+/** FormItem 插槽集合（label / error 等） */
 export type FormItemSlots = ComponentSlots<typeof FormItem>;
 
 type BaseCommon<D extends Data = Data> = {
   /**
-   * @description 字段标识namePath, 同prop
+   * 字段标识（namePath），与 prop 同时配置时以 prop 为准；`name` 作为控件自身属性向下透传
+   *
+   * 嵌套字段的 `path` 使用各自独立的完整路径（不与父级路径拼接），重复路径需自行保证唯一。
    * @example 'name' | 'age' | 'sex' | ...
    */
   path?: Path<D>;
-  /**
-   * @description 字段是否隐藏
-   */
+  /** 字段是否隐藏；支持布尔、Ref 与 ComputedRef 形式，渲染期统一按 `toValue` 取值 */
   hidden?: boolean;
   /**
-   * @description 字段是否禁用
+   * 字段是否禁用；字段级取值优先，未显式指定时继承上层（表单或宿主 Provider）的禁用上下文
    */
   disabled?: boolean;
   /**
-   * @description 字段中文名称，支持字符串或组件
+   * 字段中文名称，支持字符串或组件
    * @example '姓名' | '年龄' | '性别' | () => h('span', '自定义标签')
    */
   label?: SlotComponentType;
   /**
-   * @description 字段插槽配置，可包含formItem插槽和component插槽
+   * 字段插槽配置，可包含 FormItem 插槽与组件插槽
    * @example
    * ```js
    * slots: {
@@ -128,27 +136,27 @@ type BaseCommon<D extends Data = Data> = {
    */
   slots?: Partial<FormItemSlots>;
   /**
-   * @description 字段formItem样式属性
+   * FormItem 样式
    * @example { marginBottom: '8px', padding: '12px' }
    */
-  formItemStyle?: CSSProperties;
+  formItemStyle?: StyleValue;
   /**
-   * @description 字段formItem样式类名
+   * FormItem 类名
    * @example 'custom-form-item' | 'required-field'
    */
-  formItemClass?: string;
+  formItemClass?: ClassValue;
   /**
-   * @description 字段formItem容器包裹组件
+   * FormItem 外层包裹组件
    * @example (props, ctx) => h('div', { class: 'custom-container' }, ctx.slots.default?.())
    */
   formItemContainer?: ContainerComponent;
   /**
-   * @description 将属性附加到 FormItem 的 DOM 节点
+   * 附加到 FormItem DOM 节点上的属性
    * @example { 'data-form-item-test': 'test-value', 'aria-label': 'name' }
    */
   formItemDataAttrs?: Record<string, string>;
   /**
-   * @description 额外的自定义属性，不会被当作组件参数，仅用做给字段添加标识属性等功能
+   * 业务侧自定义标识属性，不作为组件属性透传
    * @example { group: 'group-1' }
    */
   extraProps?: Record<string, any>;
@@ -156,43 +164,45 @@ type BaseCommon<D extends Data = Data> = {
 
 type BaseWithFields<D extends Data = Data> = BaseCommon<D> & {
   /**
-   * @description 嵌套子字段配置
-   * @example [{ key: 'firstName', label: '名' }, { key: 'lastName', label: '姓' }]
+   * 嵌套子字段配置
+   * @example [{ path: 'firstName', label: '名' }, { path: 'lastName', label: '姓' }]
    */
   fields: Fields<D>;
   /**
-   * @description 网格布局属性，true表示使用默认网格布局，针对具有嵌套字段的字段
+   * 网格布局配置，true 表示使用默认网格布局
    * @example boolean | { gutter: 24 }
    */
   grid?: Grid;
   component?: never;
   /**
-   * @description 字段component样式属性
+   * 组件样式（仅非嵌套字段有效）
    * @example { width: '100%', borderColor: '#d9d9d9' }
    */
   componentStyle?: never;
   /**
-   * @description 字段component样式类名
+   * 组件类名（仅非嵌套字段有效）
    * @example 'custom-input' | 'error-input'
    */
   componentClass?: never;
   /**
-   * @description 字段component容器包裹组件
+   * 组件外层包裹组件（仅非嵌套字段有效）
    * @example (props, ctx) => h('div', { class: 'input-wrapper' }, ctx.slots.default?.())
    */
   componentContainer?: never;
   /**
-   * @description 将属性附加到表单组件的 DOM 节点
+   * 附加到组件 DOM 节点上的属性（仅非嵌套字段有效）
    * @example { 'data-test': 'input-value', 'aria-label': 'name' }
    */
   componentDataAttrs?: never;
   /**
-   * @description 字段值处理函数，在onUpdateValue前执行，函数返回值将作为更新值，也可设置get和set函数，用于处理字段值
+   * 字段值处理函数，在 onUpdateValue 前执行（仅非嵌套字段有效）
+   *
+   * 函数返回值作为更新值；也可传 `{ get, set }` 对象分别处理读取与写入
    * @example (val) => val?.trim()
    */
   valueFormatter?: never;
   /**
-   * @description 组件v-model双向绑定更新属性名，默认'modelValue'
+   * v-model 绑定的属性名，默认 `modelValue`（仅非嵌套字段有效）
    */
   modelProp?: never;
 };
@@ -201,45 +211,47 @@ type BaseWithoutFields<D extends Data = Data> = BaseCommon<D> & {
   fields?: undefined;
   grid?: never;
   /**
-   * @description 字段component样式属性
+   * 组件样式（仅非嵌套字段有效）
    * @example { width: '100%', borderColor: '#d9d9d9' }
    */
-  componentStyle?: CSSProperties;
+  componentStyle?: StyleValue;
   /**
-   * @description 字段component样式类名
+   * 组件类名（仅非嵌套字段有效）
    * @example 'custom-input' | 'error-input'
    */
-  componentClass?: string;
+  componentClass?: ClassValue;
   /**
-   * @description 字段component容器包裹组件
+   * 组件外层包裹组件（仅非嵌套字段有效）
    * @example (props, ctx) => h('div', { class: 'input-wrapper' }, ctx.slots.default?.())
    */
   componentContainer?: ContainerComponent;
   /**
-   * @description 将属性附加到表单组件的 DOM 节点
+   * 附加到组件 DOM 节点上的属性（仅非嵌套字段有效）
    * @example { 'data-test': 'input-value', 'aria-label': 'name' }
    */
   componentDataAttrs?: Record<string, string>;
   /**
-   * @description 字段值处理函数，在onUpdateValue前执行，函数返回值将作为更新值，也可设置get和set函数，用于处理字段值
+   * 字段值处理函数，在 onUpdateValue 前执行
+   *
+   * 函数返回值作为更新值；也可传 `{ get, set }` 对象分别处理读取与写入
    * @example (val) => val?.trim()
    */
   valueFormatter?: ValueFormatter;
   /**
-   * @description 组件v-model双向绑定更新属性名，默认'modelValue'
+   * v-model 绑定的属性名，默认 `modelValue`
    */
   modelProp?: string;
 };
 
 /**
- * @type {Object} Base - 基础公共字段类型
+ * 基础公共字段类型（非嵌套字段与嵌套字段两个分支）
  */
 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'
@@ -250,7 +262,7 @@ export type FieldTypeMap<D extends Data = Data> = {
 };
 
 /**
- * @description 不支持响应式的属性名
+ * 不支持响应式取值的字段属性名
  */
 type NotSupportedRefOrGetterProps =
   | 'component'
@@ -264,7 +276,8 @@ type NotSupportedRefOrGetterProps =
 type MaybeRefOrComputedRef<T = any> = MaybeRef<T> | ComputedRef<T>;
 
 /**
- * @description 为对象属性添加响应式支持的类型
+ * 为对象属性添加响应式支持的类型
+ *
  * @template T - 原始类型
  */
 export type WithRef<T> = {
@@ -288,7 +301,7 @@ type WithFields<D extends Data = Data> = WithRef<
 >;
 
 /**
- * @description 合并 FormItem 插槽与组件插槽
+ * 合并 FormItem 插槽与组件插槽
  */
 export type MergeSlots<T, CS = ComponentSlots<T>> = Partial<{
   [K in keyof FormItemSlots | keyof CS]: K extends keyof FormItemSlots
@@ -299,7 +312,8 @@ export type MergeSlots<T, CS = ComponentSlots<T>> = Partial<{
 }>;
 
 /**
- * @description 自动从 Vue 组件提取 Props 和 Slots，并加上公共表单字段属性
+ * 从 Vue 组件提取 Props 与 Slots，并叠加公共字段属性
+ *
  * @template T - Vue 组件类型
  * @template D - 数据对象类型
  */
@@ -311,24 +325,29 @@ type WithComponent<T, D extends Data = Data> = Omit<
 };
 
 /**
- * @description 字段配置类型，包含所有字段属性和响应式支持
+ * 字段配置类型，包含字段属性、响应式取值与宿主组件 Props
+ *
+ * @template C - 组件名，默认覆盖全部内置组件名
  * @template D - 数据对象类型
- 
+ *
  * @public
  */
 export type Field<
   C extends ComponentName = ComponentName,
   D extends Data = Data,
-> =
+> = (
   | (FieldTypeMap<D>[C] & {
       component?: C extends 'custom' ? FieldTypeMap<D>[C]['component'] : C;
     })
-  | WithFields<D>;
+  | WithFields<D>
+) &
+  AdditionalMethods<FormItemInstance>;
 
 /**
- * @description 字段数组类型
+ * 字段配置数组类型
+ *
  * @template D - 数据对象类型
- 
+ *
  * @public
  */
 export type Fields<D extends Data = Data> = Array<Field<ComponentName, D>>;

package/src/components/form/utils/fieldKey.ts

@@ -0,0 +1,27 @@
+import { toRaw } from 'vue';
+
+const fieldKeyMap = new WeakMap<object, number>();
+let fieldKeySeed = 0;
+
+/**
+ * 字段渲染 key
+ *
+ * @description 以 `toRaw(field)` 为键在模块级 WeakMap 中缓存自增编号，同一字段对象恒得同一 key：
+ * key 与字段在数组中的位置解耦，字段插入 / 删除 / 重排 / 过滤后仍与对象绑定；同 `path` 的兄弟字段各得其唯一 key。
+ * 非对象项无对象身份，按字面量生成稳定 key；渲染路径传入的字段项已由调用方过滤为非 null 对象，
+ * 该分支供本模块的直接调用者使用
+ *
+ * @param field - 字段配置项
+ * @returns 字段渲染 key
+ */
+export const getFieldKey = (field: unknown): string | number => {
+  if (field === null || typeof field !== 'object')
+    return `raw_${String(field)}`;
+  const raw = toRaw(field);
+  let key = fieldKeyMap.get(raw);
+  if (key === undefined) {
+    key = ++fieldKeySeed;
+    fieldKeyMap.set(raw, key);
+  }
+  return key;
+};

package/src/components/table/components/ColumnControl.vue

@@ -1,4 +1,13 @@
 <script lang="ts" setup>
+/**
+ * 列显隐控制控件，以下拉菜单列出可控列并支持全选/取消全选
+ *
+ * @component ColumnControl
+ *
+ * @param {Columns} columns - 参与控制的列配置（由 ProTable 下发）
+ * @param {Table} [table] - 表格实例，勾选结果经其 `setColumn` 写回列 `hidden`
+ * @param {ColumnControlConfig} [columnControl] - 控制项配置：labels / excludedKeys / disabledKeys / disableCheckAll
+ */
 import {
   Button,
   Dropdown,
@@ -6,12 +15,12 @@ import {
   DropdownItem,
   Checkbox,
 } from '../../../shared/ui';
-import { computed, ref, watch } from 'vue';
+import { toValue, computed, ref, watch } from 'vue';
 import type { Column, Columns, ColumnControlConfig } from '../types';
-import { type Table } from '../useTable';
+import { type Table } from '../hooks';
 import FilterOutlined from './icons/FilterOutlined.vue';
 import { useLocale } from '../../../locale';
-import { normalizePathKey } from '../../../shared/core';
+import { isObjectItem, normalizePathKey } from '../../../shared/core';
 
 type Props = {
   columns: Columns;
@@ -29,7 +38,8 @@ const checkAll = ref(false);
 const indeterminate = ref(false);
 
 const getColumnKey = (column: Column) => {
-  const rawKey = column.key ?? column.prop;
+  // 空字符串 key 视为未提供，回退 prop（与列渲染口径一致）
+  const rawKey = column.key || column.prop;
   if (rawKey === undefined || rawKey === null || rawKey === '')
     return undefined;
   return normalizePathKey(rawKey);
@@ -44,7 +54,7 @@ const checkedColumnsOptions = computed<
     column: Column;
   }>
 >(() =>
-  props.columns.flatMap(item => {
+  props.columns.filter(isObjectItem).flatMap(item => {
     const key = getColumnKey(item);
     // 无 key/prop 列不进入列控面板
     if (key === undefined) return [];
@@ -72,7 +82,7 @@ const checkedColumnsOptions = computed<
     return {
       label,
       value: key,
-      checked: !item.hidden || !!disabled,
+      checked: !toValue(item.hidden) || !!disabled,
       disabled: !!disabled,
       column: item,
     };