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

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,
     };
   })

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>

package/src/components/table/components/ProTable.vue

@@ -1,7 +1,8 @@
 <script lang="ts" setup generic="T extends Table<any> = Table">
 /**
+ * 配置驱动的表格组件
+ *
  * @component ProTable
- * @description 配置驱动的表格组件
  *
  * ## 架构概览
  *
@@ -25,24 +26,38 @@
  *         └── 转发所有 table 插槽
  * ```
  *
- * ## 搜索流程
+ * ## 搜索行为
+ *
+ * 1. 搜索：分页回到第一页后发起查询
+ * 2. 分页变化：分页参数同步后发起查询
+ * 3. 重置：查询参数恢复初始值后重新查询
+ *
+ * @template T - 表格实例类型（useTable 返回值）
  *
- * 1. 用户点击搜索 → SearchForm @search → searchPage1st()
- * 2. searchPage1st 重置分页到第一页，触发 _search()
- * 3. 分页变化 → onTableChange → setPageParam + _search()
- * 4. 重置 → reset() → resetQueryParams + _search()
+ * @param {T} [table] - 列表表格对象，来自 useTable
+ * @param {() => Promise<unknown>} [search] - 列表数据查询方法
+ * @param {boolean} [addIndexColumn] - 是否在首列插入序号列
+ * @param {boolean} [immediateSearch] - 挂载后是否立即触发一次查询
+ * @param {boolean | Partial<Control>} [control] - 是否展示尺寸与列控制按钮；显式传入 columns 时列控入口不渲染
+ * @param {SearchFormConfig} [searchFormConfig] - 搜索栏查询字段表单配置
+ * @param {ContainerComponent | false} [tableContainer] - 表格区域包裹容器
+ *
+ * @slot search-form - 搜索区域插槽，作用域参数 form / search / reset
+ * @slot button-bar - 表格头部按钮区插槽
+ * @slot toolbar - 工具栏插槽
+ * @slot default - 透传给宿主表格的默认插槽（可用于以宿主列组件声明列）
+ * @slot table - 表格区域插槽，作用域参数 columns / dataSource / pagination / loading / size / onChange
  */
