@qin-ui/element-plus-pro 1.2.3 → 1.3.0

package/src/components/form/hooks/useGroupFieldAttrs.ts

@@ -0,0 +1,123 @@
+import { computed, inject, mergeProps, toValue, type ComputedRef } from 'vue';
+import {
+  formItemProps,
+  gridItemProps,
+  type FormItemProps,
+  type GridItemProps,
+} from '../../../shared/ui';
+import { isPlainObject } from '../../../shared/core';
+import { INJECT_CONFIG } from '../../component-provider/constants';
+import { FORM_ITEM_SLOT_KEYS } from '../constants';
+import type { Base, Field } from '../types';
+
+const formItemPropKeys = Object.keys(formItemProps()).filter(
+  k => k !== 'disabled'
+);
+const gridItemPropKeys = Object.keys(gridItemProps());
+
+export interface GroupedField {
+  path: string;
+  gridItemProps: GridItemProps;
+  formItemProps: FormItemProps;
+  formItemSlots: Record<(typeof FORM_ITEM_SLOT_KEYS)[number], any>;
+  componentProps: Record<string, any>;
+  container?: Base['formItemContainer'];
+  rawField: Field;
+}
+
+/**
+ * 将 fields 配置数组逐个拆分为 grid / formItem / component / slots 分组。
+ */
+export function useGroupFieldAttrs(validFields: ComputedRef<Field[]>) {
+  const config = INJECT_CONFIG['pro-form-item'];
+  const injectFormItemProps = inject(config.injectionKey, config.default);
+
+  return computed<GroupedField[]>(() => {
+    const rawInjectProps = toValue(injectFormItemProps) || {};
+    return validFields.value.map(field => {
+      let gridItemProps: Record<string, any> = {};
+      let formItemProps: Record<string, any> = {};
+      const componentProps: Record<string, any> = { slots: {} };
+      const formItemSlots: Record<string, any> = {};
+
+      if (isPlainObject(field)) {
+        // prettier-ignore
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { path, name, fields, formItemClass, formItemStyle, formItemContainer, hidden, span, getFormItemRef, getComponentRef, getFormItemComputedProps, getComponentComputedProps, slots = {}, formItemDataAttrs = {}, componentDataAttrs = {}, extraProps, ...rest } =
+          field as any;
+
+        const {
+          class: injectClassName,
+          style: injectStyle,
+          span: injectSpan,
+          formItemContainer: injectFormItemContainer,
+          xs,
+          sm,
+          md,
+          lg,
+          xl,
+          ...injectRest
+        } = rawInjectProps;
+
+        // 字段显式 span 优先，否则回退注入配置的响应式断点
+        const initGridItemProps =
+          span || span === 0
+            ? { span }
+            : { xs, sm, md, lg, xl, span: injectSpan };
+
+        gridItemProps = fields ? { span: span ?? 24 } : initGridItemProps;
+        formItemProps = mergeProps(
+          injectRest as any,
+          { class: injectClassName, style: injectStyle },
+          { class: toValue(formItemClass), style: toValue(formItemStyle) },
+          formItemDataAttrs
+        );
+        const container = formItemContainer ?? injectFormItemContainer;
+
+        Object.keys(rest).forEach(k => {
+          if (gridItemPropKeys.includes(k)) {
+            gridItemProps[k] = rest[k];
+          } else if (formItemPropKeys.includes(k)) {
+            (formItemProps as any)[k] = rest[k];
+          } else {
+            componentProps[k] = rest[k];
+          }
+        });
+
+        Object.assign(componentProps, componentDataAttrs);
+        Object.keys(slots).forEach(k => {
+          if (FORM_ITEM_SLOT_KEYS.includes(k as any)) {
+            formItemSlots[k] = slots[k];
+          } else {
+            componentProps.slots[k] = slots[k];
+          }
+        });
+
+        const raw = (toValue(name) ?? toValue(path)) as
+          | string
+          | number[]
+          | undefined;
+        return {
+          path: Array.isArray(raw) ? raw.join('.') : (raw as string) || '',
+          gridItemProps: gridItemProps as GridItemProps,
+          formItemProps: formItemProps as any,
+          formItemSlots,
+          componentProps,
+          container,
+          rawField: field,
+        };
+      }
+
+      const raw =
+        toValue((field as any)?.name) ?? toValue((field as any)?.path);
+      return {
+        path: Array.isArray(raw) ? raw.join('.') : (raw as string) || '',
+        gridItemProps: gridItemProps as GridItemProps,
+        formItemProps: formItemProps as any,
+        formItemSlots,
+        componentProps,
+        rawField: field,
+      };
+    });
+  });
+}

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

