diff --git a/.doc/BillListComponent-usage.md b/.doc/BillListComponent-usage.md new file mode 100644 index 0000000..27d8dda --- /dev/null +++ b/.doc/BillListComponent-usage.md @@ -0,0 +1,257 @@ +# BillListComponent 使用文档 + +## 概述 + +`BillListComponent` 是一个高内聚的账单列表组件,基于 CalendarV2 风格设计,支持筛选、排序、分页、左滑删除、多选等功能。已替代项目中的旧版 `TransactionList` 组件。 + +**文件位置**: `Web/src/components/Bill/BillListComponent.vue` + +--- + +## Props + +### dataSource +- **类型**: `String` +- **默认值**: `'api'` +- **可选值**: `'api'` | `'custom'` +- **说明**: 数据源模式 + - `'api'`: 组件内部调用 API 获取数据(支持分页、筛选) + - `'custom'`: 父组件传入数据(通过 `transactions` prop) + +### apiParams +- **类型**: `Object` +- **默认值**: `{}` +- **说明**: API 模式下的筛选参数(仅 `dataSource='api'` 时有效) +- **属性**: + - `dateRange`: `[string, string]` - 日期范围,如 `['2026-01-01', '2026-01-31']` + - `category`: `String` - 分类筛选 + - `type`: `0 | 1 | 2` - 类型筛选(0=支出, 1=收入, 2=不计入) + +### transactions +- **类型**: `Array` +- **默认值**: `[]` +- **说明**: 自定义数据源(仅 `dataSource='custom'` 时有效) + +### showDelete +- **类型**: `Boolean` +- **默认值**: `true` +- **说明**: 是否显示左滑删除功能 + +### showCheckbox +- **类型**: `Boolean` +- **默认值**: `false` +- **说明**: 是否显示多选复选框 + +### enableFilter +- **类型**: `Boolean` +- **默认值**: `true` +- **说明**: 是否启用筛选栏(类型、分类、日期、排序) + +### enableSort +- **类型**: `Boolean` +- **默认值**: `true` +- **说明**: 是否启用排序功能(与 `enableFilter` 配合使用) + +### compact +- **类型**: `Boolean` +- **默认值**: `true` +- **说明**: 是否使用紧凑模式(卡片间距 6px) + +### selectedIds +- **类型**: `Set` +- **默认值**: `new Set()` +- **说明**: 已选中的账单 ID 集合(多选模式下) + +--- + +## Events + +### @load +- **参数**: 无 +- **说明**: 触发分页加载(API 模式下自动处理,Custom 模式可用于通知父组件) + +### @click +- **参数**: `transaction` (Object) - 被点击的账单对象 +- **说明**: 点击账单卡片时触发 + +### @delete +- **参数**: `id` (Number | String) - 被删除的账单 ID +- **说明**: 删除账单成功后触发 + +### @update:selectedIds +- **参数**: `ids` (Set) - 新的选中 ID 集合 +- **说明**: 多选状态变更时触发 + +--- + +## 使用示例 + +### 示例 1: API 模式(组件自动加载数据) + +```vue + + + +``` + +### 示例 2: Custom 模式(父组件管理数据) + +```vue + + + +``` + +### 示例 3: 多选模式 + +```vue + + + +``` + +--- + +## 注意事项 + +1. **数据源模式选择**: + - 如果需要自动分页、筛选,使用 `dataSource="api"` + - 如果需要自定义数据管理(如搜索、离线数据),使用 `dataSource="custom"` + +2. **筛选功能**: + - `enableFilter` 控制筛选栏的显示/隐藏 + - 筛选栏包括:类型、分类、日期范围、排序四个下拉菜单 + - Custom 模式下,筛选仅在前端过滤,不会调用 API + +3. **删除功能**: + - 组件内部自动调用 `deleteTransaction` API + - 删除成功后会派发全局事件 `transaction-deleted` + - 父组件通过 `@delete` 事件可执行额外逻辑 + +4. **多选功能**: + - 启用 `showCheckbox` 后,账单项左侧显示复选框 + - 使用 `v-model:selectedIds` 或 `@update:selectedIds` 同步选中状态 + +5. **样式适配**: + - 组件自动适配暗黑模式(使用 CSS 变量) + - `compact` 模式适合列表视图,舒适模式适合详情查看 + +--- + +## 与旧版 TransactionList 的差异 + +| 特性 | 旧版 TransactionList | 新版 BillListComponent | +|------|---------------------|----------------------| +| 数据管理 | 仅支持 Custom 模式 | 支持 API + Custom 模式 | +| 筛选功能 | 无内置筛选 | 内置筛选栏(类型、分类、日期、排序) | +| 样式 | 一行一卡片,间距大 | 紧凑列表,间距 6px | +| 图标 | 无分类图标 | 显示分类图标和彩色背景 | +| Props 命名 | `show-delete` | `show-delete`(保持兼容) | + +--- + +## 相关文件 + +- 组件实现: `Web/src/components/Bill/BillListComponent.vue` +- API 接口: `Web/src/api/transactionRecord.js` +- 设计文档: `openspec/changes/refactor-bill-list-component/design.md` + +--- + +## 常见问题 + +**Q: 如何禁用筛选栏?** +A: 设置 `:enable-filter="false"` + +**Q: Custom 模式下分页如何实现?** +A: 父组件监听 `@load` 事件,追加数据到 `transactions` 数组,并控制 `loading` 和 `finished` 状态 + +**Q: 如何自定义卡片样式?** +A: 使用 `compact` prop 切换紧凑/舒适模式,或通过全局 CSS 变量覆盖样式 + +**Q: CalendarV2 为什么还有单独的 TransactionList?** +A: CalendarV2 的 TransactionList 有特定于日历视图的功能(Smart 按钮、特殊 UI),暂时保留 diff --git a/Web/src/components/Bill/BillListComponent.vue b/Web/src/components/Bill/BillListComponent.vue new file mode 100644 index 0000000..c0a0243 --- /dev/null +++ b/Web/src/components/Bill/BillListComponent.vue @@ -0,0 +1,814 @@ + + + + + + + diff --git a/Web/src/components/Budget/BudgetCard.vue b/Web/src/components/Budget/BudgetCard.vue index bd614dc..480c406 100644 --- a/Web/src/components/Budget/BudgetCard.vue +++ b/Web/src/components/Budget/BudgetCard.vue @@ -214,12 +214,14 @@ title="关联账单列表" height="75%" > - @@ -409,12 +411,14 @@ title="关联账单列表" height="75%" > - @@ -426,7 +430,7 @@ import { computed, ref } from 'vue' import { BudgetPeriodType } from '@/constants/enums' import PopupContainer from '@/components/PopupContainer.vue' -import TransactionList from '@/components/TransactionList.vue' +import BillListComponent from '@/components/Bill/BillListComponent.vue' import { getTransactionList } from '@/api/transactionRecord' const props = defineProps({ diff --git a/Web/src/components/ReasonGroupList.vue b/Web/src/components/ReasonGroupList.vue index 7878df9..496e1d8 100644 --- a/Web/src/components/ReasonGroupList.vue +++ b/Web/src/components/ReasonGroupList.vue @@ -1,4 +1,4 @@ - - - - - diff --git a/Web/src/views/AGENTS.md b/Web/src/views/AGENTS.md index eec5b31..c12477e 100644 --- a/Web/src/views/AGENTS.md +++ b/Web/src/views/AGENTS.md @@ -4,9 +4,11 @@ **Parent:** EmailBill/AGENTS.md ## OVERVIEW + Vue 3 views using Composition API with Vant UI components for mobile-first budget tracking. ## STRUCTURE + ``` Web/src/views/ ├── BudgetView.vue # Main budget management @@ -27,25 +29,36 @@ Web/src/views/ ``` ## WHERE TO LOOK -| Task | Location | Notes | -|------|----------|-------| -| Budget management | BudgetView.vue | Main budget interface | -| Transactions | TransactionsRecord.vue | CRUD operations | -| Statistics | StatisticsView.vue | Charts, analytics | -| Classification | Classification* | Transaction categorization | -| Authentication | LoginView.vue | User login flow | -| Settings | SettingView.vue | App configuration | -| Email features | EmailRecord.vue | Email integration | + +| Task | Location | Notes | +| ----------------- | ---------------------- | -------------------------- | +| Budget management | BudgetView.vue | Main budget interface | +| Transactions | TransactionsRecord.vue | CRUD operations | +| Statistics | StatisticsView.vue | Charts, analytics | +| Classification | Classification\* | Transaction categorization | +| Authentication | LoginView.vue | User login flow | +| Settings | SettingView.vue | App configuration | +| Email features | EmailRecord.vue | Email integration | ## CONVENTIONS -- Vue 3 Composition API with `