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 模式（组件自动加载数据）

<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 模式（父组件管理数据）

<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: 多选模式

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