@@ -30,9 +30,33 @@ export type VModelProps<T = any> = {
   'onUpdate:modelValue'?: (val: T) => void;
 };
 
+/**
+ * 字段值格式化/转换处理器
+ *
+ * @description 支持函数形态或包含 get/set 方法的对象形态。
+ *
+ * ### 行为与契约说明
+ * 1. **旧值参数按需注入**：底层基于函数的形参声明个数（`fn.length > 1`）决定是否读取旧值。若转换逻辑需要使用旧值，请显式声明两个形参 `(val, oldVal) => ...`（请勿使用默认参数或 `...args` 剩余参数，否则 `fn.length` 无法正确识别）；
+ * 2. **只读快照副本**：传入的 `oldVal` 为只读快照副本，不得依赖原地修改写回；仅当 formatter 声明双形参时才克隆旧值，单参转换零开销。
+ *
+ * @example
+ * ```ts
+ * // 1. 单参数转换（常见）：无需旧值，零多余开销
+ * valueFormatter: (val) => val?.trim()
+ *
+ * // 2. 双参数转换：需要基于旧值做对比或回退
+ * valueFormatter: (val, oldVal) => (isValid(val) ? val : oldVal)
+ *
+ * // 3. 对象形态：分别定义读（展示）与写（存储）转换
+ * valueFormatter: {
+ *   get: (val) => (val ? dayjs(val).format('YYYY-MM-DD') : ''),
+ *   set: (val, oldVal) => (val ? dayjs(val).valueOf() : undefined),
+ * }
+ * ```
+ */
 export type ValueFormatter =
