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

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

@@ -21,17 +21,26 @@ type _FormProps = Pick<
 type ButtonProps = { onClick: () => void };
 type ExpandButtonProps = ButtonProps & { expandStatus: boolean };
 
+/** ProTable 搜索表单的属性面：表单实例、布局、展开与按钮自定义 */
 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 +48,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. 用户手动切换后保持手动状态，不随重新测量回退
  *
- * 1. 首次渲染后，测量 ProForm 的实际高度
- * 2. 根据 minExpandRows 计算折叠高度（默认 2 行）
- * 3. 如果实际高度 > 折叠高度，显示展开/折叠按钮
- * 4. 使用 IntersectionObserver 检测隐藏字段是否有值，有值则自动展开
+ * @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
+ *
+ * @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 +100,6 @@ const props = withDefaults(defineProps<SearchFormProps>(), {
   expandButton: undefined,
   rowGap: 16,
   columnGap: 24,
-  form: undefined,
 });
 
 type Emits = {
@@ -117,9 +135,28 @@ const onReset = () => {
   emit('reset');
 };
 
-const onSearch = () => {
+// 同一 tick 内 click 与 submit 只放行首个触达者，下一 tick 释放标记
+let searchTriggeredInTick = false;
+
+const emitSearch = () => {
+  searchTriggeredInTick = true;
+  nextTick(() => {
+    searchTriggeredInTick = false;
+  });
   emit('search');
 };
+
+// 默认查询按钮为 html-type=submit：点击与回车统一经表单 submit 事件触发
+const onSearchSubmit = () => {
+  if (searchTriggeredInTick) return;
+  emitSearch();
+};
+
+// 自定义查询按钮与 search-button 插槽经 click 触发
+const onSearchClick = () => {
+  if (searchTriggeredInTick) return;
+  emitSearch();
+};
 </script>
 
 <template>
@@ -127,6 +164,7 @@ const onSearch = () => {
     v-bind="layoutProps"
     :form="props.form"
     class="pro-table_search-form transition"
+    @submit.prevent="onSearchSubmit"
   >
     <Space align="start" class="pro-table_search-form_button-group">
       <slot name="reset-button" :on-reset="onReset">
@@ -144,19 +182,18 @@ const onSearch = () => {
           >
         </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
             class="pro-table_search-form_search-button"
             type="primary"
             html-type="submit"
-            @click="onSearch"
             >{{ t('table.query') }}
           </Button>
         </template>

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

@@ -1,4 +1,12 @@
 <script lang="ts" setup>
+/**
+ * 表格尺寸切换控件，以图标按钮 + 下拉菜单呈现
+ *
+ * @component SizeControl
+ *
+ * @param {Size} [size] - 表格尺寸（`v-model:size`），仅用于回写选中结果
+ * @param {Size} [effectiveSize] - 表格实际使用的尺寸，用于高亮选中项；未提供时依次回退 `size`、宿主 ConfigProvider 的 componentSize
+ */
 import {
   Dropdown,
   Menu,
@@ -17,10 +25,22 @@ const { t } = useLocale();
 
 const configContext = useConfigContextInject();
 
+const props = withDefaults(
+  defineProps<{
+    effectiveSize?: Size;
+  }>(),
+  { effectiveSize: undefined }
+);
+
 const size = defineModel<Size>('size');
 
+// 高亮项：表格有效尺寸 > 本地绑定 > 宿主 ConfigProvider 的 componentSize
 const currentSize = computed(
-  () => size.value ?? configContext.componentSize?.value ?? 'large'
+  () =>
+    props.effectiveSize ??
+    size.value ??
+    configContext.componentSize?.value ??
+    'large'
 );
 
 const onSizeChange = (val: any) => {

package/src/components/table/hooks/useTable.ts

@@ -9,7 +9,7 @@ import type {
   PageParam,
 } from '../../../shared/core';
 import type { Column, Columns } from '../types';
-import { Fields } from '../../form/types';
+import type { Fields } from '../../form/types';
 
 /**
  * 表格实例类型

package/src/components/table/index.ts

@@ -1,14 +1,19 @@
-import { ComponentExposed, ComponentProps } from 'vue-component-type-helpers';
+import type {
+  ComponentExposed,
+  ComponentProps,
+} from 'vue-component-type-helpers';
 import ProTable from './components/ProTable.vue';
 
-// 仅保留组件 Props 与实例类型，不将裸组件 ProTable 作为具名导出直接扔出去
+/** ProTable 的组件属性类型 */
 export type ProTableProps = ComponentProps<typeof ProTable>;
+/** ProTable 的组件实例类型，用于 `ref` 标注与 `defineExpose` 访问 */
 export type ProTableInstance = ComponentExposed<typeof ProTable>;
 
 // 仅导出核心列配置类型
-export { type Column, type Columns } from './types';
+export { type Column, type ColumnControlConfig, type Columns } from './types';
 
 // 仅导出核心表格 Hook 与类型
 export { useTable, type Table } from './hooks';
+export { type PageParam } from '../../shared/core';
 
 export default ProTable;

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

@@ -1,8 +1,11 @@
 import type { ColumnType } from '../../../shared/ui';
-import { Data, KeyExpandString, Paths, Path } from '../../../shared/core';
+import type { Data, KeyExpandString, Paths, Path } from '../../../shared/core';
+import type { ComputedRef, MaybeRef } from 'vue';
+
+type MaybeRefOrComputedRef<T = any> = MaybeRef<T> | ComputedRef<T>;
 
 /**
- * @qin-ui/antd-vue-pro 表格列配置类型
+ * 表格列配置类型
  *
  * @description 继承 Ant Design Vue 的 ColumnType 列类型，并添加：
  * - 类型安全的 dataIndex（基于泛型 D 推导路径），优先使用
@@ -37,7 +40,7 @@ export type Column<D extends Data = Data> = Omit<
   'dataIndex' | 'key'
 > & {
   /**
-   * @description 列数据路径（主要字段）
+   * 列数据路径（主要字段）
    * 关联数据源中对应字段的路径，支持点号分隔的深层路径和数组路径。
    * 优先使用 dataIndex 进行字段匹配。
    *
@@ -45,20 +48,25 @@ export type Column<D extends Data = Data> = Omit<
    */
   dataIndex?: KeyExpandString<Extract<keyof D, string>> | Paths<D>;
   /**
-   * @description 列字段标识（辅助字段）
+   * 列字段标识（辅助字段）
    * 仅当 dataIndex 无法满足需求时使用，例如需要在自定义渲染中标识列时。
    * 在字段匹配时的优先级低于 dataIndex。
    */
   key?: Path<D>;
   /**
-   * @description 是否隐藏该列
+   * 列是否隐藏；支持布尔、Ref 与 ComputedRef 形式，渲染期按 `toValue` 取值。
+   * 分组列的子列同样参与过滤（递归生效）。
    * @default false
    */
-  hidden?: boolean;
+  hidden?: MaybeRefOrComputedRef<boolean>;
+  /**
+   * 分组子列；提供时该列作为分组表头渲染，子列沿用同一配置类型
+   */
+  children?: Column<D>[];
 };
 
 /**
- * @qin-ui/antd-vue-pro 表格列配置数组类型
+ * 表格列配置数组类型
  *
  * @template D - 表格行数据类型
  * @public

package/src/index.ts

@@ -26,7 +26,9 @@ export * from './locale';
  *   <ProForm :form="form" />
  * </template>
  * ```
- *
+ */
+export { ProForm };
+/**
  * Schema 驱动的表格组件，基于 antd-vue Table 封装
  *
  * @description 通过声明式列配置即可生成功能完整的表格，
@@ -42,7 +44,9 @@ export * from './locale';
  *   <ProTable :table="table" />
  * </template>
  * ```
- *
+ */
+export { ProTable };
+/**
  * 组件提供者，用于全局配置 ProForm 和 ProTable 的默认行为
  *
  * @description 通过 `ProComponentProvider` 包裹应用根组件，
@@ -57,10 +61,10 @@ export * from './locale';
  * </template>
  * ```
  */
-export { ProForm, ProTable, ProComponentProvider };
+export { ProComponentProvider };
 export default {
   /**
-   * @qin-ui/antd-vue-pro 安装方法
+   * 安装方法
    * @description 全局注册所有组件（ProForm、ProTable、ProComponentProvider）
    *
    * @param {App} app - Vue 应用实例
@@ -76,6 +80,9 @@ export default {
   install(app: App) {
     app.component(ProForm.name, ProForm);
     app.component(ProTable.name, ProTable);
-    app.component(ProComponentProvider.name!, ProComponentProvider);
+    app.component(
+      ProComponentProvider.name ?? 'ProComponentProvider',
+      ProComponentProvider
+    );
   },
 };

package/src/locale/index.ts

@@ -23,8 +23,10 @@ import {
 } from '../shared/core';
 import { useConfigContextInject } from '../shared/ui';
 
+/** 内置语言包：简体中文 / 繁体中文 / 英文 */
 export { zhCN, zhTW, enUS };
 
+/** 文案表类型：键为内置文案 key，值为任意字符串 */
 export type { ProLocale };
 
 /** ProComponentProvider 通过该 key 注入局部覆盖文案 */

package/src/shared/core/index.ts

@@ -2,19 +2,28 @@
  * 统一 re-export @qin-ui/pro-components-core，包内所有文件通过此文件引入 core 内容。
  */
 export {
+  // types
+  type AdditionalMethods,
+  localePacks,
+  normalizeColumn,
+  normalizeColumns,
   // hooks
   useForm,
   createFormProxy,
   useTable,
   useSearchFormExpand,
   useFields,
+  resolveFieldIdentity,
+  DEFAULT_FIELD_IDENTITY_KEYS,
   useFormData,
   useFormRef,
+  useReactiveAttrs,
   // injection keys
   InjectionFormKey,
   InjectionFormSlotsKey,
   // utils
   getObject,
+  omitBy,
   get,
   set,
   normalizePathKey,
@@ -22,7 +31,9 @@ export {
   camelizeProperties,
   cloneDeep,
   pick,
+  omit,
   isPlainObject,
+  isObjectItem,
   isPromise,
   // locale
   zhCN,

package/src/shared/ui/index.ts

@@ -1,4 +1,9 @@
-import type { FormProps as _FormProps } from 'ant-design-vue';
+import type {
+  FormProps as _FormProps,
+  Table,
+  TableProps as _TableProps,
+} from 'ant-design-vue';
+import type { ComponentProps } from 'vue-component-type-helpers';
 import type { Options } from 'scroll-into-view-if-needed';
 
 export {
@@ -36,7 +41,6 @@ export {
   type RowProps as GridProps,
   type ColProps as GridItemProps,
   type FormItemProps,
-  type TableProps,
   type PaginationProps,
 } from 'ant-design-vue';
 
@@ -48,13 +52,27 @@ export {
   useProviderDisabled,
 } from 'ant-design-vue/es/config-provider/DisabledContext';
 export { colProps as gridItemProps } from 'ant-design-vue/es/grid/Col';
+export { formItemProps } from 'ant-design-vue/es/form';
 export {
-  formItemProps,
   useInjectFormItemContext,
-} from 'ant-design-vue/es/form';
+  useProvideFormItemContext,
+} from 'ant-design-vue/es/form/FormItemContext';
 export { type NamePath } from 'ant-design-vue/es/form/interface';
 export { type MenuItemType } from 'ant-design-vue/es/menu/src/interface';
 
+/** 宿主 Form 属性面；`scrollToFirstError` 放宽为布尔或滚动配置对象 */
 export type FormProps = Omit<_FormProps, 'scrollToFirstError'> & {
   scrollToFirstError?: boolean | Options<any>;
 };
+
+/**
+ * 表格完整属性面
+ *
+ * @description 由宿主 `TableProps` 与其未声明的 emit 型属性键组成；
+ * ant-design-vue 的 Table 未暴露 `scroll` 事件面，故不提供 `@scroll` 入口。
+ */
+export interface TableProps extends _TableProps {
+  'onUpdate:expandedRowKeys'?: ComponentProps<
+    typeof Table
+  >['onUpdate:expandedRowKeys'];
+}

package/tsconfig.json

@@ -11,7 +11,6 @@
     "esModuleInterop": true,
     "lib": ["ESNext", "ES2022", "DOM"],
     "baseUrl": ".",
-    "types": ["ant-design-vue/typings/global"],
     "declaration": true,
     "declarationMap": true,
     "skipLibCheck": true,