174 lines
6.1 KiB
Markdown
174 lines
6.1 KiB
Markdown
# 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>` 组件中，在状态列和操作列之间添加备注列：
|
||
|
||
```vue
|
||
<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 字段，无需修改数据结构：
|
||
|
||
```javascript
|
||
{
|
||
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**
|
||
|
||
### Property 2: Tooltip 显示条件
|
||
|
||
*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 的内置功能，不需要编写复杂的单元测试。可以通过以下方式验证：
|
||
|
||
1. **备注列存在性测试**: 检查渲染后的 DOM 中是否存在包含"备注"文本的表头
|
||
2. **数据绑定测试**: 验证备注列是否正确显示 sampleList 中的 remark 数据
|
||
3. **空值处理测试**: 验证当 remark 为空时，单元格是否正确显示为空白
|
||
|
||
### 手动测试场景
|
||
|
||
1. **正常显示测试**
|
||
- 准备包含不同长度备注的样品数据
|
||
- 验证短备注完整显示，长备注显示省略号
|
||
- 验证鼠标悬停时 tooltip 正确显示完整内容
|
||
|
||
2. **边界情况测试**
|
||
- 测试备注为空字符串的情况
|
||
- 测试备注为 null 的情况
|
||
- 测试备注恰好等于列宽的情况
|
||
|
||
3. **响应式测试**
|
||
- 调整浏览器窗口大小
|
||
- 验证备注列宽度和 tooltip 行为是否正常
|
||
|
||
4. **交互测试**
|
||
- 快速移动鼠标经过多个备注单元格
|
||
- 验证 tooltip 显示和隐藏的流畅性
|
||
- 验证 tooltip 不会遮挡操作按钮
|
||
|
||
### 测试库选择
|
||
|
||
对于这个简单的 UI 功能，不需要引入 property-based testing 库。主要通过手动测试和简单的 Vue Test Utils 单元测试即可验证功能正确性。
|
||
|
||
## Implementation Notes
|
||
|
||
### 实现步骤
|
||
|
||
1. 在 `ruoyi-fastapi-frontend/src/views/warehouse/sample/index.vue` 文件中定位到 `<el-table>` 组件
|
||
2. 在状态列（`<el-table-column label="状态" ...>`）之后添加新的备注列
|
||
3. 配置备注列的属性：label、align、prop、show-overflow-tooltip、width
|
||
4. 保存文件并测试功能
|
||
|
||
### 注意事项
|
||
|
||
- 列宽度设置为 150px 是一个建议值，可以根据实际显示效果调整
|
||
- show-overflow-tooltip 属性会自动处理文本溢出和 tooltip 显示，无需额外编写 JavaScript 代码
|
||
- 如果需要自定义 tooltip 的样式或行为，可以使用 Element UI 的 tooltip 组件手动实现
|
||
|
||
### 可选优化
|
||
|
||
如果未来需要更高级的功能，可以考虑：
|
||
|
||
1. **自定义 tooltip 内容**: 使用 scoped slot 自定义 tooltip 的显示格式
|
||
2. **可配置列宽**: 允许用户拖拽调整备注列宽度
|
||
3. **备注编辑**: 在 tooltip 中添加快速编辑按钮
|