-  | { (val: any, oldVal: any): any }
-  | { get?: (val: any) => any; set?: (val: any, oldVal: any) => any };
+  | { (val: any, oldVal?: any): any }
+  | { get?: (val: any) => any; set?: (val: any, oldVal?: any) => any };
 
 /**
  * @description 自定义组件

package/src/components/table/components/ColumnControl.vue

@@ -11,28 +11,27 @@ import type { Column, Columns, ColumnControlConfig } from '../types';
 import { type Table } from '../useTable';
 import FilterOutlined from './icons/FilterOutlined.vue';
 import { useLocale } from '../../../locale';
+import { normalizePathKey } from '../../../shared/core';
 
 type Props = {
   columns: Columns;
   table?: Table;
   columnControl?: ColumnControlConfig;
 };
-const {
-  columns,
-  table = undefined,
-  columnControl = undefined,
-} = defineProps<Props>();
+const props = withDefaults(defineProps<Props>(), {
+  table: undefined,
+  columnControl: undefined,
+});
 
 const { t } = useLocale();
 
-const open = ref(false);
 const checkAll = ref(false);
 const indeterminate = ref(false);
 
 const getColumnKey = (column: Column, index: number) => {
-  const key = column.key ?? column.prop;
-  if (key === undefined || key === null) return `__col_${index}`;
-  return Array.isArray(key) ? key.join('.') : String(key);
+  const rawKey = column.key ?? column.prop;
+  if (rawKey === undefined || rawKey === null) return `__col_${index}`;
+  return normalizePathKey(rawKey);
 };
 
 const checkedColumnsOptions = computed<
@@ -44,13 +43,13 @@ const checkedColumnsOptions = computed<
     column: Column;
   }>
 >(() =>
-  columns
+  props.columns
     .map((item, index) => {
       const key = getColumnKey(item, index);
-      const excluded = columnControl?.excludedKeys?.some(
+      const excluded = props.columnControl?.excludedKeys?.some(
         ek => String(ek) === key
       );
-      const disabled = columnControl?.disabledKeys?.some(
+      const disabled = props.columnControl?.disabledKeys?.some(
         dk => String(dk) === key
       );
       const label = String(
@@ -85,7 +84,7 @@ const checkedColumnKeys = computed({
   set(val: string[]) {
     checkedColumnsOptions.value.forEach(item => {
       if (item.disabled) return;
-      table?.setColumn(item.value as any, {
+      props.table?.setColumn(item.value as any, {
         hidden: !val.includes(item.value),
       });
     });
@@ -130,16 +129,16 @@ watch(
 
 // 强制 disabledKeys 列始终展示
 onMounted(() => {
-  columnControl?.disabledKeys?.forEach(key => {
-    table?.setColumn(String(key), { hidden: false });
+  props.columnControl?.disabledKeys?.forEach(key => {
+    props.table?.setColumn(String(key), { hidden: false });
   });
 });
 
 watch(
-  () => columnControl?.disabledKeys,
+  () => props.columnControl?.disabledKeys,
   keys => {
     keys?.forEach(key => {
-      table?.setColumn(String(key), { hidden: false });
+      props.table?.setColumn(String(key), { hidden: false });
     });
   },
   { deep: true }
@@ -147,19 +146,14 @@ watch(
 </script>
 
 <template>
-  <Dropdown
-    trigger="click"
-    :hide-on-click="false"
-    :visible="open"
-    @visible-change="val => (open = val)"
-  >
+  <Dropdown trigger="click" :hide-on-click="false">
     <Button text class="pro-table_column-control_button">
       <FilterOutlined />
     </Button>
     <template #dropdown>
       <DropdownMenu>
         <DropdownItem
-          v-if="!columnControl?.disableCheckAll"
+          v-if="!props.columnControl?.disableCheckAll"
           :disabled="true"
           :divided="false"
         >

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

@@ -40,12 +40,14 @@ import {
   tableProps,
   paginationProps,
 } from '../../../shared/ui';
+import { ElLoading } from 'element-plus';
 import {
   computed,
   nextTick,
   useAttrs,
   onMounted,
   inject,
+  toValue,
   type Slot,
   useSlots,
 } from 'vue';
@@ -60,6 +62,8 @@ import {
   camelizeProperties,
   getObject,
   pick,
+  isPromise,
+  isPlainObject,
   Path,
 } from '../../../shared/core';
 import {
@@ -71,7 +75,13 @@ import {
 import type { Columns, ColumnControlConfig } from '../types';
 import TableColumnRenderer from './TableColumnRenderer.vue';
 
-defineOptions({ name: 'ProTable', inheritAttrs: false });
+defineOptions({
+  name: 'ProTable',
+  directives: {
+    loading: ElLoading.directive,
+  },
+  inheritAttrs: false,
+});
 
 type Control = {
   sizeControl: boolean;
@@ -108,23 +118,24 @@ type Props = {
   pagination?: false | Partial<PaginationProps>;
 } & Omit<TableProps, 'data'>;
 
-const {
-  table = undefined,
-  search = undefined,
-  addIndexColumn = undefined,
-  control = undefined,
-  tableContainer = undefined,
-  immediateSearch = undefined,
-  searchFormConfig = undefined,
-  columns = undefined,
-  data = undefined,
-  pagination = undefined,
-} = defineProps<Props>();
+const props = withDefaults(defineProps<Props>(), {
+  table: undefined,
+  search: undefined,
+  addIndexColumn: undefined,
+  immediateSearch: undefined,
+  control: undefined,
+  searchFormConfig: undefined,
+  tableContainer: undefined,
+  columns: undefined,
+  data: undefined,
+  pagination: undefined,
+});
 
 const { t } = useLocale();
 
 const config = INJECT_CONFIG['pro-table'];
-const injectProps = inject(config.injectionKey, config.default) as any;
+const injectPropsRaw = inject(config.injectionKey, config.default);
+const injectProps = computed(() => toValue(injectPropsRaw) || {});
 
 const tableProperties = Object.keys(tableProps());
 const paginationProperties = Object.keys(paginationProps());
@@ -132,7 +143,7 @@ const paginationProperties = Object.keys(paginationProps());
 const attrs = useAttrs() as Record<string, any>;
 
 const injectTableAttrs = computed(() => {
-  return pick(injectProps, tableProperties) as Partial<TableProps>;
+  return pick(injectProps.value, tableProperties) as Partial<TableProps>;
 });
 
 const attrsTableProps = computed(() => {
@@ -142,30 +153,25 @@ const attrsTableProps = computed(() => {
   ) as Partial<TableProps>;
 });
 
-const {
-  columns: tableColumns,
-  data: tableData,
-  searchForm,
-  pageParam,
-  setPageParam,
-} = table || {};
-
 const size = defineModel<TableProps['size']>('size');
-const loading = defineModel<boolean>('loading');
+const loading = defineModel<boolean>('loading', { default: false });
 
 // 核心搜索方法：设置 loading 状态，调用外部 search 函数
 const _search = async () => {
-  try {
+  const searchPromise = (props.search || attrs.onSearch)?.();
+  if (isPromise(searchPromise)) {
     loading.value = true;
-    await search?.();
-  } finally {
-    loading.value = false;
+    try {
+      await searchPromise;
+    } finally {
+      loading.value = false;
+    }
   }
 };
 
 // 重置：恢复查询参数到初始值，重新搜索
 const reset = () => {
-  table?.resetQueryParams();
+  props.table?.resetQueryParams?.();
   nextTick(() => {
     _search();
   });
@@ -196,37 +202,51 @@ const tableSlots = computed(() => {
 const tableSlotNames = computed(() => Object.keys(tableSlots.value));
 
 const searchPage1st = () => {
-  setPageParam?.({ current: 1 });
+  props.table?.setPageParam?.({ current: 1 });
   _search();
 };
 
 const computedSearchFormConfig = computed(() => {
   const container =
-    searchFormConfig?.container ??
-    injectProps.searchFormConfig?.container ??
+    props.searchFormConfig?.container ??
+    (injectProps.value.searchFormConfig as any)?.container ??
     DefaultSearchFormContainer;
   return {
-    ...injectProps.searchFormConfig,
-    ...getObject(searchFormConfig),
+    ...injectProps.value.searchFormConfig,
+    ...getObject(props.searchFormConfig),
     container: container ? container : undefined,
   };
 });
 
 const computedTableContainer = computed(() => {
   const container =
-    tableContainer ?? injectProps.tableContainer ?? DefaultTableContainer;
+    props.tableContainer ??
+    injectProps.value.tableContainer ??
+    DefaultTableContainer;
   return container ? container : undefined;
 });
 
+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 normalizedRawColumns = computed(() => {
-  const source = (columns ?? tableColumns?.value ?? []) as any[];
-  if (addIndexColumn ?? injectProps.addIndexColumn) {
+  const source = (props.columns ??
+    toValue(props.table?.columns) ??
+    []) as any[];
+  if (props.addIndexColumn ?? injectProps.value.addIndexColumn) {
     return [
       {
         key: '_index',
         type: 'index',
         label: t('table.index'),
         width: 80,
+        index: getIndex,
       },
       ...source,
     ];
@@ -236,7 +256,13 @@ const normalizedRawColumns = computed(() => {
 
 const computedDataSource = computed<any[]>(() => {
   const attrsData = attrsTableProps.value.data as any[] | undefined;
-  return data ?? attrsData ?? tableData?.value ?? [];
+  return (
+    props.data ??
+    attrsData ??
+    toValue((props.table as any)?.dataSource) ??
+    toValue(props.table?.data) ??
+    []
+  );
 });
 
 const computedTableProps = computed<TableProps>(() => {
@@ -248,40 +274,69 @@ const computedTableProps = computed<TableProps>(() => {
   return merged;
 });
 
+// 分页优先级：tableAttrs 显式配置 > provider 全局配置 > 默认合成
 const computedPagination = computed<false | Partial<PaginationProps>>(() => {
-  if (pagination === false) return false;
-  const pageConfig = pagination ?? {};
+  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>;
+    const globalPagination =
+      (injectProps.value.pagination as any) === false
+        ? {}
+        : (injectProps.value.pagination as Partial<PaginationProps>) || {};
+    const pageParam = props.table?.pageParam;
+    return {
+      ...globalPagination,
+      ...pick(pageConfig as Record<string, any>, paginationProperties),
+      currentPage: pageParam?.current ?? (pageConfig as any).currentPage ?? 1,
+      pageSize: pageParam?.pageSize ?? (pageConfig as any).pageSize ?? 10,
+      total: pageParam?.total ?? (pageConfig as any).total ?? 0,
+    };
+  }
+
+  if ((injectProps.value.pagination as any) === false) return false;
+
+  const pageParam = props.table?.pageParam;
   return {
-    ...injectProps.pagination,
-    ...pick(pageConfig as Record<string, any>, paginationProperties),
-    currentPage: (pageConfig as any).currentPage ?? pageParam?.current ?? 1,
-    pageSize: (pageConfig as any).pageSize ?? pageParam?.pageSize ?? 10,
-    total: (pageConfig as any).total ?? pageParam?.total ?? 0,
+    ...(injectProps.value.pagination as Partial<PaginationProps>),
+    currentPage: pageParam?.current ?? 1,
+    pageSize: pageParam?.pageSize ?? 10,
+    total: pageParam?.total ?? 0,
   };
 });
 
 const showPagination = computed(() => computedPagination.value !== false);
 
 const onCurrentChange = (current: number) => {
-  setPageParam?.({ current });
+  props.table?.setPageParam?.({ current });
   _search();
 };
 
 const onSizeChange = (pageSize: number) => {
-  setPageParam?.({ pageSize, current: 1 });
+  props.table?.setPageParam?.({ pageSize, current: 1 });
   _search();
 };
 
 const onPaginationChange = (currentPage: number, pageSize: number) => {
+  // 透传 el-pagination change 回调
   attrs.onChange?.(currentPage, pageSize);
 };
 
 const showSearch = computed(() => {
+  const searchFields = props.table?.searchForm?.fields;
+  const fieldList =
+    (Array.isArray(searchFields) ? searchFields : searchFields?.value) ?? [];
   return !!(
     searchFormSlot ||
-    (computedSearchFormConfig.value?.hidden !== true &&
-      searchForm &&
-      searchForm.fields.value.filter(item => !item.hidden)?.length > 0)
+    ((computedSearchFormConfig.value as any)?.hidden !== true &&
+      props.table?.searchForm &&
+      fieldList.filter((item: any) => !item.hidden)?.length > 0)
   );
 });
 
@@ -289,13 +344,13 @@ const computedControl = computed<{
   sizeControl: boolean;
   columnControl: boolean | ColumnControlConfig<Path<RecordType>>;
 }>(() => {
-  const mergedControl = control ?? injectProps.control;
+  const mergedControl = props.control ?? injectProps.value.control;
   if (typeof mergedControl === 'boolean') {
     return { sizeControl: mergedControl, columnControl: mergedControl };
   }
   const c = mergedControl as Control;
-  const sizeControl = c.sizeControl ?? true;
-  const columnControl = c.columnControl ?? true;
+  const sizeControl = c?.sizeControl ?? false;
+  const columnControl = c?.columnControl ?? false;
   return { sizeControl: !!sizeControl, columnControl };
 });
 
@@ -313,7 +368,7 @@ const resolvedSize = computed(() => {
 });
 
 onMounted(() => {
-  if (immediateSearch ?? injectProps.immediateSearch) {
+  if (props.immediateSearch ?? injectProps.value.immediateSearch) {
     _search();
   }
 });
@@ -327,8 +382,8 @@ onMounted(() => {
     >
       <slot name="search-form">
         <SearchForm
-          v-if="searchForm"
-          :form="searchForm"
+          v-if="props.table?.searchForm"
+          :form="props.table.searchForm"
           v-bind="computedSearchFormConfig"
           @search="searchPage1st"
           @reset="reset"
@@ -358,7 +413,7 @@ onMounted(() => {
             :columns="
               normalizedRawColumns.filter(item => item.key !== '_index')
             "
-            :table="table"
+            :table="props.table"
             :column-control="columnControlConfig"
           />
         </div>