EmailBill/.doc/BillListComponent-usage.md

# 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
<template>
  <BillListComponent
    data-source="api"
    :api-params="{ type: 0, dateRange: ['2026-01-01', '2026-01-31'] }"
    :show-delete="true"
    :enable-filter="true"
    @click="handleBillClick"
    @delete="handleBillDelete"
  />
</template>

<script setup>
import BillListComponent from '@/components/Bill/BillListComponent.vue'

const handleBillClick = (transaction) => {
  console.log('点击账单:', transaction)
  // 打开详情弹窗等
}

const handleBillDelete = (id) => {
  console.log('删除账单:', id)
  // 刷新统计数据等
}
</script>
```

### 示例 2: Custom 模式（父组件管理数据）

```vue
<template>
  <BillListComponent
    data-source="custom"
    :transactions="billList"
    :loading="loading"
    :finished="finished"
    :show-delete="true"
    :enable-filter="false"
    @load="loadMore"
    @click="viewDetail"
    @delete="handleDelete"
  />
</template>

<script setup>
import { ref } from 'vue'
import BillListComponent from '@/components/Bill/BillListComponent.vue'
import { getTransactionList } from '@/api/transactionRecord'

const billList = ref([])
const loading = ref(false)
const finished = ref(false)

const loadMore = async () => {
  loading.value = true
  const response = await getTransactionList({ pageIndex: 1, pageSize: 20 })
  if (response.success) {
    billList.value = response.data
    finished.value = true
  }
  loading.value = false
}

const viewDetail = (transaction) => {
  // 查看详情
}

const handleDelete = (id) => {
  billList.value = billList.value.filter(t => t.id !== id)
}
</script>
```

### 示例 3: 多选模式

```vue
<template>
  <BillListComponent
    data-source="custom"
    :transactions="billList"
    :show-checkbox="true"
    :selected-ids="selectedIds"
    :show-delete="false"
    :enable-filter="false"
    @update:selected-ids="selectedIds = $event"
  />
  
  <div v-if="selectedIds.size > 0">
    已选中 {{ selectedIds.size }} 条
    <van-button @click="batchDelete">批量删除</van-button>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import BillListComponent from '@/components/Bill/BillListComponent.vue'

const billList = ref([...])
const selectedIds = ref(new Set())

const batchDelete = () => {
  // 批量删除逻辑
}
</script>
```

---

## 注意事项

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），暂时保留