@qin-ui/antd-vue-pro 2.4.4 → 2.5.0

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

@@ -4,27 +4,31 @@ import type {
   FormInstance,
   FormItemProps,
 } 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 { ComponentName, GetComponentType } from '../constants';
+import type { ComponentName, GetComponentType } from '../constants';
 import type { Data, Path } from '../../../shared/core';
+import type { AdditionalMethods } from '../../../shared/core';
+import type { FormItemInstance } from '../../../shared/ui';
 
 export type { FormInstance };
 
+/** 带 `path` 的组件属性：容器与插槽组件按该路径关联字段 */
 export type PathProps = { path?: string } & Data;
 
+/** `value` / `onUpdate:value` 形态的 v-model 属性 */
 export type VModelProps<T = any> = {
   value?: T;
   'onUpdate:value'?: (val: T) => void;
@@ -59,13 +63,14 @@ 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 插槽组件类型
+ * 插槽组件类型
  */
 export type SlotComponentType =
   | Component<PathProps>
@@ -78,45 +83,55 @@ 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>;
 
+/** 表单栅格开关：`true` 启用默认栅格，或传 `GridProps` 自定义 */
 export type Grid = boolean | (GridProps & {});
 
+/** FormItem 自身的插槽集合（label / extra / help / tooltip 等） */
 export type FormItemSlots = ComponentSlots<typeof FormItem>;
 
 type BaseCommon<D extends Data = Data> = {
   /**
-   * @description 字段标识namePath, 同name
+   * 字段标识namePath, 同name
+   *
+   * 字段标识按 `name`、`path` 的顺序取首个非 `null` / `undefined` 的值（`name` 优先），
+   * 结果经 `normalizePathKey` 归一化，供渲染标识与 core 字段查找 API（`getField` / `setField` 等）共用；
+   * `name` 仅参与标识解析，不落入控件属性透传。与 `element-plus-pro` 口径不同（该包宿主标识键为 `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插槽和component插槽
+   *
    * @example
    * ```js
    * slots: {
@@ -128,27 +143,32 @@ 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,12 +176,14 @@ type BaseCommon<D extends Data = Data> = {
 
 type BaseWithFields<D extends Data = Data> = BaseCommon<D> & {
   /**
-   * @description 嵌套子字段配置
+   * 嵌套子字段配置
+   *
    * @example [{ key: 'firstName', label: '名' }, { key: 'lastName', label: '姓' }]
    */
   fields: Fields<D>;
   /**
-   * @description 网格布局属性，true表示使用默认网格布局，针对具有嵌套字段的字段
+   * 网格布局属性，true表示使用默认网格布局，针对具有嵌套字段的字段
+   *
    * @example boolean | { gutter: 24 }
    */
   grid?: Grid;
@@ -178,46 +200,47 @@ type BaseWithoutFields<D extends Data = Data> = BaseCommon<D> & {
   fields?: undefined;
   grid?: never;
   /**
-   * @description 字段component样式属性
+   * 字段component样式属性
+   *
    * @example { width: '100%', borderColor: '#d9d9d9' }
    */
-  componentStyle?: CSSProperties;
+  componentStyle?: StyleValue;
   /**
-   * @description 字段component样式类名
+   * 字段component样式类名
+   *
    * @example 'custom-input' | 'error-input'
    */
-  componentClass?: string;
+  componentClass?: ClassValue;
   /**
-   * @description 字段component容器包裹组件
+   * 字段component容器包裹组件
+   *
    * @example (props, ctx) => h('div', { class: 'input-wrapper' }, ctx.slots.default?.())
    */
   componentContainer?: ContainerComponent;
   /**
-   * @description 字段值处理函数，在onUpdateValue前执行，函数返回值将作为更新值，也可设置get和set函数，用于处理字段值
+   * 字段值处理函数，在onUpdateValue前执行，函数返回值将作为更新值，也可设置get和set函数，用于处理字段值
+   *
    * @example (val) => val?.trim()
    */
   valueFormatter?: ValueFormatter;
   /**
-   * @description 组件v-model双向绑定更新属性名，默认'value'
+   * 组件v-model双向绑定更新属性名，默认'value'
    */
   modelProp?: string;
   /**
-   * @description 将属性附加到表单组件的 DOM 节点
+   * 将属性附加到表单组件的 DOM 节点
+   *
    * @example { 'data-test': 'input-value', 'aria-label': 'name' }
    */
   componentDataAttrs?: Record<string, 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'
     ? WithCommon<{ slots?: Slots; [x: string]: any }, D> & {
@@ -227,7 +250,7 @@ export type FieldTypeMap<D extends Data = Data> = {
 };
 
 /**
- * @description 不支持响应式的属性名
+ * 不支持响应式的属性名
  */
 type NotSupportedRefOrGetterProps =
   | 'component'
@@ -241,7 +264,8 @@ type NotSupportedRefOrGetterProps =
 type MaybeRefOrComputedRef<T = any> = MaybeRef<T> | ComputedRef<T>;
 
 /**
- * @description 为对象属性添加响应式支持的类型
+ * 为对象属性添加响应式支持的类型
+ *
  * @template T - 原始类型
  */
 export type WithRef<T> = {
@@ -252,6 +276,12 @@ export type WithRef<T> = {
       : MaybeRefOrComputedRef<T[P]>;
 };
 
+/**
+ * 公共字段属性集合：FormItem 透传属性与 GridItem 栅格属性
+ *
+ * 栅格行为边界：字段显式指定 `span` 时整体接管栅格，不再叠加 Provider 注入的响应式断点；
+ * 未指定 `span` 时使用注入的断点配置。
+ */
 type WithCommonBase<T = unknown> = T &
   Omit<FormItemProps, 'label'> &
   GridItemProps;
@@ -265,7 +295,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
@@ -276,7 +306,8 @@ export type MergeSlots<T, CS = ComponentSlots<T>> = Partial<{
 }>;
 
 /**
- * @description 自动从 Vue 组件提取 Props 和 Slots，并加上公共表单字段属性
+ * 自动从 Vue 组件提取 Props 和 Slots，并加上公共表单字段属性
+ *
  * @template T - Vue 组件类型
  * @template D - 数据对象类型
  */
@@ -288,17 +319,19 @@ type WithComponent<T, D extends Data = Data> = Omit<
 };
 
 /**
- * @description 字段配置类型，包含所有字段属性和响应式支持
+ * 字段配置类型，包含所有字段属性和响应式支持
+ *
  * @template D - 数据对象类型
  * @public
  */
 export type Field<
   C extends ComponentName = ComponentName,
   D extends Data = Data,
-> = FieldTypeMap<D>[C] | WithFields<D>;
+> = (FieldTypeMap<D>[C] | WithFields<D>) & AdditionalMethods<FormItemInstance>;
 
 /**
- * @description 字段数组类型
+ * 字段数组类型
+ *
  * @template D - 数据对象类型
  * @public
  */

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,
   MenuDivider,
@@ -7,15 +16,19 @@ import {
   MenuItem,
   Checkbox,
 } from '../../../shared/ui';
-import { computed, ref, watch } from 'vue';
+import { computed, ref, toValue, watch } from 'vue';
+import { isObjectItem } from '../../../shared/core';
 import type { Columns, ColumnControlConfig } from '../types';
 import { type Table } from '../hooks/useTable';
 import FilterOutlined from './icons/FilterOutlined.vue';
 import { useLocale } from '../../../locale';
 
 type Props = {
+  /** 参与控制的列配置（由 ProTable 下发） */
   columns: Columns;
+  /** 表格实例，勾选结果经其 `setColumn` 写回列 `hidden` */
   table?: Table;
+  /** 控制项配置：labels / excludedKeys / disabledKeys / disableCheckAll */
   columnControl?: ColumnControlConfig;
 };
 const props = withDefaults(defineProps<Props>(), {
@@ -30,6 +43,7 @@ const open = ref(false);
 const checkAll = ref(false);
 const indeterminate = ref(false);
 
+/** 下拉项：逐列解析出 key、显示名、勾选态与是否禁用 */
 const checkedColumnsOptions = computed<
   Array<{
     label: string;
@@ -38,7 +52,7 @@ const checkedColumnsOptions = computed<
     disabled: boolean;
   }>
 >(() =>
-  props.columns.flatMap(item => {
+  props.columns.filter(isObjectItem).flatMap(item => {
     const rawKey =
       item.key ??
       (Array.isArray(item.dataIndex)
@@ -62,7 +76,7 @@ const checkedColumnsOptions = computed<
     return {
       label,
       value: key,
-      checked: !item.hidden || disabled,
+      checked: !toValue(item.hidden) || disabled,
       disabled,
     };
   })
@@ -80,10 +94,12 @@ const checkedColumnKeys = computed({
     );
   },
   set(val) {
+    // 仅写 hidden 发生翻转的列
+    const checkedSet = new Set(val);
     checkedColumnsOptions.value.forEach(item => {
-      if (item.disabled) return;
+      if (item.disabled || item.checked === checkedSet.has(item.value)) return;
       props.table?.setColumn?.(item.value, {
-        hidden: !val.includes(item.value),
+        hidden: !checkedSet.has(item.value),
       });
     });
   },

package/src/components/table/components/DefaultSearchFormContainer.vue

@@ -1,4 +1,9 @@
 <script lang="ts" setup>
+/**
+ * 搜索区域默认包裹容器，提供统一的背景色与间距
+ *
+ * @component DefaultSearchFormContainer
+ */
 import { theme } from '../../../shared/ui';
 const { token } = theme.useToken();
 </script>

package/src/components/table/components/DefaultTableContainer.vue

@@ -1,4 +1,9 @@
 <script lang="ts" setup>
+/**
+ * 表格区域默认包裹容器，提供统一的背景色与内边距
+ *
+ * @component DefaultTableContainer
+ */
 import { theme } from '../../../shared/ui';
 const { token } = theme.useToken();
 </script>