@qin-ui/element-plus-pro 1.0.8 → 1.1.0

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

@@ -0,0 +1,420 @@
+<script lang="ts" setup generic="T extends Table<any> = Table">
+/**
+ * @component ProTable
+ * @description 配置驱动的表格组件
+ *
+ * ## 架构概览
+ *
+ * ProTable 是表格系统的顶层容器，负责：
+ * 1. 接收 useTable() 创建的表格实例，驱动列、数据源、分页的渲染
+ * 2. 内部集成 SearchForm 搜索区域（基于 ProForm）
+ * 3. 支持列动态控制（显示/隐藏）和尺寸控制
+ * 4. 将分页变化和搜索事件串联到数据查询流程
+ *
+ * ## 数据流
+ *
+ * ```
+ * useTable({ columns, dataSource, searchFields, ... })
+ *   ↓ 传入 :table prop
+ * ProTable
+ *   ├── SearchForm (使用 table.searchForm 管理搜索条件)
+ *   │     └── ProForm
+ *   ├── SizeControl (表格尺寸切换)
+ *   ├── ColumnControl (列显示/隐藏)
+ *   └── ElTable (element-plus Table)
+ *         └── 转发所有 table 插槽
+ * ```
+ *
+ * ## 搜索流程
+ *
+ * 1. 用户点击搜索 → SearchForm @search → searchPage1st()
+ * 2. searchPage1st 重置分页到第一页，触发 _search()
+ * 3. 分页变化 → onTableChange → setPageParam + _search()
+ * 4. 重置 → reset() → resetQueryParams + _search()
+ */
+import {
+  Pagination as ElPagination,
+  type PaginationProps,
+  Table as ElTable,
+  type TableProps,
+  tableProps,
+  paginationProps,
+} from '../../../shared/ui';
+import {
+  computed,
+  nextTick,
+  useAttrs,
+  onMounted,
+  inject,
+  type Slot,
+  useSlots,
+} from 'vue';
+import { INJECT_CONFIG } from '../../component-provider/constants';
+import { ContainerFragment } from '../../form';
+import type { ContainerComponent } from '../../form/types';
+import SearchForm from './SearchForm.vue';
+import type { SearchFormProps } from './SearchForm.vue';
+import type { Table } from '../useTable';
+import { camelizeProperties, getObject, pick } from '../../../shared/core';
+import {
+  DefaultSearchFormContainer,
+  DefaultTableContainer,
+  SizeControl,
+  ColumnControl,
+} from '.';
+import type { Columns } from '../types';
+import TableColumnRenderer from './TableColumnRenderer.vue';
+
+defineOptions({ name: 'ProTable', inheritAttrs: false });
+
+type Control = { sizeControl: boolean; columnControl: boolean };
+
+type SearchFormConfig = Omit<SearchFormProps, 'form'> & {
+  // 是否隐藏搜索表单
+  hidden?: boolean;
+  // 搜索区域包裹容器
+  container?: ContainerComponent | false;
+};
+
+type ReturnTableRecord<V> = V extends Table<any, infer R> ? R : any;
+type RecordType = ReturnTableRecord<T>;
+
+type Props = {
+  // 列表表格对象，returns from useTable
+  table?: T;
+  // 列表数据查询方法
+  search?: () => Promise<unknown>;
+  // 是否在首列插入index列
+  addIndexColumn?: boolean;
+  // onMounted 时立即触发一次 search 事件
+  immediateSearch?: boolean;
+  // 是否展示表格 size 和 column 控制按钮
+  control?: boolean | Partial<Control>;
+  // 搜索栏查询字段表单配置
+  searchFormConfig?: SearchFormConfig;
+  // 表格区域包裹容器
+  tableContainer?: ContainerComponent | false;
+  columns?: Columns<RecordType>;
+  data?: RecordType[];
+  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 config = INJECT_CONFIG['pro-table'];
+const injectProps = inject(config.injectionKey, config.default) as any;
+
+const tableProperties = Object.keys(tableProps());
+const paginationProperties = Object.keys(paginationProps());
+
+const attrs = useAttrs() as Record<string, any>;
+
+const injectTableAttrs = computed(() => {
+  return pick(injectProps, tableProperties) as Partial<TableProps>;
+});
+
+const attrsTableProps = computed(() => {
+  return pick(
+    camelizeProperties(attrs),
+    tableProperties
+  ) as Partial<TableProps>;
+});
+
+const {
+  columns: tableColumns,
+  data: tableData,
+  searchForm,
+  pageParam,
+  setPageParam,
+} = table || {};
+
+const size = defineModel<TableProps['size']>('size');
+const loading = defineModel<boolean>('loading');
+
+// 核心搜索方法：设置 loading 状态，调用外部 search 函数
+const _search = async () => {
+  try {
+    loading.value = true;
+    await search?.();
+  } finally {
+    loading.value = false;
+  }
+};
+
+// 重置：恢复查询参数到初始值，重新搜索
+const reset = () => {
+  table?.resetQueryParams();
+  nextTick(() => {
+    _search();
+  });
+};
+
+type CustomSlots = Readonly<
+  Partial<Record<'search-form' | 'button-bar' | 'toolbar' | 'table', Slot>>
+>;
+
+type Slots = CustomSlots & Readonly<Record<string, Slot>>;
+
+const slots = useSlots() as Slots;
+const searchFormSlot = slots['search-form'];
+const buttonBarSlot = slots['button-bar'];
+const toolbarSlot = slots['toolbar'];
+
+const tableSlots = computed(() => {
+  const customNames = new Set([
+    'search-form',
+    'button-bar',
+    'toolbar',
+    'table',
+  ]);
+  return Object.fromEntries(
+    Object.entries(slots).filter(([name]) => !customNames.has(name))
+  ) as Record<string, Slot>;
+});
+const tableSlotNames = computed(() => Object.keys(tableSlots.value));
+
+const searchPage1st = () => {
+  setPageParam?.({ current: 1 });
+  _search();
+};
+
+const computedSearchFormConfig = computed(() => {
+  const container =
+    searchFormConfig?.container ??
+    injectProps.searchFormConfig?.container ??
+    DefaultSearchFormContainer;
+  return {
+    ...injectProps.searchFormConfig,
+    ...getObject(searchFormConfig),
+    container: container ? container : undefined,
+  };
+});
+
+const computedTableContainer = computed(() => {
+  const container =
+    tableContainer ?? injectProps.tableContainer ?? DefaultTableContainer;
+  return container ? container : undefined;
+});
+
+const normalizedRawColumns = computed(() => {
+  const source = (columns ?? tableColumns?.value ?? []) as any[];
+
+  const normalized = source.map((item, index) => {
+    const current: any = { ...item };
+    if (current.label === undefined && current.title !== undefined) {
+      current.label = current.title;
+    }
+    if (current.prop === undefined && current.dataIndex !== undefined) {
+      current.prop = Array.isArray(current.dataIndex)
+        ? current.dataIndex.join('.')
+        : current.dataIndex;
+    }
+    if (current.key === undefined) {
+      current.key =
+        current.prop ??
+        (typeof current.columnKey === 'string'
+          ? current.columnKey
+          : undefined) ??
+        `col-${index}`;
+    }
+    return current;
+  });
+  if (addIndexColumn ?? injectProps.addIndexColumn) {
+    return [
+      {
+        key: '_index',
+        type: 'index',
+        label: '序号',
+        width: 80,
+      },
+      ...normalized,
+    ];
+  }
+  return normalized;
+});
+
+const computedDataSource = computed<any[]>(() => {
+  const attrsData = attrsTableProps.value.data as any[] | undefined;
+  return data ?? attrsData ?? tableData?.value ?? [];
+});
+
+const computedTableProps = computed<TableProps>(() => {
+  const merged = {
+    ...injectTableAttrs.value,
+    ...attrsTableProps.value,
+  } as TableProps;
+  delete (merged as any).data;
+  return merged;
+});
+
+const computedPagination = computed<false | Partial<PaginationProps>>(() => {
+  if (pagination === false) return false;
+  const pageConfig = pagination ?? {};
+  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,
+  };
+});
+
+const showPagination = computed(() => computedPagination.value !== false);
+
+const onCurrentChange = (current: number) => {
+  setPageParam?.({ current });
+  _search();
+};
+
+const onSizeChange = (pageSize: number) => {
+  setPageParam?.({ pageSize, current: 1 });
+  _search();
+};
+
+const onPaginationChange = (currentPage: number, pageSize: number) => {
+  attrs.onChange?.(currentPage, pageSize);
+};
+
+const showSearch = computed(() => {
+  return !!(
+    searchFormSlot ||
+    (computedSearchFormConfig.value?.hidden !== true &&
+      searchForm &&
+      searchForm.fields.value.filter(item => !item.hidden)?.length > 0)
+  );
+});
+
+const computedControl = computed<Control>(() => {
+  const mergedControl = control ?? injectProps.control;
+  const sizeControl = (mergedControl as Control)?.sizeControl ?? mergedControl;
+  const columnControl =
+    (mergedControl as Control)?.columnControl ?? mergedControl;
+  return { sizeControl: !!sizeControl, columnControl: !!columnControl };
+});
+
+const resolvedSize = computed(() => {
+  return (
+    size.value ??
+    (attrsTableProps.value.size as any) ??
+    injectTableAttrs.value.size
+  );
+});
+
+onMounted(() => {
+  if (immediateSearch ?? injectProps.immediateSearch) {
+    _search();
+  }
+});
+</script>
+
+<template>
+  <div
+    class="pro-table"
+    :class="($attrs as any).class"
+    :style="($attrs as any).style"
+  >
+    <ContainerFragment
+      v-if="showSearch"
+      :component="computedSearchFormConfig.container"
+    >
+      <slot name="search-form">
+        <SearchForm
+          v-if="searchForm"
+          :form="searchForm"
+          v-bind="computedSearchFormConfig"
+          @search="searchPage1st"
+          @reset="reset"
+        />
+      </slot>
+    </ContainerFragment>
+
+    <ContainerFragment :component="computedTableContainer">
+      <div class="pro-table_header">
+        <div v-if="buttonBarSlot" class="pro-table_header_button-bar">
+          <slot name="button-bar" />
+        </div>
+        <div v-if="toolbarSlot" class="pro-table_header_toolbar">
+          <slot name="toolbar" />
+        </div>
+        <div
+          v-if="computedControl.sizeControl"
+          class="pro-table_header_size-control"
+        >
+          <SizeControl v-model:size="size" />
+        </div>
+        <div
+          v-if="computedControl.columnControl"
+          class="pro-table_header_column-control"
+        >
+          <ColumnControl :columns="normalizedRawColumns" :table="table" />
+        </div>
+      </div>
+
+      <slot name="table">
+        <ElTable
+          v-loading="loading"
+          class="pro-table_content"
+          v-bind="computedTableProps"
+          :size="resolvedSize"
+          :data="computedDataSource"
+        >
+          <TableColumnRenderer :columns="normalizedRawColumns" />
+          <template v-for="name in tableSlotNames" :key="name" #[name]="scoped">
+            <slot :name="name" v-bind="scoped" />
+          </template>
+        </ElTable>
+      </slot>
+
+      <ElPagination
+        v-if="showPagination"
+        class="pro-table_pagination"
+        v-bind="computedPagination"
+        @current-change="onCurrentChange"
+        @size-change="onSizeChange"
+        @change="onPaginationChange"
+      />
+    </ContainerFragment>
+  </div>
+</template>
+
+<style scoped lang="less">
+.pro-table {
+  &_header {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+
+    &:empty {
+      display: none;
+    }
+
+    & + &_content {
+      margin-top: 16px;
+    }
+
+    &_button-bar {
+      flex: 1;
+    }
+
+    &_toolbar {
+      margin-left: 12px;
+    }
+  }
+
+  &_pagination {
+    justify-content: flex-end;
+    padding: 16px 0;
+  }
+}
+</style>

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

