更新日志

v1.0.4 (2025-12-31)

新特性

• tableOptions.otherHeight 配置：支持通过 tableOptions.otherHeight 配置额外高度偏移

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

  使用场景：

  • 页面有额外的 Tab 栏、统计卡片等固定高度元素时
  • 需要动态调整表格高度偏移时（使用函数形式）

  配置说明：

  类型	示例	说明
  number	otherHeight: 40	固定高度偏移
  function	otherHeight: () => ref.value	动态高度偏移，支持响应式值

• useTableHeight 新增 tableCardPadding 配置：用于指定表格区域 el-card 的 padding 高度，当 tableCard: true 时自动减去该值

• tableCardPadding 支持全局和页面级配置：可在 setupPageTemplate 中全局配置，也可在 useState 的 ui 中页面级配置，优先级：页面级 > 全局 > 默认值（8px）

  // 全局配置
  setupPageTemplate({
    ui: {
      tableCardPadding: 10,
    },
  });
  
  // 页面级配置（覆盖全局）
  useState({
    ui: {
      tableCard: true,
      tableCardPadding: 12,
    },
  });

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

Bug 修复

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

破坏性变更

• 移除 Table 组件 otherHeight prop：该配置已移至 tableOptions.otherHeight

  // ❌ 旧写法（v1.0.3 及之前）
  <Table :otherHeight="40" />
  
  // ✅ 新写法（v1.0.4+）
  useState({
    tableOptions: {
      otherHeight: 40,
    },
  });

文档更新

• 更新表格高度管理文档，添加 tableOptions.otherHeight 配置说明
• 更新 Table 组件文档，移除 otherHeight prop 说明
• 更新类型定义文档，添加 TableOptions.otherHeight 类型说明
• 全面优化最佳实践文档，更新项目结构和配置示例
• 添加迁移指南说明配置方式变更
• README 添加项目 logo，优化页面布局

---

v1.0.3 (2025-12-23)

新特性

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

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

  配置字段说明：

  字段	类型	默认值	说明
  searchCard	boolean | { show: boolean }	false	是否将搜索区域包裹在 el-card 卡片组件中，启用后搜索表单会有卡片边框和阴影效果
  tableCard	boolean | { show: boolean }	false	是否将表格区域包裹在 el-card 卡片组件中，启用后表格会有卡片边框和阴影效果
  formItemSize	'small' | 'default' | 'large'	-	表单项尺寸，用于控制搜索表单、编辑表单中的组件大小

  使用场景：

  • 当页面需要视觉分区时，可以启用卡片包裹
  • 搜索区域和表格区域可以独立控制是否显示卡片
  • 卡片默认使用 shadow="hover" 悬停阴影效果

• 页面级 formItemSize 配置：新增在 ui 配置中设置 formItemSize 的能力

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

  优先级顺序（从高到低）：

  1. pageData.ui.formItemSize - 页面级配置（useState 中设置）
  2. PageTemplate 组件的 size prop
  3. 全局配置（setupPageTemplate 中设置的 ui.formItemSize）

  完整示例：

  // 全局配置（最低优先级）
  setupPageTemplate({
    ui: {
      formItemSize: 'default',
    },
  });
  
  // 页面级配置（最高优先级）
  useState({
    ui: {
      searchCard: true,
      tableCard: false,
      formItemSize: 'small',  // 覆盖全局配置
    },
    searchConfig: [...],
    formConfig: [...],
  });

Bug 修复

• 表格高度计算修复：修复 useTableHeight 中 queryFormRef 无法正确获取搜索表单 DOM 元素的问题

  • 问题表现：calculateHeight 函数接收到的 formHeight 始终为 0
  • 原因：Vue 3 模板 ref 绑定与 hook 返回的共享 ref 存在兼容性问题
  • 解决方案：在 PageTemplate 中使用本地 ref 进行模板绑定，通过 watch 同步到共享状态

