@melt-js/comps-vben 0.0.0-stage → 2026.11.8-2

package/src/plugins/vxe-table/use-vxe-grid.vue

@@ -0,0 +1,564 @@
+<script lang="ts" setup>
+import type {
+  VxeGridDefines,
+  VxeGridInstance,
+  VxeGridListeners,
+  VxeGridPropTypes,
+  VxeGridProps as VxeTableGridProps,
+  VxeToolbarPropTypes,
+} from 'vxe-table';
+
+import type { SetupContext } from 'vue';
+
+import type { VbenFormProps } from '@melt-js/comps-vben/form-ui';
+
+import type { ExtendedVxeGridApi, VxeGridProps } from './types';
+
+import {
+  computed,
+  nextTick,
+  onMounted,
+  onUnmounted,
+  toRaw,
+  useSlots,
+  useTemplateRef,
+  watch,
+} from 'vue';
+
+import { usePriorityValues } from '@melt-js/libs-vben/hooks';
+import { EmptyIcon } from '@melt-js/libs-vben/icons';
+import { $t } from '@melt-js/libs-vben/locales';
+import { usePreferences } from '@melt-js/libs-vben/preferences';
+import {
+  cloneDeep,
+  cn,
+  isBoolean,
+  isEqual,
+  mergeWithArrayOverride,
+} from '@melt-js/libs-vben/utils';
+
+import { VbenHelpTooltip, VbenLoading } from '@melt-js/comps-vben/shadcn-ui';
+
+import { VxeUI } from '@vxe-ui/core';
+import { VxeButton } from 'vxe-pc-ui';
+import { VxeGrid } from 'vxe-table';
+
+import { extendProxyOptions, wrapProxyAjaxOptions } from './extends';
+import { useTableForm } from './init';
+import { applyViewedRowOptions, useViewedRow } from './viewed-row';
+
+import 'vxe-table/styles/cssvar.scss';
+import 'vxe-pc-ui/styles/cssvar.scss';
+import './style.css';
+
+interface Props extends VxeGridProps {
+  api: ExtendedVxeGridApi;
+}
+
+const props = withDefaults(defineProps<Props>(), {});
+
+const FORM_SLOT_PREFIX = 'form-';
+
+const TOOLBAR_ACTIONS = 'toolbar-actions';
+const TOOLBAR_TOOLS = 'toolbar-tools';
+const TABLE_TITLE = 'table-title';
+
+const gridRef = useTemplateRef<VxeGridInstance>('gridRef');
+
+const state = props.api?.useStore?.();
+
+const {
+  gridOptions,
+  class: className,
+  gridClass,
+  gridEvents,
+  formOptions,
+  tableTitle,
+  tableData,
+  tableTitleHelp,
+  showSearchForm,
+  separator,
+  viewedRowOptions,
+} = usePriorityValues(props, state);
+
+// viewedRowOptions：helper 只创建一次（persist/keyField 不支持运行时切换）
+// actionCodes、rowClassName、rowStyle、viewedKeys 的变化通过 options computed 自然响应
+const gridApi = props.api;
+
+watch(
+  viewedRowOptions,
+  (cfg) => {
+    // helper 已存在则不重建
+    if (gridApi.viewedRowHelper) return;
+
+    if (!cfg) return;
+
+    const keyField = (gridOptions.value?.rowConfig as any)?.keyField || 'id';
+    const resolved = isBoolean(cfg) ? { keyField } : { keyField, ...cfg };
+    gridApi.viewedRowHelper = useViewedRow(resolved);
+  },
+  { immediate: true },
+);
+
+const { isMobile } = usePreferences();
+const isSeparator = computed(() => {
+  if (
+    !formOptions.value ||
+    showSearchForm.value === false ||
+    separator.value === false
+  ) {
+    return false;
+  }
+  if (separator.value === true || separator.value === undefined) {
+    return true;
+  }
+  return separator.value.show !== false;
+});
+const separatorBg = computed(() => {
+  return !separator.value ||
+    isBoolean(separator.value) ||
+    !separator.value.backgroundColor
+    ? undefined
+    : separator.value.backgroundColor;
+});
+const slots: SetupContext['slots'] = useSlots();
+
+const [Form, formApi] = useTableForm({
+  compact: true,
+  handleSubmit: async () => {
+    const formValues = await formApi.getValues();
+    formApi.setLatestSubmissionValues(toRaw(formValues));
+    props.api.reload(formValues);
+  },
+  handleReset: async () => {
+    const prevValues = await formApi.getValues();
+    await formApi.reset();
+    const formValues = await formApi.getValues();
+    formApi.setLatestSubmissionValues(formValues);
+    // 如果值发生了变化，submitOnChange会触发刷新。所以只在submitOnChange为false或者值没有发生变化时，手动刷新
+    if (isEqual(prevValues, formValues) || !formOptions.value?.submitOnChange) {
+      props.api.reload(formValues);
+    }
+  },
+  commonConfig: {
+    componentProps: {
+      class: 'w-full',
+    },
+  },
+  showCollapseButton: true,
+  submitButtonOptions: {
+    content: computed(() => $t('common.search')),
+  },
+  wrapperClass: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
+});
+
+const showTableTitle = computed(() => {
+  return !!slots[TABLE_TITLE] || tableTitle.value;
+});
+
+const showToolbar = computed(() => {
+  return (
+    !!slots[TOOLBAR_ACTIONS] || !!slots[TOOLBAR_TOOLS] || showTableTitle.value
+  );
+});
+
+const toolbarOptions = computed(() => {
+  const hasSlotActions = !!slots[TOOLBAR_ACTIONS];
+  const hasSlotTools = !!slots[TOOLBAR_TOOLS];
+  const searchBtn: VxeToolbarPropTypes.ToolConfig = {
+    code: 'search',
+    icon: 'vxe-icon-search',
+    circle: true,
+    status: showSearchForm.value ? 'primary' : undefined,
+    title: showSearchForm.value
+      ? $t('common.hideSearchPanel')
+      : $t('common.showSearchPanel'),
+  };
+  // 将搜索按钮合并到用户配置的toolbarConfig.tools中
+  const toolbarConfig: VxeGridPropTypes.ToolbarConfig = {
+    tools: (gridOptions.value?.toolbarConfig?.tools ??
+      []) as VxeToolbarPropTypes.ToolConfig[],
+  };
+  if (gridOptions.value?.toolbarConfig?.search && !!formOptions.value) {
+    toolbarConfig.tools = Array.isArray(toolbarConfig.tools)
+      ? [...toolbarConfig.tools, searchBtn]
+      : [searchBtn];
+  }
+
+  if (!showToolbar.value) {
+    toolbarConfig.enabled = false;
+    return { toolbarConfig };
+  }
+
+  // 强制使用固定的toolbar配置，不允许用户自定义
+  // 减少配置的复杂度，以及后续维护的成本
+  toolbarConfig.slots = {
+    ...(hasSlotActions || showTableTitle.value
+      ? { buttons: TOOLBAR_ACTIONS }
+      : {}),
+    ...(hasSlotTools ? { tools: TOOLBAR_TOOLS } : {}),
+  };
+  return { toolbarConfig };
+});
+
+const options = computed(() => {
+  const globalGridConfig = VxeUI?.getConfig()?.grid ?? {};
+
+  // mergeWithArrayOverride is defu-based: nested objects that only exist in
+  // the defaults layers keep their original references, so the merged result
+  // must be cloned before it is mutated below. Otherwise writes such as
+  // `proxyConfig.autoLoad/enabled` would pollute the caller's source options.
+  const rawMergedOptions: VxeTableGridProps = mergeWithArrayOverride(
+    {},
+    toRaw(toolbarOptions.value),
+    toRaw(gridOptions.value),
+    globalGridConfig,
+  );
+  const mergedOptions: VxeTableGridProps = cloneDeep(rawMergedOptions);
+
+  // Keep the columns/data references stable when unrelated reactive options
+  // change. Otherwise VXE reloads the columns and loses its initialized sort
+  // state, and a cloned data array would make VXE overwrite the data set via
+  // instance methods (reloadData, setMergeCells, ...) with stale option data.
+  mergedOptions.columns = rawMergedOptions.columns;
+  mergedOptions.data = rawMergedOptions.data;
+
+  if (mergedOptions.proxyConfig) {
+    const { ajax } = mergedOptions.proxyConfig;
+    mergedOptions.proxyConfig.enabled = !!ajax;
+    // 不自动加载数据, 由组件控制
+    mergedOptions.proxyConfig.autoLoad = false;
+    // gridOptions 可能由父组件以 prop 传入（优先级高于 state），写入
+    // state 的包装器会被 prop 遮蔽。这里对最终传给 VxeGrid 的克隆选项
+    // 就地包装（幂等），父组件的 prop 不会被修改。
+    wrapProxyAjaxOptions(gridApi, mergedOptions, () =>
+      formApi.getLatestSubmissionValues(),
+    );
+  }
+
+  if (mergedOptions.pagerConfig) {
+    const mobileLayouts = [
+      'PrevJump',
+      'PrevPage',
+      'Number',
+      'NextPage',
+      'NextJump',
+    ] as any;
+    const layouts = [
+      'Total',
+      'Sizes',
+      'Home',
+      ...mobileLayouts,
+      'End',
+    ] as readonly string[];
+    mergedOptions.pagerConfig = mergeWithArrayOverride(
+      {},
+      mergedOptions.pagerConfig,
+      {
+        pageSize: 20,
+        background: true,
+        pageSizes: [10, 20, 30, 50, 100, 200],
+        className: 'mt-2 w-full',
+        layouts: isMobile.value ? mobileLayouts : layouts,
+        size: 'mini' as const,
+      },
+    );
+  }
+  if (mergedOptions.formConfig) {
+    mergedOptions.formConfig.enabled = false;
+  }
+  if (tableData.value && tableData.value.length > 0) {
+    mergedOptions.data = tableData.value;
+  }
+
+  // 注入已读行功能（rowClassName、rowStyle、columns 拦截）
+  if (viewedRowOptions.value && gridApi.viewedRowHelper) {
+    applyViewedRowOptions(
+      mergedOptions,
+      viewedRowOptions.value,
+      gridApi.viewedRowHelper,
+    );
+  }
+
+  return mergedOptions;
+});
+
+function onToolbarToolClick(event: VxeGridDefines.ToolbarToolClickEventParams) {
+  if (event.code === 'search') {
+    onSearchBtnClick();
+  }
+  (
+    gridEvents.value?.toolbarToolClick as VxeGridListeners['toolbarToolClick']
+  )?.(event);
+}
+
+function onSearchBtnClick() {
+  props.api?.toggleSearchForm?.();
+}
+
+const events = computed(() => {
+  return {
+    ...gridEvents.value,
+    toolbarToolClick: onToolbarToolClick,
+  };
+});
+
+const delegatedSlots = computed(() => {
+  const resultSlots: string[] = [];
+
+  for (const key of Object.keys(slots)) {
+    if (
+      !['empty', 'form', 'loading', TOOLBAR_ACTIONS, TOOLBAR_TOOLS].includes(
+        key,
+      )
+    ) {
+      resultSlots.push(key);
+    }
+  }
+  return resultSlots;
+});
+
+const delegatedFormSlots = computed(() => {
+  const resultSlots: string[] = [];
+
+  for (const key of Object.keys(slots)) {
+    if (key.startsWith(FORM_SLOT_PREFIX)) {
+      resultSlots.push(key);
+    }
+  }
+  return resultSlots.map((key) => key.replace(FORM_SLOT_PREFIX, ''));
+});
+
+const showDefaultEmpty = computed(() => {
+  // 检查是否有原生的 VXE Table 空状态配置
+  const hasEmptyText = options.value.emptyText !== undefined;
+  const hasEmptyRender = options.value.emptyRender !== undefined;
+
+  // 如果有原生配置，就不显示默认的空状态
+  return !hasEmptyText && !hasEmptyRender;
+});
+
+async function init() {
+  await nextTick();
+  const globalGridConfig = VxeUI?.getConfig()?.grid ?? {};
+  const defaultGridOptions: VxeTableGridProps = mergeWithArrayOverride(
+    {},
+    toRaw(gridOptions.value),
+    toRaw(globalGridConfig),
+  );
+  props.api?.setState?.({ gridOptions: defaultGridOptions });
+  // Re-wrap after the option update: a parent may have replaced
+  // proxyConfig.ajax callbacks (e.g. via setGridOptions in its onMounted)
+  // after the setup-time wrapping. extendProxyOptions is idempotent, so
+  // already-wrapped handlers are skipped.
+  extendProxyOptions(props.api, toRaw(gridOptions.value) ?? {}, () =>
+    formApi.getLatestSubmissionValues(),
+  );
+
+  // 内部主动加载数据，防止form的默认值影响
+  const autoLoad = defaultGridOptions.proxyConfig?.autoLoad;
+  const enableProxyConfig = options.value.proxyConfig?.enabled;
+  if (enableProxyConfig && autoLoad) {
+    // Wait for VXE to receive the latest options before applying default sort.
+    await nextTick();
+    props.api.grid.commitProxy?.(
+      'initial',
+      formOptions.value ? ((await formApi.getValues()) ?? {}) : {},
+    );
+  }
+
+  // form 由 vben-form代替，所以不适配formConfig，这里给出警告
+  const formConfig = gridOptions.value?.formConfig;
+  // 处理某个页面加载多个Table时，第2个之后的Table初始化报出警告
+  // 因为第一次初始化之后会把defaultGridOptions和gridOptions合并后缓存进State
+  if (formConfig && formConfig.enabled) {
+    console.warn(
+      '[Vben Vxe Table]: The formConfig in the grid is not supported, please use the `formOptions` props',
+    );
+  }
+}
+
+// formOptions支持响应式
+watch(
+  formOptions,
+  () => {
+    formApi.setState((prev: Record<string, any>) => {
+      const finalFormOptions: VbenFormProps = mergeWithArrayOverride(
+        {},
+        formOptions.value,
+        prev,
+      );
+      return {
+        ...finalFormOptions,
+        collapseTriggerResize: !!finalFormOptions.showCollapseButton,
+      };
+    });
+  },
+  {
+    immediate: true,
+  },
+);
+
+// form 由 vben-form 代替，所以需要保证 query 相关事件可以拿到参数。
+// 在 setup 阶段同步包装（而不是在 init 中）：init 首行 await nextTick，
+// 晚于父组件的 onMounted，父组件挂载时调用 query()/reload() 会命中未包装的 ajax。
+// 包装范围与 init 的 defaultGridOptions 一致（gridOptions + 全局 grid 配置）。
+extendProxyOptions(
+  props.api,
+  mergeWithArrayOverride(
+    {},
+    toRaw(gridOptions.value),
+    toRaw(VxeUI?.getConfig()?.grid ?? {}),
+  ),
+  () => formApi.getLatestSubmissionValues(),
+);
+
+// init 之后业务仍可能通过 api.setGridOptions()/setState() 替换 proxyConfig.ajax
+// 回调。监听 ajax 引用变化并重新包装（幂等）：新回调恢复表单值注入，同时把
+// 表单值 getter 刷新为当前挂载实例（重新挂载时旧 wrapper 会被复用）。
+watch(
+  () => toRaw(gridOptions.value)?.proxyConfig?.ajax,
+  (ajax) => {
+    if (!ajax) {
+      return;
+    }
+    extendProxyOptions(props.api, { proxyConfig: { ajax } }, () =>
+      formApi.getLatestSubmissionValues(),
+    );
+  },
+);
+
+const isCompactForm = computed(() => {
+  return formApi.getState()?.compact;
+});
+
+onMounted(() => {
+  props.api?.mount?.(gridRef.value, formApi);
+  init();
+});
+
+onUnmounted(() => {
+  formApi?.unmount?.();
+  props.api?.unmount?.();
+});
+</script>
+
+<template>
+  <div :class="cn('h-full rounded-md bg-card', className)">
+    <VxeGrid
+      ref="gridRef"
+      :class="
+        cn(
+          'p-2',
+          {
+            'pt-0': showToolbar && !formOptions,
+          },
+          gridClass,
+        )
+      "
+      v-bind="options"
+      v-on="events"
+    >
+      <!-- 左侧操作区域或者title -->
+      <template v-if="showToolbar" #toolbar-actions="slotProps">
+        <slot v-if="showTableTitle" name="table-title">
+          <div class="flex-center gap-1 text-[1rem] font-bold">
+            {{ tableTitle }}
+            <VbenHelpTooltip v-if="tableTitleHelp">
+              {{ tableTitleHelp }}
+            </VbenHelpTooltip>
+          </div>
+        </slot>
+        <slot name="toolbar-actions" v-bind="slotProps"> </slot>
+      </template>
+
+      <!-- 继承默认的slot -->
+      <template
+        v-for="slotName in delegatedSlots"
+        :key="slotName"
+        #[slotName]="slotProps"
+      >
+        <slot :name="slotName" v-bind="slotProps"></slot>
+      </template>
+      <template #toolbar-tools="slotProps">
+        <slot name="toolbar-tools" v-bind="slotProps"></slot>
+        <VxeButton
+          icon="vxe-icon-search"
+          circle
+          class="ml-2"
+          v-if="gridOptions?.toolbarConfig?.search && !!formOptions"
+          :status="showSearchForm ? 'primary' : undefined"
+          :title="$t('common.search')"
+          @click="onSearchBtnClick"
+        />
+      </template>
+
+      <!-- form表单 -->
+      <template #form>
+        <div
+          v-if="formOptions"
+          v-show="showSearchForm !== false"
+          :class="
+            cn(
+              'relative rounded-sm py-3',
+              isCompactForm
+                ? isSeparator
+                  ? 'pb-8'
+                  : 'pb-4'
+                : isSeparator
+                  ? 'pb-4'
+                  : 'pb-0',
+            )
+          "
+        >
+          <slot name="form">
+            <Form>
+              <template
+                v-for="slotName in delegatedFormSlots"
+                :key="slotName"
+                #[slotName]="slotProps"
+              >
+                <slot
+                  :name="`${FORM_SLOT_PREFIX}${slotName}`"
+                  v-bind="slotProps"
+                ></slot>
+              </template>
+              <template #reset-before="slotProps">
+                <slot name="reset-before" v-bind="slotProps"></slot>
+              </template>
+              <template #submit-before="slotProps">
+                <slot name="submit-before" v-bind="slotProps"></slot>
+              </template>
+              <template #expand-before="slotProps">
+                <slot name="expand-before" v-bind="slotProps"></slot>
+              </template>
+              <template #expand-after="slotProps">
+                <slot name="expand-after" v-bind="slotProps"></slot>
+              </template>
+            </Form>
+          </slot>
+          <div
+            v-if="isSeparator"
+            :style="{
+              ...(separatorBg ? { backgroundColor: separatorBg } : undefined),
+            }"
+            class="absolute bottom-1 -left-2 z-100 h-2 w-[calc(100%+1rem)] overflow-hidden bg-background-deep md:bottom-2 md:h-3"
+          ></div>
+        </div>
+      </template>
+      <!-- loading -->
+      <template #loading>
+        <slot name="loading">
+          <VbenLoading :spinning="true" />
+        </slot>
+      </template>
+      <!-- 统一控状态 -->
+      <template v-if="showDefaultEmpty" #empty>
+        <slot name="empty">
+          <EmptyIcon class="mx-auto" />
+          <div class="mt-2">{{ $t('common.noData') }}</div>
+        </slot>
+      </template>
+    </VxeGrid>
+  </div>
+</template>

