164 lines
6.0 KiB
Markdown
164 lines
6.0 KiB
Markdown
## Context
|
||
|
||
当前前端项目使用 Vue 3 + Vant UI 构建，虽然已有封装的 `PopupContainer.vue` 组件，但项目中存在多种弹窗实现方式：
|
||
|
||
1. **PopupContainer.vue**: 统一的底部弹出式弹窗，支持标题、副标题、固定头部/页脚、内容滚动
|
||
2. **AddClassifyDialog.vue**: 基于 `van-dialog` 的独立对话框组件，用于新增分类
|
||
3. **CategoryBillPopup.vue**: 基于 `van-popup` 的独立底部弹窗组件，用于展示分类账单列表
|
||
4. **直接使用 van-dialog**: 多个视图文件中直接使用（如 ClassificationEdit.vue、BillAnalysisView.vue）
|
||
5. **直接使用 van-popup**: 多个视图文件中用于选择器、表单等场景（如 PeriodicRecord.vue、statisticsV2/Index.vue）
|
||
|
||
这种分散的实现导致：
|
||
- 弹窗风格不统一（标题样式、圆角、间距、字体大小等）
|
||
- 代码重复度高，维护成本高
|
||
- 用户体验不一致
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- 统一所有弹窗组件使用 `PopupContainer` 或其扩展组件
|
||
- 确保弹窗的视觉风格和交互行为一致
|
||
- 减少代码重复，提高可维护性
|
||
- 扩展 `PopupContainer` 功能以覆盖现有所有使用场景
|
||
|
||
**Non-Goals:**
|
||
- 不修改 Vant UI 组件库本身
|
||
- 不改变弹窗的业务逻辑（仅重构 UI 层）
|
||
- 不影响后端 API
|
||
|
||
## Decisions
|
||
|
||
### 1. 扩展现有 PopupContainer 组件而非创建新组件
|
||
|
||
**选择理由:**
|
||
- `PopupContainer.vue` 已有成熟的底部弹窗布局和样式
|
||
- 仅需扩展其功能即可覆盖大部分使用场景
|
||
- 避免引入新的组件，减少学习成本
|
||
|
||
**扩展点:**
|
||
- 添加 `confirm` 和 `cancel` 事件，支持简单确认对话框场景
|
||
- 添加 `showConfirmButton` 和 `showCancelButton` props，控制按钮显示
|
||
- 添加 `confirmText` 和 `cancelText` props，自定义按钮文本
|
||
- 保留插槽机制，支持复杂表单场景
|
||
|
||
### 2. 保留 PopupContainer 的插槽设计
|
||
|
||
**选择理由:**
|
||
- 插槽提供最大的灵活性，支持任意复杂的内容
|
||
- 现有代码已使用插槽模式（header-actions、footer），保持向后兼容
|
||
- 避免 API 过度设计，保持组件简洁
|
||
|
||
### 3. 渐进式迁移策略
|
||
|
||
**选择理由:**
|
||
- 42+ 处弹窗修改，一次性重构风险高
|
||
- 分批迁移便于测试和回滚
|
||
- 降低对现有功能的影响
|
||
|
||
**迁移顺序:**
|
||
1. 扩展 `PopupContainer` 组件
|
||
2. 迁移 `AddClassifyDialog.vue` 和 `CategoryBillPopup.vue`
|
||
3. 迁移 `views/` 目录中的弹窗，按功能模块分批
|
||
|
||
### 4. 不删除 AddClassifyDialog 和 CategoryBillPopup 组件文件
|
||
|
||
**选择理由:**
|
||
- 这两个组件封装了特定的业务逻辑（如表单验证、数据加载）
|
||
- 可以将它们改造为使用 `PopupContainer` 的组合组件，保留业务逻辑
|
||
- 避免破坏其他引用这些组件的地方
|
||
|
||
**改造方式:**
|
||
- 将 `AddClassifyDialog.vue` 改造为使用 `PopupContainer` 的组合组件
|
||
- 将 `CategoryBillPopup.vue` 改造为使用 `PopupContainer` 的组合组件
|
||
- 组件 API 保持不变，仅内部实现变更
|
||
|
||
### 5. 使用 Vant UI 的 CSS 变量
|
||
|
||
**选择理由:**
|
||
- 项目已使用 Vant UI，保持视觉一致性
|
||
- 支持深色/浅色主题切换
|
||
- 减少自定义 CSS 代码量
|
||
|
||
## Risks / Trade-offs
|
||
|
||
### 1. 扩展 PopupContainer 可能导致 API 膨胀
|
||
|
||
**风险**: 扩展功能过多后，组件变得复杂，难以维护
|
||
|
||
**缓解措施**:
|
||
- 保持核心 API 简洁，使用插槽处理复杂场景
|
||
- 添加清晰的文档和示例
|
||
- 考虑拆分为多个专用组件（如 ConfirmDialog、FormDialog）如果过于复杂
|
||
|
||
### 2. 迁移过程中可能引入 Bug
|
||
|
||
**风险**: 重构可能破坏现有功能
|
||
|
||
**缓解措施**:
|
||
- 渐进式迁移，每批迁移后进行完整测试
|
||
- 保留旧代码作为参考，直到新代码稳定
|
||
- 重点测试弹窗的打开/关闭、表单验证、数据加载等交互
|
||
|
||
### 3. 某些场景可能不适用 PopupContainer
|
||
|
||
**风险**: 一些特殊的弹窗场景（如全屏弹窗、居中弹窗）无法用底部弹窗实现
|
||
|
||
**缓解措施**:
|
||
- 识别这些特殊场景，评估是否需要保留 `van-dialog` 或创建新的专用组件
|
||
- 优先统一常见场景，特殊场景可以例外
|
||
|
||
### 4. 性能影响
|
||
|
||
**风险**: 组件封装层可能增加轻微的性能开销
|
||
|
||
**缓解措施**:
|
||
- 保持组件轻量化，避免不必要的响应式依赖
|
||
- 使用 Vue 3 的 `<script setup>` 语法，减少运行时开销
|
||
- 进行性能测试，确保没有明显退化
|
||
|
||
## Migration Plan
|
||
|
||
### 阶段 1: 扩展 PopupContainer 组件
|
||
1. 添加确认对话框相关 props（`showConfirmButton`、`showCancelButton`、`confirmText`、`cancelText`）
|
||
2. 添加 `confirm` 和 `cancel` 事件
|
||
3. 更新样式，确保与现有设计一致
|
||
4. 编写组件文档和示例
|
||
|
||
### 阶段 2: 改造现有封装组件
|
||
1. 改造 `AddClassifyDialog.vue`，使用 `PopupContainer` 实现
|
||
2. 改造 `CategoryBillPopup.vue`，使用 `PopupContainer` 实现
|
||
3. 测试改造后的组件功能
|
||
|
||
### 阶段 3: 迁移 views/ 目录中的弹窗
|
||
按功能模块分批迁移：
|
||
1. 分类相关视图（ClassificationEdit.vue、ClassificationBatch.vue 等）
|
||
2. 账单相关视图（PeriodicRecord.vue、TransactionsRecord.vue 等）
|
||
3. 统计相关视图（statisticsV2/Index.vue 等）
|
||
4. 预算相关视图（budgetV2/*.vue）
|
||
5. 其他视图（BillAnalysisView.vue、calendarV2/Index.vue 等）
|
||
|
||
### 阶段 4: 验证和优化
|
||
1. 全量测试所有弹窗功能
|
||
2. 性能测试和优化
|
||
3. 代码审查和清理
|
||
4. 更新文档
|
||
|
||
### 回滚策略
|
||
- 使用 Git 分支进行开发，主分支保持稳定
|
||
- 每个阶段完成后打 Tag，便于快速回滚
|
||
- 保留旧的实现代码，直到新代码完全稳定
|
||
|
||
## Open Questions
|
||
|
||
1. 是否需要创建专门的 `ConfirmDialog` 组件？
|
||
- 当前考虑扩展 `PopupContainer` 以支持确认对话框场景
|
||
- 如果确认对话框的使用场景较多且简单，可以考虑独立组件
|
||
|
||
2. 如何处理全屏弹窗场景？
|
||
- 识别项目中是否存在全屏弹窗需求
|
||
- 如有，评估是否需要扩展 `PopupContainer` 或创建新组件
|
||
|
||
3. 弹窗动画是否需要统一？
|
||
- 当前依赖 Vant UI 的默认动画
|
||
- 如有特殊需求，可能需要自定义动画
|