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

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,12 +26,27 @@
  *         └── 转发所有 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 default - 保留给列渲染器，传入内容不参与渲染，自定义区域请使用下列具名插槽
+ * @slot search-form - 搜索区域插槽（无作用域）
+ * @slot button-bar - 表格头部按钮区插槽
+ * @slot toolbar - 工具栏插槽
+ * @slot table - 表格区域插槽（无作用域）
  */
 import {
   Pagination as ElPagination,
@@ -43,9 +59,13 @@ import {
 } from '../../../shared/ui';
 import { ElLoading } from 'element-plus';
 import {
+  Comment,
+  Fragment,
+  Text,
   computed,
+  effect,
+  stop,
   nextTick,
-  useAttrs,
   onMounted,
   inject,
   toValue,
@@ -57,15 +77,18 @@ import ContainerFragment from '../../form/components/ContainerFragment/index.vue
 import type { ContainerComponent } from '../../form/types';
 import SearchForm from './SearchForm.vue';
 import type { SearchFormProps } from './SearchForm.vue';
-import type { Table } from '../useTable';
+import type { Table } from '../hooks';
 import { useLocale } from '../../../locale';
+import type { Path } from '../../../shared/core';
 import {
   camelizeProperties,
   getObject,
-  pick,
-  isPromise,
+  isObjectItem,
   isPlainObject,
-  Path,
+  isPromise,
+  omitBy,
+  pick,
+  useReactiveAttrs,
 } from '../../../shared/core';
 import DefaultSearchFormContainer from './DefaultSearchFormContainer.vue';
 import DefaultTableContainer from './DefaultTableContainer.vue';
@@ -86,14 +109,17 @@ const tableProperties = Object.keys(tableProps());
 const paginationProperties = Object.keys(paginationProps());
 
 type Control = {
+  /** 是否展示表格尺寸控制 */
   sizeControl: boolean;
+  /** 是否展示列控制，传对象时作为列控面板配置 */
   columnControl: boolean | ColumnControlConfig<Path<RecordType>>;
 };
 
+/** 搜索表单配置：SearchFormProps 去掉 form，并加上搜索区显隐与容器 */
 type SearchFormConfig = Omit<SearchFormProps, 'form'> & {
-  // 是否隐藏搜索表单
+  /** 是否隐藏搜索表单 */
   hidden?: boolean;
-  // 搜索区域包裹容器
+  /** 搜索区域包裹容器 */
   container?: ContainerComponent | false;
 };
 
@@ -101,25 +127,31 @@ type ReturnTableRecord<V> = V extends Table<any, infer R> ? R : any;
 type RecordType = ReturnTableRecord<T>;
 
 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;
+  /** 直接传入列配置（覆盖 :table 实例的 columns） */
   columns?: Columns<RecordType>;
+  /** 直接传入数据源（覆盖 :table 实例的 data） */
   data?: RecordType[];
+  /** 分页配置，传 false 禁用 */
   pagination?: false | Partial<PaginationProps>;
 } & /* @vue-ignore */ Omit<TableProps, 'data'>;
 
+/*
+ * 组件自身仅触发模型事件；宿主表格事件不入运行时 emits，监听入口保留在 attrs 中透传至 ElTable
+ */
 type Emits = {} & /* @vue-ignore */ TableEmits<RecordType>;
 
 defineEmits<Emits>();
@@ -143,34 +175,23 @@ const config = INJECT_CONFIG['pro-table'];
 const injectPropsRaw = inject(config.injectionKey, config.default);
 const injectProps = computed(() => toValue(injectPropsRaw) || {});
 
-const attrs = useAttrs() as Record<string, any>;
+const attrs = useReactiveAttrs() as Record<string, any>;
 
-const PRO_TABLE_EXCLUDED_ATTR_KEYS = new Set([
+// 组件自身消费的 attrs 键：class / style 绑定根节点，onSearch / onChange 由搜索与分页流程消费
+const PRO_TABLE_CONSUMED_ATTR_KEYS = new Set([
   'class',
   'style',
   'onSearch',
   'onChange',
-  'onUpdate:size',
-  'onUpdate:loading',
-  'data',
-  'columns',
-  'size',
-  'pagination',
 ]);
 
-const PRO_TABLE_PROVIDER_KEYS = new Set([
-  'pagination',
-  'searchFormConfig',
-  'control',
-  'immediateSearch',
-  'addIndexColumn',
-  'tableContainer',
-]);
+// 组件自身消费的 props 键：对应值按 prop / provider 单一来源派生，provider 注入不再透传这些键
+const PRO_TABLE_PROP_KEYS = new Set(Object.keys(props));
 
 const injectTableAttrs = computed(() => {
   const tableConfig: Record<string, any> = {};
   for (const [key, value] of Object.entries(injectProps.value)) {
-    if (!PRO_TABLE_PROVIDER_KEYS.has(key)) {
+    if (!PRO_TABLE_PROP_KEYS.has(key)) {
       tableConfig[key] = value;
     }
   }
@@ -178,20 +199,20 @@ const injectTableAttrs = computed(() => {
 });
 
 const attrsTableProps = computed(() => {
-  return pick(
-    camelizeProperties(attrs),
-    tableProperties
+  return omitBy(
+    pick(camelizeProperties(attrs), tableProperties),
+    value => value === undefined
   ) as Partial<TableProps>;
 });
 
 const restTableAttrs = computed(() => {
   const rest: Record<string, any> = {};
   for (const [key, value] of Object.entries(attrs)) {
-    if (!PRO_TABLE_EXCLUDED_ATTR_KEYS.has(key)) {
+    if (!PRO_TABLE_CONSUMED_ATTR_KEYS.has(key)) {
       rest[key] = value;
     }
   }
-  return rest;
+  return omitBy(rest, value => value === undefined);
 });
 
 const size = defineModel<TableProps['size']>('size');
@@ -199,23 +220,28 @@ 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;
@@ -250,8 +276,57 @@ type CustomSlots = Readonly<
 type Slots = CustomSlots & Readonly<Record<string, Slot>>;
 
 const slots = useSlots() as Slots;
-const forwardedSlotNames = () =>
-  Object.keys(slots).filter(name => !customSlotNames.includes(name as any));
+
+/** 插槽产出是否含可渲染内容：注释节点与空白文本不计 */
+const hasRenderableContent = (nodes: unknown): boolean => {
+  if (nodes === null || nodes === undefined || nodes === false) return false;
+  if (typeof nodes === 'string') return nodes.trim() !== '';
+  if (typeof nodes === 'number') return true;
+  if (Array.isArray(nodes)) return nodes.some(hasRenderableContent);
+  const vnode = nodes as { type?: unknown; children?: unknown };
+  if (vnode.type === Comment) return false;
+  if (vnode.type === Text) return String(vnode.children ?? '').trim() !== '';
+  if (vnode.type === Fragment) return hasRenderableContent(vnode.children);
+  return true;
+};
+
+/*
+ * 求值一次 default 插槽产出，用于判定是否有可渲染内容（空插槽 / 包装组件透传不提示）。
+ * 求值由一次性 effect 执行并立即停止，插槽内的响应式读取不进入 ProTable 的渲染依赖。
+ */
+const evaluateSlotContent = (): boolean => {
+  let hasContent = false;
+  const runner = effect(() => {
+    try {
+      hasContent = hasRenderableContent(slots.default?.());
+    } catch {
+      // 产出无法求值时按有内容处理，照常提示 default 插槽被保留
+      hasContent = true;
+    }
+  });
+  stop(runner);
+  return hasContent;
+};
+
+// default 插槽保留给列渲染器，同名用户插槽不透传宿主表格
+let defaultSlotChecked = false;
+const checkDefaultSlot = () => {
+  if (defaultSlotChecked) return;
+  if (!Object.prototype.hasOwnProperty.call(slots, 'default')) return;
+  defaultSlotChecked = true;
+  if (evaluateSlotContent()) {
+    console.warn(
+      '[pro-components] ProTable 的 default 插槽保留用于列渲染，已忽略传入的 default 插槽内容；自定义区域请使用 search-form / button-bar / toolbar / table 具名插槽。'
+    );
+  }
+};
+
+const forwardedSlotNames = () => {
+  checkDefaultSlot();
+  return Object.keys(slots).filter(
+    name => name !== 'default' && !customSlotNames.includes(name as any)
+  );
+};
 
 const searchPage1st = () => {
   props.table?.setPageParam?.({ current: 1 });
@@ -270,6 +345,16 @@ const computedSearchFormConfig = computed(() => {
   };
 });
 
+/** SearchForm 属性面：容器与显隐由 ProTable 自身消费，不下发 SearchForm */
+const searchFormProps = computed(() => {
+  const {
+    container: _container,
+    hidden: _hidden,
+    ...rest
+  } = computedSearchFormConfig.value;
+  return rest;
+});
+
 const computedTableContainer = computed(() => {
   const container =
     props.tableContainer ??
@@ -278,19 +363,26 @@ const computedTableContainer = computed(() => {
   return container ? container : undefined;
 });
 
+/*
+ * 序号列随有效分页偏移：分页关闭时退化为 index + 1；
+ * current / pageSize 取有效分页（显式 :pagination 或 Provider 注入），table.pageParam 仅作兜底
+ */
 const getIndex = (i: number) => {
-  if (props.table?.pageParam && computedPagination.value !== false) {
-    const current = props.table.pageParam.current ?? 1;
-    const pageSize = props.table.pageParam.pageSize ?? 10;
-    return (current - 1) * pageSize + i + 1;
-  }
-  return i + 1;
+  const pagination = computedPagination.value;
+  if (pagination === false) return i + 1;
+  const pageParam = props.table?.pageParam;
+  const current = pagination.currentPage ?? pageParam?.current ?? 1;
+  const pageSize = pagination.pageSize ?? pageParam?.pageSize ?? 10;
+  return (current - 1) * pageSize + i + 1;
 };
 
+/** 调用方是否显式传入 columns（值为 undefined 时视为未指定） */
+const hasExplicitColumns = computed(() => props.columns !== undefined);
+
 const normalizedRawColumns = computed(() => {
-  const source = (props.columns ??
-    toValue(props.table?.columns) ??
-    []) as any[];
+  const source = (
+    (props.columns ?? toValue(props.table?.columns) ?? []) as any[]
+  ).filter(isObjectItem);
   if (props.addIndexColumn ?? injectProps.value.addIndexColumn) {
     return [
       {
@@ -307,35 +399,25 @@ const normalizedRawColumns = computed(() => {
 });
 
 const computedDataSource = computed<any[]>(() => {
-  const attrsData = attrsTableProps.value.data as any[] | undefined;
-  return props.data ?? attrsData ?? toValue(props.table?.data) ?? [];
+  return props.data ?? toValue(props.table?.data) ?? [];
 });
 
 const computedTableProps = computed<TableProps>(() => {
-  const merged = {
+  return {
     ...injectTableAttrs.value,
     ...restTableAttrs.value,
     ...attrsTableProps.value,
   } as TableProps;
-  delete (merged as any).data;
-  delete (merged as any).columns;
-  delete (merged as any).size;
-  delete (merged as any).pagination;
-  return merged;
 });
 
-// 分页优先级：tableAttrs 显式配置 > provider 全局配置 > 默认合成
+/*
+ * 分页来源：分页开关与展示配置取 props.pagination 显式配置 > provider 全局配置 > 默认合成；
+ * currentPage / pageSize / total 以 table.pageParam 为实时状态，显式配置仅在 pageParam 缺省时兜底
+ */
 const computedPagination = computed<false | Partial<PaginationProps>>(() => {
-  const attrsPagination = (attrsTableProps.value as any).pagination;
-  if (props.pagination === false || attrsPagination === false) {
-    return false;
-  }
-  const hasUserPagination =
-    isPlainObject(props.pagination) || isPlainObject(attrsPagination);
-  if (hasUserPagination) {
-    const pageConfig = (props.pagination ??
-      attrsPagination ??
-      {}) as Partial<PaginationProps>;
+  if (props.pagination === false) return false;
+  if (isPlainObject(props.pagination)) {
+    const pageConfig = props.pagination as Partial<PaginationProps>;
     const globalPagination =
       (injectProps.value.pagination as any) === false
         ? {}
@@ -386,11 +468,15 @@ const searchFormVisible = computed(() => {
   return !!(
     (computedSearchFormConfig.value as any)?.hidden !== true &&
     props.table?.searchForm &&
-    fieldList.filter((item: any) => !toValue(item.hidden))?.length > 0
+    fieldList.filter((item: any) => isObjectItem(item) && !toValue(item.hidden))
+      .length > 0
   );
 });
 
-const computedControl = computed<{
+/*
+ * 控制项来源：显式控制配置 > Provider 全局配置
+ */
+const resolvedControl = computed<{
   sizeControl: boolean;
   columnControl: boolean | ColumnControlConfig<Path<RecordType>>;
 }>(() => {
@@ -404,17 +490,21 @@ const computedControl = computed<{
   return { sizeControl: !!sizeControl, columnControl };
 });
 
+/* 显式 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;
 });
 
+// 尺寸来源：size 模型 > provider 全局配置
 const resolvedSize = computed(() => {
-  return (
-    size.value ??
-    (attrsTableProps.value.size as any) ??
-    injectTableAttrs.value.size
-  );
+  return size.value ?? injectProps.value.size;
 });
 
 onMounted(() => {
@@ -439,7 +529,7 @@ defineExpose({
         <SearchForm
           v-if="props.table?.searchForm"
           :form="props.table.searchForm"
-          v-bind="computedSearchFormConfig"
+          v-bind="searchFormProps"
           @search="searchPage1st"
           @reset="reset"
         />
@@ -458,7 +548,7 @@ defineExpose({
           v-if="computedControl.sizeControl"
           class="pro-table_header_size-control"
         >
-          <SizeControl v-model:size="size" />
+          <SizeControl v-model:size="size" :effective-size="resolvedSize" />
         </div>
         <div
           v-if="computedControl.columnControl"

package/src/components/table/components/SearchForm.vue

@@ -1,8 +1,8 @@
 <script lang="ts">
 type Expand = {
-  // 网格布局时默认展开行数量
+  /** 网格布局时默认展开行数量 */
   minExpandRows?: number;
-  // 网格布局时展开状态
+  /** 网格布局时展开状态 */
   expandStatus?: boolean;
 };
 
@@ -21,17 +21,28 @@ type _FormProps = Pick<
 type ButtonProps = { onClick: () => void };
 type ExpandButtonProps = ButtonProps & { expandStatus: boolean };
 
+/**
+ * 搜索表单属性面，由 ProTable 经 `searchFormConfig` 下发
+ */
 export type SearchFormProps = {
+  /** 搜索表单实例，由 table.searchForm 提供 */
   form: Form;
+  /** 布局形态，默认 'grid' */
   layout?: 'grid' | 'inline';
+  /** 展开配置，默认 true */
   expand?: boolean | Expand;
+  /** 自定义搜索按钮，false 时不渲染 */
   searchButton?: Component<ButtonProps> | DefineComponent<ButtonProps> | false;
+  /** 自定义重置按钮，false 时不渲染 */
   resetButton?: Component<ButtonProps> | DefineComponent<ButtonProps> | false;
+  /** 自定义展开/折叠按钮，false 时不渲染 */
   expandButton?:
     | Component<ExpandButtonProps>
     | DefineComponent<ExpandButtonProps>
     | false;
+  /** 行间距，默认 16 */
   rowGap?: number;
+  /** 列间距，默认 24 */
   columnGap?: number;
 } & /* @vue-ignore */ _FormProps &
   AllowedComponentProps;
@@ -39,30 +50,40 @@ export type SearchFormProps = {
 
 <script lang="ts" setup>
 /**
+ * ProTable 的搜索表单子组件
+ *
  * @component SearchForm
- * @description ProTable 的搜索表单子组件
  *
  * ## 核心功能
  *
  * 1. 内部渲染 ProForm，使用 table.searchForm 管理搜索条件
  * 2. 支持 grid（网格）和 inline（行内）两种布局
- * 3. 网格布局下支持展开/折叠（溢出检测与初值自动展开见下方机制说明）
+ * 3. 网格布局下支持展开/折叠
  * 4. 提供搜索、重置、展开/折叠按钮（支持自定义）
  *
- * ## 展开/折叠机制
+ * ## 展开/折叠行为
+ *
+ * 1. 内容高度超出折叠高度（由 minExpandRows 决定，默认 2 行）时显示展开/折叠按钮
+ * 2. 隐藏区域存在搜索值时自动展开
+ * 3. 用户手动切换后保持手动状态，不随重新测量回退
+ *
+ * @param {Form} form - 搜索表单实例，由 table.searchForm 提供
+ * @param {'grid' | 'inline'} [layout] - 布局形态，默认 'grid'
+ * @param {boolean | Expand} [expand] - 展开配置，默认 true
+ * @param {Component<ButtonProps> | DefineComponent<ButtonProps> | false} [searchButton] - 自定义搜索按钮，false 时不渲染
+ * @param {Component<ButtonProps> | DefineComponent<ButtonProps> | false} [resetButton] - 自定义重置按钮，false 时不渲染
+ * @param {Component<ExpandButtonProps> | DefineComponent<ExpandButtonProps> | false} [expandButton] - 自定义展开/折叠按钮，false 时不渲染
+ * @param {number} [rowGap] - 行间距，默认 16
+ * @param {number} [columnGap] - 列间距，默认 24
  *
- * 1. 首次渲染后，测量 ProForm 的实际高度
- * 2. 根据 minExpandRows 计算折叠高度（默认 2 行）
- * 3. 如果实际高度 > 折叠高度，显示展开/折叠按钮
- * 4. 使用 IntersectionObserver 检测隐藏字段是否有值，有值则自动展开
+ * @slot reset-button - 重置按钮插槽，作用域参数 onReset
+ * @slot search-button - 搜索按钮插槽，作用域参数 onSearch
+ * @slot expand-button - 展开/折叠按钮插槽，作用域参数 expandStatus / changeExpandStatus
  */
-import { Space, Button, FormProps } from '../../../shared/ui';
-import {
-  AllowedComponentProps,
-  computed,
-  type Component,
-  type DefineComponent,
-} from 'vue';
+import type { FormProps } from '../../../shared/ui';
+import { Space, Button } from '../../../shared/ui';
+import type { AllowedComponentProps } from 'vue';
+import { computed, nextTick, type Component, type DefineComponent } from 'vue';
 import ProForm from '../../form/components/ProForm/index.vue';
 import { type Form } from '../../form/hooks/useForm';
 import DownOutlined from './icons/DownOutlined.vue';
@@ -81,7 +102,6 @@ const props = withDefaults(defineProps<SearchFormProps>(), {
   expandButton: undefined,
   rowGap: 16,
   columnGap: 24,
-  form: undefined,
 });
 
 type Emits = {
@@ -122,10 +142,28 @@ const onReset = () => {
   emit('reset');
 };
 
-// 查询按钮为 native-type=submit：点击与回车统一经表单 submit 事件触发
-const onSearch = () => {
+// 同一 tick 内 click 与 submit 只放行首个触达者，下一 tick 释放标记
+let searchTriggeredInTick = false;
+
+const emitSearch = () => {
+  searchTriggeredInTick = true;
+  nextTick(() => {
+    searchTriggeredInTick = false;
+  });
   emit('search');
 };
+
+// 默认查询按钮为 native-type=submit：点击与回车统一经表单 submit 事件触发
+const onSearchSubmit = () => {
+  if (searchTriggeredInTick) return;
+  emitSearch();
+};
+
+// 自定义查询按钮与 search-button 插槽经 click 触发
+const onSearchClick = () => {
+  if (searchTriggeredInTick) return;
+  emitSearch();
+};
 </script>
 
 <template>
@@ -133,7 +171,7 @@ const onSearch = () => {
     v-bind="layoutProps"
     :form="props.form"
     class="pro-table_search-form transition"
-    @submit.prevent="onSearch"
+    @submit.prevent="onSearchSubmit"
   >
     <Space alignment="start" class="pro-table_search-form_button-group">
       <slot name="reset-button" :on-reset="onReset">
@@ -152,12 +190,12 @@ const onSearch = () => {
           </Button>
         </template>
       </slot>
-      <slot name="search-button" :on-search="onSearch">
+      <slot name="search-button" :on-search="onSearchClick">
         <template v-if="props.searchButton !== false">
           <component
             :is="props.searchButton"
             v-if="props.searchButton"
-            @click="onSearch"
+            @click="onSearchClick"
           />
           <Button
             v-else

package/src/components/table/components/SizeControl.vue

@@ -1,9 +1,18 @@
 <script lang="ts" setup>
+/**
+ * 表格尺寸切换控件，以图标按钮 + 下拉菜单呈现
+ *
+ * @component SizeControl
+ *
+ * @param {Size} [size] - 表格尺寸（`v-model:size`），仅用于回写选中结果
+ * @param {Size} [effectiveSize] - 表格实际使用的尺寸，用于高亮选中项；未提供时依次回退 `size`、宿主 ConfigProvider 的尺寸
+ */
 import {
   Dropdown,
   DropdownMenu,
   DropdownItem,
   Button,
+  useSize,
   type TableProps,
 } from '../../../shared/ui';
 import ColumnHeightOutlined from './icons/ColumnHeightOutlined.vue';
@@ -14,9 +23,22 @@ type Size = TableProps['size'];
 
 const { t } = useLocale();
 
+const props = withDefaults(
+  defineProps<{
+    effectiveSize?: Size;
+  }>(),
+  { effectiveSize: undefined }
+);
+
 const size = defineModel<Size>('size');
 
-const currentSize = computed(() => size.value ?? 'default');
+// 宿主 ConfigProvider / 表单上下文的尺寸兜底
+const hostSize = useSize();
+
+// 高亮项：表格有效尺寸 > 本地绑定 > 宿主 ConfigProvider 尺寸 > 默认
+const currentSize = computed(
+  () => (props.effectiveSize ?? size.value ?? hostSize.value) || 'default'
+);
 
 const items = computed<Array<{ label: string; key: NonNullable<Size> }>>(() => [
   { label: t('table.sizeDefault'), key: 'default' },