• keep-alive 多页面切换修复：修复使用 keep-alive 缓存多个页面时，切换页面导致表格高度计算错误的问题

  • 问题表现：切换到其他页面再切回来，formHeight 变为 0
  • 原因：多个 PageTemplate 实例共享同一个高度状态，切换时状态被覆盖
  • 解决方案：重构 useTableHeight，每个 PageTemplate 实例创建独立的高度状态，通过 provide/inject 传递给 Table 组件

破坏性变更

• 移除 instanceKey prop：PageTemplate 和 Table 组件不再需要 instanceKey 属性，状态隔离现在是自动的
• 移除测试辅助函数：resetTableHeightState 和 resetAllTableHeightStates 不再导出（内部实现已简化）

代码优化

• 类型重构：提取 BasePageConfig 基础接口，消除 UseStateOptions 和 pageDataType 之间的重复定义
• PageTemplate 组件优化：使用动态组件简化搜索区域模板代码，优化 ref 绑定机制
• useTableHeight 优化：
  • 添加 isCalculating 标志防止并发计算
  • 添加 isElementVisible 检查，keep-alive 场景下跳过不可见元素的计算
  • 添加 lastFormHeight 缓存，表单高度未变化时跳过重复计算
  • 增加防抖时间（200ms），减少初始加载时的多次触发

类型导出

• 新增 BasePageConfig 类型导出

---

v1.0.2 (2025-12-22)

新特性

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

  • 支持字符串数组、对象数组、单字符串三种数据格式
  • 支持 typeMap 按标签文本映射类型样式
  • 支持 propsMap 按标签文本映射完整 Tag 属性
  • 支持 max 限制显示数量，超出显示 "+N" 省略提示
  • 继承 Element Plus Tag 所有属性作为默认值

• 多表格场景支持：新增 instanceKey 实例隔离功能

  • PageTemplate 和 Table 组件新增 instanceKey 属性
  • 解决 Tab 切换、v-show 等场景下多表格高度计算冲突问题
  • 支持 string 或 Symbol 类型的实例标识符
  • 自动优化：隔离实例在高度未变化时跳过重复计算，避免切换闪烁

• Table 组件增强：新增 otherHeight 属性，支持传入额外高度偏移用于特殊页面布局

类型导出

• 新增 TagItem、TagData、TagConfig 类型导出
• 新增 TableHeightState、UseTableHeightOptions 类型导出

---

v1.0.1 (2025-12-15)

架构优化与清理

• 移除了未使用的 tableWidth.ts、asyncComponentMap.ts 以及相关 lazy.ts 文件，精简了代码库
• 将 defaultOssApi 实现从类型定义文件中分离，移至 src/shared/utils/oss.ts，提升了类型定义的纯粹性
• 优化依赖管理，移除不必要的打包依赖，显著减小包体积
• 项目结构重构，迁移至 ESLint Flat 配置
• 集成 Vitest 单元测试框架与 GitLab CI 自动化流程

类型系统改进

• 修正了 PageTemplateExposed 接口中 importFile 方法的类型签名，使其与实际实现保持一致，解决了构建错误
• 移除了 PageTemplate/index.vue 中重复的接口定义

性能优化

• 将 src/shared/utils/validate.ts 中的正则表达式提升为模块级常量，避免了重复创建，提升了验证函数的性能

组件增强

• 导出了 DictTag 组件，提供了更灵活的字典标签使用方式

新特性

• Hook 增强：新增 useDialog 用于简化弹窗管理
• 权限控制：新增 v-hasPermi 和 v-hasRole 指令及编程式检查
• 工具库：新增 validURL、isPathMatch 等验证工具及操作辅助函数

文档更新

• 补充了 useTableHeight、formatterRes 和 checkRes 等工具的使用文档
• 完善配置工具函数文档
• 补充核心功能使用说明

---

v1.0.0 (2025-12-01)

首次发布

• PageTemplate CRUD 页面模板组件
• Table 表格组件（基于 VXE-Table）
• 完整的表单控件体系
• 字典管理系统
• 配置工具函数
• TypeScript 类型支持