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

package/src/components/table/components/TableColumnRenderer.vue

@@ -1,31 +1,30 @@
-<script
-  lang="ts"
-  setup
-  generic="D extends Record<string, any> = Record<string, any>"
->
-import { get, normalizePathKey } from '../../../shared/core';
+<script lang="ts">
+/**
+ * 列配置渲染器
+ *
+ * @component TableColumnRenderer
+ * @description 把列数组渲染为 el-table-column 树，支持分组列（children）、自定义 render 列与深层路径取值
+ *
+ * @param {Columns} [columns] - 列配置数组
+ *
+ * @internal
+ */
+import { defineComponent, h, toRaw, toValue, type PropType } from 'vue';
+import { get, isObjectItem, normalizePathKey } from '../../../shared/core';
 import { TableColumn } from '../../../shared/ui';
 import SlotComponent from '../../form/components/SlotComponent/index.vue';
 import type { Column, Columns } from '../types';
-import { computed, toRaw } from 'vue';
-
-defineOptions({ name: 'TableColumnRenderer' });
-
-type Props = {
-  columns: Columns<D>;
-};
-const props = withDefaults(defineProps<Props>(), {
-  columns: () => [],
-});
 
 /*
- * 无 key/prop 列的稳定渲染 key：以列原始对象为 key 分配自增 id，
- * 列插删/重排/过滤时保持 key 与对象绑定，不随数组位置漂移
+ * 无 key/prop 列的渲染 key 与列对象身份绑定：
+ * 列增删、重排与过滤后 key 不随数组位置漂移
  */
 let columnKeySeed = 0;
 const columnKeyMap = new WeakMap<object, number>();
