6.1 KiB

Raw Blame History

Design Document

Overview

本设计文档描述了在样品管理列表中添加备注列并实现 tooltip 功能的技术方案。该功能将利用 Element UI 的 el-table-column 组件的 show-overflow-tooltip 属性，实现当备注内容超出列宽时自动显示省略号，并在鼠标悬停时通过 tooltip 展示完整内容。

Architecture

该功能是一个纯前端实现，不涉及后端 API 修改。主要修改点在样品管理页面的 Vue 组件中。

组件层次结构

WarehouseSample (Vue Component)
  └── el-table
      ├── el-table-column (入库单号)
      ├── el-table-column (样品型号)
      ├── el-table-column (样品SN号)
      ├── el-table-column (硬件版本号)
      ├── el-table-column (外测状态)
      ├── el-table-column (计划测试项)
      ├── el-table-column (测试截止日期)
      ├── el-table-column (状态)
      ├── el-table-column (备注) ← 新增
      └── el-table-column (操作)

Components and Interfaces

修改的组件

文件路径: ruoyi-fastapi-frontend/src/views/warehouse/sample/index.vue

新增表格列

在 <el-table> 组件中，在状态列和操作列之间添加备注列：

<el-table-column 
  label="备注" 
  align="center" 
  prop="remark" 
  :show-overflow-tooltip="true"
  width="150"
/>

Element UI 组件属性说明

label: 列标题，显示为"备注"
align: 对齐方式，设置为"center"居中对齐
prop: 绑定的数据字段，对应 sampleList 中每个对象的 remark 属性
show-overflow-tooltip: Element UI 内置属性，当内容超出时自动显示 tooltip
width: 列宽度，设置为 150px 以平衡显示空间和表格整体布局

Data Models

样品数据模型

样品列表数据已包含 remark 字段，无需修改数据结构：

{
  sampleId: Number,
  receiptNo: String,
  sampleModel: String,
  sampleSn: String,
  hardwareVersion: String,
  externalStatus: String,
  testItems: String,
  testDeadline: String,
  status: String,
  remark: String  // 备注字段，已存在于后端返回数据中
}

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property 1: 备注列渲染完整性

For any 样品列表数据，当页面渲染完成后，表格中应该存在一个 label 为"备注"的列，且该列位于状态列之后、操作列之前

Validates: Requirements 1.1, 1.2

For any 备注单元格，当且仅当备注内容的实际渲染宽度超过列宽度时，鼠标悬停应触发 tooltip 显示

Validates: Requirements 2.1, 2.2, 2.4

Property 3: 空备注处理

For any 样品数据，如果 remark 字段为 null、undefined 或空字符串，则对应单元格应显示为空白，且不触发 tooltip

Validates: Requirements 1.3

Property 4: 样式一致性

For any 备注列单元格，其字体、字号、颜色和对齐方式应与同一行其他文本列（如样品型号、样品SN号）保持一致

Validates: Requirements 3.1, 3.2, 3.3

Error Handling

数据缺失处理

当 API 返回的样品数据中不包含 remark 字段时，Vue 会将其视为 undefined，单元格显示为空白
Element UI 的 show-overflow-tooltip 会自动处理 null/undefined 值，不会报错

浏览器兼容性

Element UI 的 tooltip 功能基于 Popper.js，支持主流浏览器（Chrome, Firefox, Safari, Edge）
在不支持的旧版浏览器中，tooltip 可能不显示，但不会影响基本的文本显示功能

Testing Strategy

单元测试

由于这是一个简单的 UI 展示功能，主要依赖 Element UI 的内置功能，不需要编写复杂的单元测试。可以通过以下方式验证：

备注列存在性测试: 检查渲染后的 DOM 中是否存在包含"备注"文本的表头
数据绑定测试: 验证备注列是否正确显示 sampleList 中的 remark 数据
空值处理测试: 验证当 remark 为空时，单元格是否正确显示为空白

手动测试场景

正常显示测试
- 准备包含不同长度备注的样品数据
- 验证短备注完整显示，长备注显示省略号
- 验证鼠标悬停时 tooltip 正确显示完整内容
边界情况测试
- 测试备注为空字符串的情况
- 测试备注为 null 的情况
- 测试备注恰好等于列宽的情况
响应式测试
- 调整浏览器窗口大小
- 验证备注列宽度和 tooltip 行为是否正常
交互测试
- 快速移动鼠标经过多个备注单元格
- 验证 tooltip 显示和隐藏的流畅性
- 验证 tooltip 不会遮挡操作按钮

测试库选择

对于这个简单的 UI 功能，不需要引入 property-based testing 库。主要通过手动测试和简单的 Vue Test Utils 单元测试即可验证功能正确性。

Implementation Notes

实现步骤

在 ruoyi-fastapi-frontend/src/views/warehouse/sample/index.vue 文件中定位到 <el-table> 组件
在状态列（<el-table-column label="状态" ...>）之后添加新的备注列
配置备注列的属性：label、align、prop、show-overflow-tooltip、width
保存文件并测试功能

注意事项

列宽度设置为 150px 是一个建议值，可以根据实际显示效果调整
show-overflow-tooltip 属性会自动处理文本溢出和 tooltip 显示，无需额外编写 JavaScript 代码
如果需要自定义 tooltip 的样式或行为，可以使用 Element UI 的 tooltip 组件手动实现

可选优化

如果未来需要更高级的功能，可以考虑：

自定义 tooltip 内容: 使用 scoped slot 自定义 tooltip 的显示格式
可配置列宽: 允许用户拖拽调整备注列宽度
备注编辑: 在 tooltip 中添加快速编辑按钮

6.1 KiB Raw Blame History Unescape Escape