迁移指南

本文档帮助你从旧版本升级到新版本。

从 v1.0.3 升级到 v1.0.4

破坏性变更

移除 Table 组件 otherHeight prop

otherHeight 配置已从 Table 组件 prop 移至 tableOptions.otherHeight。

旧写法（v1.0.3 及之前）

<Table :otherHeight="40" />

新写法（v1.0.4+）

useState({
  tableOptions: {
    otherHeight: 40,
    // 或函数形式（支持响应式）
    // otherHeight: () => tabHeight.value,
  },
});

新增功能

tableOptions.otherHeight 配置

支持通过 tableOptions.otherHeight 配置额外高度偏移，用于补偿页面中 Tab 栏、统计卡片等固定高度元素。

useState({
  api: { list: getList },
  tableOptions: {
    // 数值类型
    otherHeight: 40,
    // 或函数类型（支持响应式）
    otherHeight: () => tabHeight.value,
  },
});

isElementVisible 工具函数

新增 isElementVisible 函数，用于检查 DOM 元素是否可见，支持 v-show 和 keep-alive 场景。

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

const visible = isElementVisible(element);

Bug 修复

• 修复窗口大小变化和显示/隐藏搜索栏时表格高度自适应失效的问题
• 修复 el-card 包裹时未减去 padding 高度导致出现滚动条的问题
• 修复 otherHeight 参数未实际从表格高度中减去的问题
• 修复显示/隐藏搜索栏时未等待 DOM 更新就触发高度计算的问题

---

从 v1.0.2 升级到 v1.0.3

破坏性变更

移除 instanceKey prop

PageTemplate 和 Table 组件不再需要 instanceKey 属性，状态隔离现在是自动的。

旧写法（v1.0.2）

<PageTemplate :instance-key="Symbol('table1')">
  <template #table>
    <Table :instance-key="Symbol('table1')" />
  </template>
</PageTemplate>

新写法（v1.0.3+）

<PageTemplate>
  <template #table>
    <Table />
  </template>
</PageTemplate>

移除测试辅助函数

resetTableHeightState 和 resetAllTableHeightStates 函数不再导出。

新增功能

UI 配置简写

useState 的 ui 配置现在支持简写格式：

// 简写格式（新增）
useState({
  ui: { searchCard: true, tableCard: false },
});

// 完整格式（原有）
useState({
  ui: { searchCard: { show: true }, tableCard: { show: false } },
});

页面级 formItemSize 配置

useState({
  ui: {
    formItemSize: "small", // 页面级别的表单项尺寸
  },
});

Bug 修复

• 修复 useTableHeight 中 queryFormRef 无法正确获取搜索表单 DOM 元素的问题
• 修复使用 keep-alive 缓存多个页面时，切换页面导致表格高度计算错误的问题

---

从 v1.0.1 升级到 v1.0.2

新增功能

标签列渲染

新增 tags 配置，支持在表格单元格内容后追加显示标签数组：

{
  field: 'tags',
  title: '标签',
  tags: {
    field: 'tagList',
    max: 3,
    typeMap: {
      '重要': 'danger',
      '普通': 'info'
    }
  }
}

Table 组件 otherHeight 属性

新增 otherHeight 属性，支持传入额外高度偏移：

<Table :otherHeight="40" />

注意

此属性在 v1.0.4 中已移除，请使用 tableOptions.otherHeight 替代。

---

从 v1.0.0 升级到 v1.0.1

新增功能

useDialog Hook

新增 useDialog 用于简化弹窗管理：

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

const { visible, title, openDialog, closeDialog } = useDialog({
  title: "新增用户",
});

权限指令

新增 v-hasPermi 和 v-hasRole 指令：

<el-button v-hasPermi="['system:user:add']">新增</el-button>
<el-button v-hasRole="['admin']">管理员操作</el-button>

验证工具

新增多个验证工具函数：

import { validURL, validEmail, validPhone, isPathMatch } from "vue-admin-kit";

架构变更

• 支持双版本构建（Lite/Full）
• 迁移至 ESLint Flat 配置
• 集成 Vitest 单元测试框架