-const getStableColumnKey = (column: unknown): number => {
-  const raw = toRaw(column as object);
+const getStableColumnKey = (column: unknown): string | number => {
+  if (column === null || typeof column !== 'object')
+    return `raw_${String(column)}`;
+  const raw = toRaw(column);
   let key = columnKeyMap.get(raw);
   if (key === undefined) {
     key = ++columnKeySeed;
@@ -34,24 +33,20 @@ const getStableColumnKey = (column: unknown): number => {
   return key;
 };
 
-const getColumnKey = (column: Column<D>) => {
-  const rawKey = column.key ?? column.prop;
-  if (rawKey === undefined || rawKey === null)
-    return getStableColumnKey(column);
+const getColumnKey = (column: Column) => {
+  // 空字符串 key 视为未提供，与 getColumnProps 的 columnKey 取值一致
+  const rawKey = column.key || column.prop;
+  if (!rawKey) return getStableColumnKey(column);
   return normalizePathKey(rawKey);
 };
 
-const getCellValue = (row: Record<string, any>, column: Column<D>) => {
+const getCellValue = (row: Record<string, any>, column: Column) => {
   const path = column.prop;
   if (!path) return undefined;
   return get(row, path);
 };
 
-const normalizedColumns = computed(() => {
-  return props.columns.filter(column => !column.hidden);
-});
-
-const getColumnProps = (column: Column<D>) => {
+const getColumnProps = (column: Column) => {
   const { hidden, render, key, children, ...rest } = column;
   const prop = column.prop ? normalizePathKey(column.prop) : undefined;
   const columnKey = key ? normalizePathKey(key) : prop;
@@ -62,38 +57,62 @@ const getColumnProps = (column: Column<D>) => {
     columnKey,
   };
 };
-</script>
 
-<template>
-  <template v-for="column in normalizedColumns" :key="getColumnKey(column)">
-    <!-- 分组列（递归子列） -->
-    <TableColumn
-      v-if="column.children && column.children.length > 0"
-      v-bind="getColumnProps(column)"
-    >
-      <TableColumnRenderer :columns="column.children" />
-    </TableColumn>
-
-    <!-- 自定义 render 列 -->
-    <TableColumn
-      v-else-if="typeof column.render === 'function'"
-      v-bind="getColumnProps(column)"
-    >
-      <template #default="scope">
-        <!-- 经 SlotComponent 渲染：支持组件、VNode 与文本等多种形态 -->
-        <SlotComponent
-          :component="
-            column.render?.({
-              ...scope,
-              column,
-              cellValue: getCellValue(scope.row, column),
-            })
-          "
-        />
-      </template>
-    </TableColumn>
+/*
+ * 递归渲染列树：子列以同层 vnode 数组展开，深层分组同样成立；
+ * 每层以不可变祖先路径向下传递，重复出现的祖先引用直接剔除（含 a→b→a 互引用）
+ */
+const renderColumn = (
+  column: Column,
+  ancestors: Set<object> = new Set()
+): any => {
+  const hasChildren =
+    Array.isArray(column.children) && column.children.length > 0;
+  const vnodeProps = { key: getColumnKey(column), ...getColumnProps(column) };
+  if (hasChildren) {
+    // 每层祖先路径随 vnode 创建确定，环状引用按路径截断
+    const nextAncestors = new Set(ancestors).add(column);
+    return h(TableColumn, vnodeProps, {
+      default: () =>
+        column
+          .children!.filter(
+            child =>
+              isObjectItem(child) &&
+              !nextAncestors.has(child) &&
+              !toValue(child.hidden)
+          )
+          .map(child => renderColumn(child, nextAncestors)),
+    });
+  }
+  if (typeof column.render === 'function') {
+    return h(TableColumn, vnodeProps, {
+      default: (scope: any) =>
+        h(SlotComponent, {
+          component: column.render!({
+            ...scope,
+            column,
+            cellValue: getCellValue(scope.row, column),
+          }),
+        }),
+    });
+  }
+  return h(TableColumn, vnodeProps);
+};
 
-    <!-- 普通列（Element Plus 原生渲染） -->
-    <TableColumn v-else v-bind="getColumnProps(column)" />
-  </template>
-</template>
+export default defineComponent({
+  name: 'TableColumnRenderer',
+  inheritAttrs: false,
+  props: {
+    columns: {
+      type: Array as PropType<Columns>,
+      default: () => [],
+    },
+  },
+  setup(props) {
+    return () =>
+      props.columns
+        .filter(column => isObjectItem(column) && !toValue(column.hidden))
+        .map(column => renderColumn(column));
+  },
+});
+</script>

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

@@ -0,0 +1 @@
+export * from './useTable';

package/src/components/table/{useTable.ts → hooks/useTable.ts}

@@ -1,15 +1,16 @@
 import {
   useTable as coreUseTable,
   type Table as _Table,
-} from '../../shared/core';
+} from '../../../shared/core';
 import type {
   Data,
   ExtendWithAny,
   DeepPartial,
   PageParam,
-} from '../../shared/core';
-import { Fields } from '../form/types';
-import type { Column, Columns } from './types';
+} from '../../../shared/core';
+import type { Fields } from '../../form/types';
+import { ELEMENT_FIELD_IDENTITY_KEYS } from '../../form/constants';
+import type { Column, Columns } from '../types';
 import type { Ref } from 'vue';
 
 /**
@@ -133,6 +134,7 @@ export function useTable<
     ...rest,
     dataSource: data,
     columns: columns as any,
+    fieldIdentityKeys: ELEMENT_FIELD_IDENTITY_KEYS,
   });
 
   const { dataSource, ...tableWithoutDataSource } = coreTable as Omit<

package/src/components/table/index.ts

@@ -5,14 +5,23 @@ import type {
 import ProTable from './components/ProTable.vue';
 
 // 仅导出组件 Props 与实例类型，不导出裸组件
+/** ProTable 组件属性（由组件 Props 推导） */
 export type ProTableProps = ComponentProps<typeof ProTable>;
+/** ProTable 组件实例（`defineExpose` 暴露的能力） */
 export type ProTableInstance = ComponentExposed<typeof ProTable>;
 
 // 仅导出核心列配置类型
-export { type Column, type Columns } from './types';
+export {
+  type Column,
+  type ColumnControlConfig,
+  type ColumnScope,
+  type Columns,
+} from './types';
+/** Element Plus 宿主表格事件类型（仅 element 适配层提供） */
 export { type TableEmits } from '../../shared/ui';
 
 // 仅导出核心表格 Hook 与类型
-export { useTable, type Table } from './useTable';
+export { useTable, type Table } from './hooks';
+export { type PageParam } from '../../shared/core';
 
 export default ProTable;

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

@@ -1,5 +1,7 @@
 import type { ColumnType } from '../../../shared/ui';
-import { Data, ExtendWithAny, Path } from '../../../shared/core';
+import type { Data, ExtendWithAny, Path } from '../../../shared/core';
+import type { ComputedRef, MaybeRef } from 'vue';
+type MaybeRefOrComputedRef<T = any> = MaybeRef<T> | ComputedRef<T>;
 
 type BivariantRender<D extends Data = Data> = {
   bivarianceHack(scope: ColumnScope<D>): any;
@@ -8,7 +10,7 @@ type BivariantRender<D extends Data = Data> = {
 /**
  * Element Plus 表格列作用域
  * @template D - 表格行数据类型
- 
+ *
  * @public
  */
 export type ColumnScope<D extends Data = Data> = {
@@ -23,16 +25,14 @@ export type ColumnScope<D extends Data = Data> = {
 };
 
 /**
- * @qin-ui/element-plus-pro 表格列配置类型
+ * 表格列配置类型，基于宿主 ColumnType 扩展
  *
- * @description 基于 Element Plus 的 ColumnType 列类型，并添加：
+ * @description 在宿主列类型之上新增：
  * - prop 作为主要字段（Element Plus 使用 prop 而非 dataIndex）
  * - key 作为辅助标识
  * - hidden 属性
  * - render 自定义渲染函数
- *
  * @template D - 表格行数据类型
- *
  * @example
  * ```ts
  * interface User { name: string; age: number }
@@ -42,7 +42,7 @@ export type ColumnScope<D extends Data = Data> = {
  *   { prop: 'age', label: '年龄', width: 80 },
  * ]
  * ```
- 
+ *
  * @public
  */
 export type Column<D extends Data = Data> = Partial<
@@ -51,13 +51,16 @@ export type Column<D extends Data = Data> = Partial<
   /** 列字段标识（辅助字段） */
   key?: Path<D>;
   /**
-   * @description 列数据路径（主要字段）
-   * Element Plus 使用 prop 而非 dataIndex
+   * 列数据路径（主要字段），Element Plus 使用 prop 而非 dataIndex
    * @example 'name' | 'address.city'
    */
   prop?: Path<D>;
-  /** 是否隐藏该列 */
-  hidden?: boolean;
+  /**
+   * 列是否隐藏；支持布尔、Ref 与 ComputedRef 形式，渲染期按 `toValue` 取值
+   *
+   * 分组列的子列同样参与过滤（递归生效）。
+   */
+  hidden?: MaybeRefOrComputedRef<boolean>;
   /** 自定义渲染函数 */
   render?: BivariantRender<D>;
   /** 嵌套子列（用于表头分组） */
@@ -65,9 +68,10 @@ export type Column<D extends Data = Data> = Partial<
 };
 
 /**
- * @qin-ui/element-plus-pro 表格列配置数组类型
+ * 表格列配置数组类型
+ *
  * @template D - 表格行数据类型
- 
+ *
  * @public
  */
 export type Columns<D extends Data = Data> = Array<Column<D>>;

package/src/index.ts

@@ -26,7 +26,9 @@ export * from './locale';
  *   <ProForm :form="form" />
  * </template>
  * ```
- *
+ */
+export { ProForm };
+/**
  * Schema 驱动的表格组件，基于 element-plus Table 封装
  *
  * @description 通过声明式列配置即可生成功能完整的表格，
@@ -42,7 +44,9 @@ export * from './locale';
  *   <ProTable :table="table" />
  * </template>
  * ```
- *
+ */
+export { ProTable };
+/**
  * 组件提供者，用于全局配置 ProForm 和 ProTable 的默认行为
  *
  * @description 通过 `ProComponentProvider` 包裹应用根组件，
@@ -57,15 +61,14 @@ export * from './locale';
  * </template>
  * ```
  */
-export { ProForm, ProTable, ProComponentProvider };
+export { ProComponentProvider };
 
 export default {
   /**
-   * @qin-ui/element-plus-pro 安装方法
-   * @description 全局注册所有组件（ProForm、ProTable、ProComponentProvider）
+   * 安装方法：全局注册 ProForm / ProTable / ProComponentProvider
    *
+   * @description 供 `app.use(ProComponents)` 调用
    * @param {App} app - Vue 应用实例
-   *
    * @example
    * ```ts
    * import { createApp } from 'vue'
@@ -77,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

@@ -20,7 +20,8 @@ import enUS from './en-US';
 
 export { zhCN, zhTW, enUS };
 
-export type ProLocale = typeof zhCN;
+/** 内置文案类型：键集合与 zh-CN 对齐，取值允许任意文案覆盖 */
+export type ProLocale = Record<keyof typeof zhCN, string>;
 
 /** ProComponentProvider 通过该 key 注入局部覆盖文案 */
 export const LOCALE_INJECT_KEY: InjectionKey<
@@ -50,7 +51,8 @@ export const useLocale = () => {
   const override = inject(LOCALE_INJECT_KEY, undefined);
 
   const lang = computed<ProLocaleName>(() => {
-    if (!elLocaleContext) return 'zh-CN';
+    // 注入上下文为 computed/ref 包装，按取值本体判定宿主是否提供语言
+    if (toValue(elLocaleContext) == null) return 'zh-CN';
     return resolveLocaleName(elLang.value);
   });
   const pack = computed<Record<string, string>>(() =>

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

@@ -27,6 +27,7 @@ import {
   ElTimeSelect as TimeSelect,
   ElPagination as Pagination,
   useFormDisabled,
+  useSize,
   type FormItemInstance,
   type FormInstance,
   type FormProps,
@@ -68,6 +69,7 @@ export {
   TimePicker,
   TimeSelect,
   Pagination,
+  useSize,
   type FormItemInstance,
   type FormInstance,
   type FormProps,
@@ -79,6 +81,7 @@ export {
   type TableEmits,
 };
 
+/** 宿主 Table 属性面（放宽泛型以兼容任意行数据） */
 export type TableProps = _TableProps<any>;
 
 const _tableProps = (Table as any).props || {};
@@ -86,34 +89,55 @@ const _paginationProps = (Pagination as any).props || {};
 const _gridItemProps = (GridItem as any).props || {};
 const _formItemProps = (FormItem as any).props || {};
 
+/** 宿主 Table 的静态 props 快照（透传键名白名单用） */
 export const tableProps = () => _tableProps;
+/** 宿主 Pagination 的静态 props 快照（分页配置键名白名单用） */
 export const paginationProps = () => _paginationProps;
+/** 宿主 Row/Col 的静态 props 快照 */
 export const gridItemProps = () => _gridItemProps;
+/** 宿主 FormItem 的静态 props 快照 */
 export const formItemProps = () => _formItemProps;
 
 const DisabledContextKey = Symbol.for('pro-form-disabled-context');
 
+/** 禁用上下文取值
+ *
+ * @description 字段级禁用优先，未声明时回退宿主 `el-form` 的禁用状态
+ * @returns {ComputedRef<boolean>} 当前生效的禁用状态
+ */
 export const useDisabledContext = () => {
   const formDisabled = useFormDisabled();
-  const customDisabled = inject<any>(DisabledContextKey, undefined);
+  const customDisabled = inject<MaybeRefOrGetter<boolean | undefined>>(
+    DisabledContextKey,
+    undefined
+  );
   return computed(() => {
-    if (customDisabled !== undefined && toValue(customDisabled) !== undefined) {
-      return Boolean(toValue(customDisabled));
-    }
+    const custom = toValue(customDisabled);
+    if (custom !== undefined) return Boolean(custom);
     return Boolean(formDisabled.value);
   });
 };
 
+/** 禁用上下文提供者
+ *
+ * @description 与父级禁用上下文合并：未声明时保持继承，声明时（含 false）覆盖
+ * @param {MaybeRefOrGetter<boolean | undefined>} disabled - 本层声明的禁用状态
+ */
 export const useDisabledContextProvider = (
   disabled: MaybeRefOrGetter<boolean | undefined>
 ) => {
+  // 与父级禁用上下文合并：未声明时保持继承，声明时（含 false）覆盖
+  const parentDisabled = useDisabledContext();
   provide(
     DisabledContextKey,
-    computed(() => !!toValue(disabled))
+    computed(() => toValue(disabled) ?? parentDisabled.value)
   );
 };
 
+/** {@link useDisabledContext} 的别名 */
 export const useInjectDisabled = useDisabledContext;
+/** {@link useDisabledContextProvider} 的别名 */
 export const useProviderDisabled = useDisabledContextProvider;
 
+/** 字段路径：字符串、数字或分段数组 */
 export type NamePath = string | number | (string | number)[];

package/tsconfig.json

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

package/es/components/table/useTable.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useTable.d.ts","sourceRoot":"","sources":["../../../src/components/table/useTable.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,KAAK,IAAI,MAAM,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,IAAI,EACJ,aAAa,EACb,WAAW,EACX,SAAS,EACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,MAAM,KAAK,CACf,CAAC,SAAS,IAAI,GAAG,IAAI,EACrB,CAAC,SAAS,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,IAC/B,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,GAAG;IAChD;;OAEG;IACH,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;CAChB,CAAC;AAEF,KAAK,cAAc,CACjB,CAAC,SAAS,IAAI,GAAG,IAAI,EACrB,CAAC,SAAS,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,IAC/B;IACF,YAAY;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACrB,gDAAgD;IAChD,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;IACX,aAAa;IACb,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa;IACb,WAAW,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5C,eAAe;IACf,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,QAAQ,CACtB,CAAC,SAAS,IAAI,GAAG,IAAI,EACrB,CAAC,SAAS,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,EACjC,MAAM,GAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAM,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAoBhD"}