-import {
+import type {
   PaginationProps,
-  Table as ATable,
   TableProps,
   ColumnType,
-  tableProps,
 } from '../../../shared/ui';
+import { Table as ATable, tableProps } from '../../../shared/ui';
 import {
   computed,
+  getCurrentInstance,
   nextTick,
-  useAttrs,
   onMounted,
   inject,
   toValue,
@@ -52,23 +67,26 @@ import { INJECT_CONFIG } from '../../component-provider/constants';
 import ContainerFragment from '../../form/components/ContainerFragment/index.vue';
 import type { ContainerComponent } from '../../form/types';
 import SearchForm from './SearchForm.vue';
-import { SearchFormProps } from './SearchForm.vue';
+import type { SearchFormProps } from './SearchForm.vue';
 import type { Table } from '../hooks/useTable';
 import { useLocale } from '../../../locale';
+import type { Path } from '../../../shared/core';
 import {
+  camelizeProperties,
   getObject,
+  isObjectItem,
   isPlainObject,
-  pick,
   isPromise,
-  camelizeProperties,
-  Path,
+  omitBy,
+  pick,
+  useReactiveAttrs,
 } from '../../../shared/core';
-import { ComponentSlots } from 'vue-component-type-helpers';
+import type { ComponentSlots } from 'vue-component-type-helpers';
 import DefaultSearchFormContainer from './DefaultSearchFormContainer.vue';
 import DefaultTableContainer from './DefaultTableContainer.vue';
 import SizeControl from './SizeControl.vue';
 import ColumnControl from './ColumnControl.vue';
-import { Column, Columns, ColumnControlConfig } from '../types';
+import type { Column, Columns, ColumnControlConfig } from '../types';
 
 defineOptions({ name: 'ProTable', inheritAttrs: false });
 
@@ -87,19 +105,19 @@ type SearchFormConfig = Omit<SearchFormProps, 'form'> & {
 };
 
 type Props = {
-  // 列表表格对象，returns from useTable
+  /** 列表表格对象，来自 `useTable` */
   table?: T;
-  // 列表数据查询方法
+  /** 列表数据查询方法 */
   search?: () => Promise<unknown>;
-  // 是否在首列插入index列
+  /** 是否在首列插入序号列 */
   addIndexColumn?: boolean;
-  // onMounted 时立即触发一次search事件
+  /** 挂载后是否立即触发一次查询 */
   immediateSearch?: boolean;
-  // 是否展示表格 size 和 column 控制按钮
+  /** 是否展示尺寸与列控制按钮；显式传入 columns 时列控入口不渲染 */
   control?: boolean | Partial<Control>;
-  // 搜索栏查询字段表单配置
+  /** 搜索栏查询字段表单配置 */
   searchFormConfig?: SearchFormConfig;
-  // 表格区域包裹容器
+  /** 表格区域包裹容器 */
   tableContainer?: ContainerComponent | false;
 } & /* @vue-ignore */ TableProps;
 
@@ -119,6 +137,7 @@ const config = INJECT_CONFIG['pro-table'];
 const injectPropsRaw = inject(config.injectionKey, config.default);
 const injectProps = computed(() => toValue(injectPropsRaw) || {});
 
+/* Provider 注入的不可注入键（columns / dataSource / loading）已在注入层剔除，此处直接取用其注入属性 */
 const injectAttrs = computed<TableProps>(
   () => pick(injectProps.value, tableProperties) as TableProps
 );
@@ -135,33 +154,45 @@ const computedSearchFormConfig = computed(() => {
   };
 });
 
-const attrs: Record<string, any> = useAttrs();
-const tableAttrs = computed<TableProps>(() => {
-  return pick(camelizeProperties(attrs), tableProperties) as TableProps;
+/** SearchForm 属性面：容器与显隐由 ProTable 自身消费，不下发 SearchForm */
+const searchFormProps = computed(() => {
+  const {
+    container: _container,
+    hidden: _hidden,
+    ...rest
+  } = computedSearchFormConfig.value;
+  return rest;
 });
 
+const attrs: Record<string, any> = useReactiveAttrs();
+
 const size = defineModel<TableProps['size']>('size');
 const loading = defineModel<boolean>('loading', { default: false });
 
 // 递增序号做请求竞态守卫，仅最新一次请求可变更 loading
 let searchSequence = 0;
-let warnedSearchConfig = false;
-const warnSearchConfig = (reason: string) => {
-  if (warnedSearchConfig) return;
-  warnedSearchConfig = true;
-  console.warn(`[ProTable] ${reason}`);
+// 告警文案按原因分键，各原因独立去重
+const SEARCH_WARN_MESSAGES = {
+  duplicate:
+    '同时配置了 :search prop 与 @search 监听，@search 监听不会被执行，请仅保留其一。',
+  'not-promise':
+    'search 未返回 Promise，本次查询不参与 loading 竞态管理（在途请求的 loading 状态保持不变）。',
+} as const;
+const warnedSearchReasons = new Set<keyof typeof SEARCH_WARN_MESSAGES>();
+const warnSearchConfig = (reason: keyof typeof SEARCH_WARN_MESSAGES) => {
+  if (warnedSearchReasons.has(reason)) return;
+  warnedSearchReasons.add(reason);
+  console.warn(`[ProTable] ${SEARCH_WARN_MESSAGES[reason]}`);
 };
 const _search = async () => {
+  const search = props.search || attrs.onSearch;
   if (props.search && attrs.onSearch) {
-    warnSearchConfig(
-      '同时配置了 :search prop 与 @search 监听，@search 监听不会被执行，请仅保留其一。'
-    );
+    warnSearchConfig('duplicate');
   }
-  const searchPromise = (props.search || attrs.onSearch)?.();
+  if (!search) return;
+  const searchPromise = search();
   if (!isPromise(searchPromise)) {
-    warnSearchConfig(
-      'search 未返回 Promise，本次查询不参与 loading 竞态管理（在途请求的 loading 状态保持不变）。'
-    );
+    warnSearchConfig('not-promise');
     return;
   }
   const seq = ++searchSequence;
@@ -218,10 +249,15 @@ const columnRequiredSlotNames = new Set([
 ]);
 
 /**
- * 判定插槽是否具备渲染条件（守卫过渡状态或空列下 column 为 undefined 的情况）
- * 当列被动态隐藏或所有列均隐藏时，旧单元格销毁过渡帧或空占位中 column 可能为 undefined，
- * 此时阻断依赖 column 的业务插槽调用；
- * 非列依赖的表格级插槽（如 emptyText、footer、summary 等）始终正常渲染。
+ * 判定插槽在当前渲染状态下是否可渲染。
+ *
+ * @description
+ * 依赖列信息的插槽（`bodyCell` / `headerCell` / `customFilterDropdown` / `customFilterIcon`）仅在存在可见列且作用域中存在 `column` 时渲染；
+ * 非列依赖的表格级插槽（如 `emptyText`、`footer`、`summary` 等）始终渲染。
+ *
+ * @param name - 插槽名
+ * @param scoped - 插槽作用域参数
+ * @returns 该插槽是否参与渲染
  */
 const isSlotRenderable = (name: string, scoped: any) => {
   if (columnRequiredSlotNames.has(name)) {
@@ -235,13 +271,65 @@ const searchPage1st = () => {
   _search();
 };
 
+const instance = getCurrentInstance();
+
+/** 调用方是否显式绑定该 prop（含 kebab-case 与 v-model 写法） */
+const isBoundProp = (name: string) => {
+  const vnodeProps = instance?.vnode.props || {};
+  const kebab = name.replace(/[A-Z]/g, char => `-${char.toLowerCase()}`);
+  return (
+    name in vnodeProps ||
+    kebab in vnodeProps ||
+    `onUpdate:${name}` in vnodeProps
+  );
+};
+
+/** attrs 的驼峰视图：模板中以 kebab-case 写法的绑定键在此归一 */
+const camelAttrs = computed<Record<string, any>>(() =>
+  camelizeProperties(attrs)
+);
+
+/*
+ * 组件自有键取值：`Props` 中声明的键取 prop，其余宿主键取 attrs（模板 kebab-case 绑定经归一后同键）；
+ * 均以调用方显式绑定为唯一来源，未绑定时不取值（留给 Provider 注入兜底）
+ */
+const resolveOwnedProp = (name: string) => {
+  const attrValue = camelAttrs.value[name];
+  return isBoundProp(name)
+    ? ((props as Record<string, any>)[name] ?? attrValue)
+    : attrValue;
+};
+
+/** 调用方是否显式传入 columns（prop 或 attrs 形态，值为 undefined 时视为未指定） */
+const hasExplicitColumns = computed(
+  () => resolveOwnedProp('columns') !== undefined
+);
+
+/*
+ * 表格尺寸单一来源：本地模型（显式绑定或 SizeControl 回写）> Provider 注入；
+ * 本地模型为 undefined 时视为未指定，Provider 注入值继续生效
+ */
+const effectiveSize = computed<TableProps['size']>(() => {
+  return size.value ?? injectAttrs.value.size;
+});
+
+/*
+ * 下发给宿主表格的属性：Provider 注入为底（其不可注入键已在注入层剔除），调用方绑定与 v-model 透传值覆盖同键。
+ * size / loading 为声明模型，其 onUpdate:* 回写通道不进入 attrs，无需另行剔除
+ */
 const computedTableProps = computed<TableProps>(() => {
-  return {
+  const merged = {
     ...injectAttrs.value,
-    ...tableAttrs.value,
-    pagination: undefined,
-    onChange: undefined,
-  };
+    ...omitBy(
+      pick(camelAttrs.value, tableProperties),
+      value => value === undefined
+    ),
+  } as Record<string, any>;
+  // onChange 由模板监听器收口，散落 attrs 中的同名监听器并入会形成重复回调
+  delete merged.onChange;
+  merged.size = effectiveSize.value;
+  merged.loading = undefined;
+  return merged as TableProps;
 });
 
 const computedTableContainer = computed(() => {
@@ -255,15 +343,17 @@ const computedTableContainer = computed(() => {
 type ReturnGenericParameterTypes<V> = V extends Table<any, infer R> ? R : never;
 type RecordType = ReturnGenericParameterTypes<T>;
 
-// 序号列随分页偏移：第 n 页首行序号 = (n-1)*pageSize + i + 1（无分页时退化为 index+1）
+/*
+ * 序号列随有效分页偏移：分页关闭时退化为 index + 1；
+ * current / pageSize 取有效分页（显式 :pagination 或 Provider 注入），table.pageParam 仅作兜底
+ */
 const getIndex = (i: number) => {
+  const pagination = computedPagination.value;
+  if (pagination === false) return i + 1;
   const pageParam = props.table?.pageParam;
-  if (pageParam && computedPagination.value !== false) {
-    const current = pageParam.current ?? 1;
-    const pageSize = pageParam.pageSize ?? 10;
-    return (current - 1) * pageSize + i + 1;
-  }
-  return i + 1;
+  const current = pagination.current ?? pageParam?.current ?? 1;
+  const pageSize = pagination.pageSize ?? pageParam?.pageSize ?? 10;
+  return (current - 1) * pageSize + i + 1;
 };
 
 const indexColumn = computed<ColumnType>(() => ({
@@ -274,26 +364,72 @@ const indexColumn = computed<ColumnType>(() => ({
   customRender: ({ index }) => getIndex(index),
 }));
 
+// 列来源优先级：显式绑定 > table 实例（useTable 创建的 columns）
 const computedColumns = computed<Columns<RecordType>>(() => {
-  const cols = (tableAttrs.value.columns ??
+  const cols = (resolveOwnedProp('columns') ??
     toValue(props.table?.columns) ??
     []) as any;
   const needIndex = props.addIndexColumn ?? injectProps.value.addIndexColumn;
   return needIndex ? [indexColumn.value, ...cols] : cols;
 });
 
+/*
+ * 递归过滤 hidden 列（含分组子列）：仅对被过滤过子列的列生成浅拷贝，
+ * 未发生变动的列保持原对象引用（每次 columns 变化执行一次，不在渲染期递归）
+ */
+const filterVisibleColumns = (
+  columns: any[],
+  ancestors: Set<object> = new Set()
+): { list: any[]; changed: boolean } => {
+  const list: any[] = [];
+  let changed = false;
+  for (const column of columns) {
+    if (!isObjectItem(column) || toValue((column as Column).hidden)) {
+      changed = true;
+      continue;
+    }
+    if (Array.isArray(column.children) && column.children.length > 0) {
+      // 环状分组列不再深入，重复出现的祖先引用直接剔除
+      if (ancestors.has(column)) {
+        changed = true;
+        continue;
+      }
+      ancestors.add(column);
+      const filtered = filterVisibleColumns(column.children, ancestors);
+      ancestors.delete(column);
+      if (filtered.changed) {
+        changed = true;
+        list.push({ ...column, children: filtered.list });
+        continue;
+      }
+    }
+    list.push(column);
+  }
+  return { list, changed };
+};
+
 const visibleComputedColumns = computed(() => {
-  return computedColumns.value.filter(item => !(item as Column).hidden);
+  return filterVisibleColumns(computedColumns.value).list;
 });
 
+// 数据源优先级：显式绑定 > table 实例（useTable 创建的 dataSource）
 const computedDataSource = computed<RecordType[]>(() => {
-  return tableAttrs.value.dataSource ?? toValue(props.table?.dataSource) ?? [];
+  return (
+    resolveOwnedProp('dataSource') ?? toValue(props.table?.dataSource) ?? []
+  );
 });
 
-// 分页优先级：tableAttrs 显式配置 > provider 全局配置 > 默认合成
+/*
+ * 分页优先级：显式绑定 > provider 全局配置 > 默认合成；
+ * provider 作为基础配置与 table.pageParam 合并，显式绑定的对象形态在其之上覆盖
+ */
 const computedPagination = computed<PaginationProps | false>(() => {
-  if (tableAttrs.value.pagination === false) return false;
-  if (isPlainObject(tableAttrs.value.pagination)) {
+  const attrsPagination = resolveOwnedProp('pagination') as
+    | PaginationProps
+    | false
+    | undefined;
+  if (attrsPagination === false) return false;
+  if (isPlainObject(attrsPagination)) {
     const globalPagination =
       injectAttrs.value.pagination === false
         ? {}
@@ -301,9 +437,9 @@ const computedPagination = computed<PaginationProps | false>(() => {
     return {
       ...globalPagination,
       ...props.table?.pageParam,
-      ...tableAttrs.value.pagination,
+      ...attrsPagination,
       showTotal:
-        tableAttrs.value.pagination?.showTotal ??
+        attrsPagination?.showTotal ??
         globalPagination?.showTotal ??
         ((total: number) => t('pagination.total', { total })),
     };
@@ -332,11 +468,15 @@ const searchFormVisible = computed(() => {
   return !!(
     computedSearchFormConfig.value?.hidden !== true &&
     props.table?.searchForm &&
-    fieldList.filter(item => !toValue(item.hidden)).length > 0
+    fieldList.filter(item => isObjectItem(item) && !toValue(item.hidden))
+      .length > 0
   );
 });
 
-const computedControl = computed<{
+/*
+ * 控制项来源：显式控制配置 > Provider 全局配置
+ */
+const resolvedControl = computed<{
   sizeControl: boolean;
   columnControl: boolean | ColumnControlConfig<Path<RecordType>>;
 }>(() => {
@@ -353,6 +493,13 @@ const computedControl = computed<{
   };
 });
 
+/* 显式 columns 模式下渲染源不受 table.setColumn 影响，列控入口隐藏 */
+const computedControl = computed(() =>
+  hasExplicitColumns.value && resolvedControl.value.columnControl
+    ? { ...resolvedControl.value, columnControl: false }
+    : resolvedControl.value
+);
+
 const columnControlConfig = computed(() => {
   const cc = computedControl.value.columnControl;
   return typeof cc === 'object' ? cc : undefined;
@@ -376,11 +523,14 @@ defineExpose({
       v-if="searchFormVisible || $slots['search-form']"
       :component="computedSearchFormConfig.container"
     >
-      <slot name="search-form">
+      <slot
+        name="search-form"
+        v-bind="{ form: props.table?.searchForm, search: searchPage1st, reset }"
+      >
         <SearchForm
           v-if="props.table?.searchForm"
           :form="props.table.searchForm"
-          v-bind="computedSearchFormConfig"
+          v-bind="searchFormProps"
           @search="searchPage1st"
           @reset="reset"
         />
@@ -399,7 +549,7 @@ defineExpose({
           v-if="computedControl.sizeControl"
           class="pro-table_header_size-control"
         >
-          <SizeControl v-model:size="size" />
+          <SizeControl v-model:size="size" :effective-size="effectiveSize" />
         </div>
         <div
           v-if="computedControl.columnControl"
@@ -413,11 +563,20 @@ defineExpose({
         </div>
       </div>
 
-      <slot name="table">
+      <slot
+        name="table"
+        v-bind="{
+          columns: visibleComputedColumns,
+          dataSource: computedDataSource,
+          pagination: computedPagination,
+          loading: loading,
+          size: effectiveSize,
+          onChange: onTableChange,
+        }"
+      >
         <ATable
           class="pro-table_content"
           v-bind="computedTableProps"
-          :size="size"
           :loading="loading"
           :columns="visibleComputedColumns"
           :data-source="computedDataSource"