表格高度管理

高度计算配置

在 setupPageTemplate 中配置 calculateHeight 函数，用于计算表格高度。

setupPageTemplate({
  dependencies: {
    // formHeight: 搜索表单高度
    // otherHeight: tableOptions 中配置的额外高度偏移（用于特殊页面布局）
    calculateHeight: (formHeight, otherHeight = 0) => {
      const navbarHeight = 50;
      const tagsHeight = 34;
      const padding = 16;
      const paginationHeight = 56;

      return (
        window.innerHeight -
        navbarHeight -
        tagsHeight -
        padding -
        formHeight -
        otherHeight -
        paginationHeight
      );
    },
  },
});

tableOptions.otherHeight 配置

当页面有额外的固定高度元素（如 Tab 栏、统计卡片等）时，可以通过 tableOptions.otherHeight 配置额外的高度偏移。

基础用法

import { useState } from "vue-admin-kit";

useState({
  api: { list: getList },
  searchConfig: [...],
  columnsConfig: [...],
  tableOptions: {
    // 传入额外高度偏移（数值）
    otherHeight: 40,
  },
});

动态高度（函数形式）

支持传入函数，实现响应式的高度计算：

import { ref } from "vue";
import { useState } from "vue-admin-kit";

const tabHeight = ref(40);

useState({
  api: { list: getList },
  tableOptions: {
    // 传入函数，支持响应式
    otherHeight: () => tabHeight.value,
  },
});

使用场景示例

<template>
  <!-- 页面有额外的 Tab 栏，高度 40px -->
  <div class="tab-bar" style="height: 40px">
    <el-tabs v-model="activeTab">
      <el-tab-pane label="全部" name="all" />
      <el-tab-pane label="待处理" name="pending" />
    </el-tabs>
  </div>

  <PageTemplate ref="pageTemplateRef">
    <template #table>
      <Table />
    </template>
  </PageTemplate>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { useState, PageTemplate, Table } from "vue-admin-kit";

const activeTab = ref("all");

useState({
  api: { list: getList },
  searchConfig: [...],
  columnsConfig: [...],
  tableOptions: {
    // 补偿 Tab 栏的高度
    otherHeight: 40,
  },
});
</script>

高度事件发射器

用于在表格高度变化时触发更新。

import { useTableHeightEmitter } from "vue-admin-kit";

// 在组件中使用
const emit = defineEmits(["setTableHeight"]);
const { emitSetTableHeight } = useTableHeightEmitter(emit);

// 手动触发高度更新
emitSetTableHeight();

useTableHeight Hook

useTableHeight 是内部使用的 Hook，用于管理表格高度状态。

基础用法

import { useTableHeight } from "vue-admin-kit";

// 创建独立的高度状态实例
const heightState = useTableHeight();

// 手动触发高度计算
heightState.calculateTableHeight();

// 防抖计算高度
heightState.debouncedCalculateHeight(200);

返回值

属性	类型	说明
tableHeight	Ref<number>	表格高度
queryFormRef	Ref<HTMLElement | null>	搜索表单 DOM 引用
showSearch	Ref<boolean>	是否显示搜索
isHeightReady	Ref<boolean>	高度是否已计算完成
calculateTableHeight	() => Promise<void>	手动触发高度计算
debouncedCalculateHeight	(delay?: number) => void	防抖计算高度
preCalculateHeight	(extraFormHeight: number) => void	预计算高度（展开/收起前）
setActive	(active: boolean) => void	设置激活状态

配置选项

interface UseTableHeightOptions {
  /** 其他高度偏移量 */
  otherHeight?: number | (() => number);

  /** 表格区域 el-card 的 padding 高度 */
  tableCardPadding?: number | (() => number);
}

状态隔离机制

从 v1.0.3 开始，每个 PageTemplate 实例自动创建独立的高度状态：

• 自动隔离：无需手动配置 instanceKey，状态隔离是自动的
• provide/inject：PageTemplate 通过 provide 提供状态，Table 通过 inject 获取
• keep-alive 支持：切换页面时自动重新计算高度

工作原理

// PageTemplate 内部实现
const heightState = useTableHeight();
provide("tableHeightState", heightState);

// Table 内部实现
const heightState = inject<TableHeightState>("tableHeightState");

tableCardPadding 配置

当表格区域使用 el-card 包裹时（ui.tableCard: true），需要从表格高度中减去卡片的 padding 高度。

配置优先级

1. 页面级配置（useState 的 ui.tableCardPadding）
2. 全局配置（setupPageTemplate 的 ui.tableCardPadding）
3. 默认值：8px

全局配置

import { setupPageTemplate } from "vue-admin-kit";

setupPageTemplate({
  ui: {
    tableCardPadding: 8, // 全局默认值
  },
});

页面级配置

import { useState } from "vue-admin-kit";

useState({
  api: { list: getList },
  searchConfig: [...],
  columnsConfig: [...],
  ui: {
    tableCard: true,
    tableCardPadding: 16, // 覆盖全局配置
  },
});

不使用 tableCard 时

当 ui.tableCard 为 false 或未设置时，tableCardPadding 不会生效（内部自动设为 0）。

keep-alive 场景

使用 keep-alive 缓存多个页面时，组件会自动处理：

1. onActivated 时重新计算高度
2. onDeactivated 时标记为非激活状态
3. 切换回来时自动恢复正确的高度

无需任何额外配置，开箱即用。

迁移指南（v1.0.3 → v1.0.4）

otherHeight 配置方式变更

// v1.0.3（旧写法）- 通过 Table 组件 prop 传入
<Table :otherHeight="40" />

// v1.0.4（新写法）- 通过 tableOptions 配置传入
useState({
  tableOptions: {
    otherHeight: 40,
  },
});

迁移指南（v1.0.2 → v1.0.3）

移除 instanceKey

// v1.0.2（旧写法）
<PageTemplate instanceKey="table1">
  <template #table>
    <Table instanceKey="table1" />
  </template>
</PageTemplate>

// v1.0.3（新写法）- 直接使用，无需 instanceKey
<PageTemplate>
  <template #table>
    <Table />
  </template>
</PageTemplate>

移除测试辅助函数

// v1.0.2（旧写法）
import {
  resetTableHeightState,
  resetAllTableHeightStates,
} from "vue-admin-kit";
resetTableHeightState(instanceKey);
resetAllTableHeightStates();

// v1.0.3 - 这些函数已移除，不再需要手动重置状态