@@ -0,0 +1,302 @@
+<script lang="ts">
+type Expand = {
+  // 网格布局时默认展开行数量
+  minExpandRows?: number;
+  // 网格布局时展开状态
+  expandStatus?: boolean;
+};
+
+type _FormProps = Pick<
+  Partial<FormProps>,
+  | 'disabled'
+  | 'labelPosition'
+  | 'labelWidth'
+  | 'inline'
+  | 'inlineMessage'
+  | 'statusIcon'
+  | 'showMessage'
+  | 'size'
+>;
+
+type ButtonProps = { onClick: () => void };
+type ExpandButtonProps = ButtonProps & { expandStatus: boolean };
+
+export type SearchFormProps = {
+  form: Form;
+  layout?: 'grid' | 'inline';
+  expand?: boolean | Expand;
+  searchButton?: Component<ButtonProps> | DefineComponent<ButtonProps> | false;
+  resetButton?: Component<ButtonProps> | DefineComponent<ButtonProps> | false;
+  expandButton?:
+    | Component<ExpandButtonProps>
+    | DefineComponent<ExpandButtonProps>
+    | false;
+  rowGap?: number;
+  columnGap?: number;
+} & /* @vue-ignore */ _FormProps &
+  AllowedComponentProps;
+</script>
+
+<script lang="ts" setup>
+/**
+ * @component SearchForm
+ * @description ProTable 的搜索表单子组件
+ *
+ * ## 核心功能
+ *
+ * 1. 内部渲染 ProForm，使用 table.searchForm 管理搜索条件
+ * 2. 支持 grid（网格）和 inline（行内）两种布局
+ * 3. 网格布局下支持展开/折叠：通过 IntersectionObserver 自动检测哪些字段溢出
+ * 4. 提供搜索、重置、展开/折叠按钮（支持自定义）
+ *
+ * ## 展开/折叠机制
+ *
+ * 1. 首次渲染后，测量 ProForm 的实际高度
+ * 2. 根据 minExpandRows 计算折叠高度（默认 2 行）
+ * 3. 如果实际高度 > 折叠高度，显示展开/折叠按钮
+ * 4. 使用 IntersectionObserver 检测隐藏字段是否有值，有值则自动展开
+ */
+import { Space, Button, FormProps } from '../../../shared/ui';
+import {
+  AllowedComponentProps,
+  computed,
+  ref,
+  watch,
+  watchEffect,
+  type Component,
+  type DefineComponent,
+} from 'vue';
+import ProForm from '../../form';
+import { type Form } from '../../form';
+import DownOutlined from './icons/DownOutlined.vue';
+
+defineOptions({ name: 'SearchForm' });
+
+const {
+  layout = 'grid',
+  expand = true,
+  searchButton = undefined,
+  resetButton = undefined,
+  expandButton = undefined,
+  rowGap = 16,
+  columnGap = 24,
+  form,
+} = defineProps<SearchFormProps>();
+
+type Emits = {
+  (e: 'search'): void;
+  (e: 'reset'): void;
+};
+const emit = defineEmits<Emits>();
+
+const proFormHeight = ref<'unset' | number>('unset');
+const collapseHeight = ref(0);
+let rowHeight = 32;
+
+const computedExpand = computed(() => {
+  if (!expand) return false;
+  if (expand === true) return { minExpandRows: 2, expandStatus: false };
+  return {
+    minExpandRows: Math.max(Math.floor(expand.minExpandRows ?? 2), 1),
+    expandStatus: expand.expandStatus ?? false,
+  };
+});
+
+const showExpandToggle = ref(false);
+
+const expandStatus = ref(true);
+
+const changeExpandStatus = () => {
+  expandStatus.value = !expandStatus.value;
+};
+
+const { formRef, getFormData } = form;
+
+/*
+ * 使用 IntersectionObserver 检测折叠状态下隐藏字段是否有值
+ * 如果有值则自动展开，让用户看到已填写的搜索条件
+ */
+const setInitExpandStatus = () => {
+  expandStatus.value = false;
+  if (formRef.value && expand) {
+    const formEl = (formRef.value as any).$el;
+    const formItemsEl = formEl.querySelectorAll(
+      "[class*='-form-item'] > [path]"
+    );
+    const observer = new IntersectionObserver(
+      entries => {
+        expandStatus.value = entries.some(e => {
+          // 如果隐藏字段（intersectionRatio === 0）有值，则自动展开
+          if (e.intersectionRatio === 0) {
+            const path = e.target.getAttribute('path');
+            const searchFieldValue = path ? getFormData?.(path) : undefined;
+            return ![null, undefined].includes(searchFieldValue);
+          }
+          return (expand as any).expandStatus;
+        });
+        observer.disconnect();
+      },
+      { root: formEl }
+    );
+    formItemsEl.forEach((element: Element) => {
+      observer.observe(element);
+    });
+  }
+};
+
+watch(
+  [
+    () => form?.fields.value?.filter((f: any) => !f.hidden)?.length,
+    () => formRef.value,
+    () => expand,
+  ],
+  () => {
+    if (!expand || !expandStatus.value || !formRef.value) return;
+    const proFormEl = (formRef.value as any)?.$el;
+    const { height = 0 } = proFormEl?.getBoundingClientRect?.() || {};
+    proFormHeight.value = height;
+    rowHeight = proFormEl
+      ?.querySelector("[class*='-form-item']")
+      ?.getBoundingClientRect?.()?.height;
+  },
+  { flush: 'post', immediate: true }
+);
+
+/*
+ * 计算折叠高度和是否显示展开按钮
+ * 折叠高度 = minExpandRows * 行高 + (minExpandRows - 1) * 行间距
+ * 如果实际高度与折叠高度差异 > 1px，说明有字段溢出，显示展开按钮
+ */
+watchEffect(
+  () => {
+    if (typeof proFormHeight.value !== 'number') return;
+    if (layout === 'grid' && computedExpand.value) {
+      const { minExpandRows } = computedExpand.value;
+      collapseHeight.value = Math.min(
+        minExpandRows * rowHeight + (minExpandRows - 1) * rowGap,
+        +proFormHeight.value
+      );
+      showExpandToggle.value = +proFormHeight.value - collapseHeight.value > 1;
+      if (showExpandToggle.value) {
+        setInitExpandStatus();
+      }
+    } else {
+      showExpandToggle.value = false;
+    }
+  },
+  { flush: 'post' }
+);
+
+const layoutProps = computed(() =>
+  layout === 'grid'
+    ? {
+        grid: {
+          gutter: columnGap,
+          style: { rowGap: `${rowGap}px` },
+        },
+        style: {
+          display: 'flex',
+          overflow: 'hidden',
+          columnGap: `${columnGap}px`,
+          height: `${expandStatus.value ? proFormHeight.value : collapseHeight.value}px`,
+        },
+      }
+    : {
+        inline: true,
+        style: {
+          display: 'flex',
+          flexWrap: 'wrap',
+          gap: `${rowGap}px ${columnGap}px`,
+        },
+        grid: false,
+      }
+);
+
+const onReset = () => {
+  emit('reset');
+};
+
+const onSearch = () => {
+  emit('search');
+};
+</script>
+
+<template>
+  <ProForm
+    v-bind="layoutProps"
+    :form="form"
+    class="pro-table_search-form transition"
+    @keyup.enter="onSearch"
+  >
+    <Space alignment="start" class="pro-table_search-form_button-group">
+      <slot name="reset-button" @click="onReset">
+        <template v-if="resetButton !== false">
+          <component :is="resetButton" v-if="resetButton" @click="onReset" />
+          <Button
+            v-else
+            class="pro-table_search-form_reset-button"
+            @click="onReset"
+            >重置</Button
+          >
+        </template>
+      </slot>
+      <slot name="search-button" @click="onSearch">
+        <template v-if="searchButton !== false">
+          <component :is="searchButton" v-if="searchButton" @click="onSearch" />
+          <Button
+            v-else
+            class="pro-table_search-form_search-button"
+            type="primary"
+            native-type="submit"
+            @click="onSearch"
+          >
+            查询
+          </Button>
+        </template>
+      </slot>
+      <slot name="expand-button" @click="changeExpandStatus">
+        <template v-if="expandButton !== false && showExpandToggle">
+          <component
+            :is="expandButton"
+            v-if="expandButton"
+            :expand-status="expandStatus"
+            @click="changeExpandStatus"
+          />
+          <Button
+            v-else
+            text
+            class="pro-table_search-form_expand-toggle-button"
+            @click="changeExpandStatus"
+          >
+            {{ expandStatus ? '收起' : '展开' }}
+            <DownOutlined
+              class="transition"
+              style="margin-left: 4px"
+              :style="{ transform: `rotate(${expandStatus ? -180 : 0}deg)` }"
+            />
+          </Button>
+        </template>
+      </slot>
+    </Space>
+  </ProForm>
+</template>
+
+<style scoped lang="less">
+.pro-table_search-form {
+  :deep {
+    [class*='-form-item'] {
+      margin: 0;
+    }
+  }
+  &_expand-toggle-button {
+    display: flex;
+    align-items: center;
+    padding: 0;
+    padding-left: 4px;
+  }
+
+  .transition {
+    transition: all 0.25s;
+  }
+}
+</style>