package/src/plugins/vxe-table/viewed-row/index.ts

@@ -0,0 +1,8 @@
+export type {
+  ViewedRowOptions,
+  ViewedRowPersistOptions,
+  ViewedRowStorageAdapter,
+} from './types';
+
+export { applyViewedRowOptions, useViewedRow } from './use-viewed-row';
+export type { ViewedRowHelper } from './use-viewed-row';

package/src/plugins/vxe-table/viewed-row/types.ts

@@ -0,0 +1,84 @@
+import type { VxeTablePropTypes } from 'vxe-table';
+
+import type { Ref } from 'vue';
+
+/**
+ * 自定义存储适配器接口
+ * 用户可接入任意后端（API、IndexedDB wrapper、第三方库等）
+ */
+export interface ViewedRowStorageAdapter {
+  /** 读取所有已查看的 key 列表 */
+  getKeys(): Promise<Array<number | string>>;
+
+  /** 移除所有已查看数据 */
+  removeKeys(): Promise<void>;
+
+  /** 持久化已查看的 key 列表 */
+  setKeys(keys: Array<number | string>): Promise<void>;
+}
+
+/**
+ * 已读行持久化 — 公共基础字段
+ */
+interface ViewedRowPersistBase {
+  /** 持久化数据的存活时间（毫秒） */
+  ttl?: number;
+  /** 最大缓存数量，超出时淘汰最早标记的 key（FIFO），默认 100 */
+  maxSize?: number;
+}
+
+/**
+ * 已读行持久化配置（按 type 区分的联合类型）
+ *
+ * - 'memory'          → 仅内存，不持久化
+ * - 'localStorage'    → 使用 localStorage 整体存储，key 必传
+ * - 'sessionStorage'  → 使用 sessionStorage 整体存储，key 必传
+ * - 'indexedDB'       → 使用 IndexedDB 单条存储，key 必传
+ * - 'custom'          → 用户自定义存储适配器，storage 必传
+ */
+export type ViewedRowPersistOptions =
+  | ({
+      /** IndexedDB 数据库名称，默认 'viewed-table-db' */
+      dbName?: string;
+      /** IndexedDB 数据库版本，默认 1 */
+      dbVersion?: number;
+      /** 存储 key / prefix（必传） */
+      key: string;
+      /** IndexedDB 对象存储名称，默认 'viewed-table-row' */
+      storeName?: string;
+      type: 'indexedDB';
+    } & ViewedRowPersistBase)
+  | ({
+      /** 存储 key（必传） */
+      key: string;
+      type: 'localStorage' | 'sessionStorage';
+    } & ViewedRowPersistBase)
+  | ({
+      /** 自定义存储适配器（必传） */
+      storage: ViewedRowStorageAdapter;
+      type: 'custom';
+    } & ViewedRowPersistBase)
+  | (ViewedRowPersistBase & {
+      type: 'memory';
+    });
+
+/**
+ * 已查看row设置
+ */
+export interface ViewedRowOptions<T = any> {
+  /** 点击 CellOperation 中匹配的 code 时，自动将该行标记为已读 */
+  actionCodes?: string | string[];
+  /** 行唯一标识字段，默认取 gridOptions.rowConfig.keyField，最终兜底 'id' */
+  keyField?: string;
+  /** 已查看的行key列表 */
+  viewedKeys?: Array<number | string> | Ref<Array<number | string>>;
+  /**
+   * 持久化配置
+   * - 传 string：使用内置 localStorage，值为 storage key（向后兼容）
+   * - 传 object：高级配置
+   * - 不传：不持久化（等同于 memory）
+   */
+  persist?: string | ViewedRowPersistOptions;
+  rowClassName?: VxeTablePropTypes.RowClassName<T>;
+  rowStyle?: VxeTablePropTypes.RowStyle<T>;
+}