@blocklet/payment-react/docs/components-history-invoice-list.zh.md

Reusable react components for payment kit v2

# CustomerInvoiceList

`CustomerInvoiceList` 组件用于渲染客户的发票历史记录。它会从支付服务中获取并显示发票数据，并提供两种不同的布局：一种是按日期分组的简单列表，支持无限滚动；另一种是详细的分页表格。此组件必须在 `PaymentProvider` 内部使用才能正常工作。

## Props

| Prop | Type | Description | Default |
| --- | --- | --- | --- |
| `customer_id` | `string` | 要显示其发票的客户 ID。 | `''` |
| `subscription_id` | `string` | 按特定订阅 ID 筛选发票。 | `''` |
| `currency_id` | `string` | 按特定货币 ID 筛选发票。 | `''` |
| `include_staking` | `boolean` | 如果为 `true`，则在列表中包含与质押相关的发票。 | `false` |
| `include_return_staking` | `boolean` | 如果为 `true`，则包含返还质押的发票。 | `false` |
| `include_recovered_from` | `boolean` | 如果为 `true`，则包含从先前余额中恢复的发票。 | `false` |
| `status` | `string` | 一个逗号分隔的发票状态字符串，用于显示（例如，`'open,paid,uncollectible'`）。 | `'open,paid,uncollectible'` |
| `pageSize` | `number` | 每页要获取的发票数量。 | `10` |
| `target` | `string` | 发票链接的目标属性（例如，`'_self'`，`'_blank'`）。 | `'_self'` |
| `action` | `string` | 为某些发票定义一个行动号召。设置为 `'pay'` 以显示待支付发票的支付按钮。 | `''` |
| `type` | `'list' \| 'table'` | 发票列表的显示模式。 | `'list'` |
| `onTableDataChange` | `Function` | 当发票数据更改时触发的回调函数。 | `() => {}` |
| `relatedSubscription` | `boolean` | 在 `table` 模式下，如果为 `true`，则显示一个包含相关订阅链接的列。 | `false` |

## 基本用法（列表视图）

默认视图 (`type="list"`) 会渲染一个按日期分组的简单发票列表，并带有无限滚动机制来加载更多项目。

```tsx CustomerInvoiceListPage.tsx icon=logos:react
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function InvoiceHistoryPage() {
  // 假设 customerId 可用，例如，从 session 或 props 中获取
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList customer_id={customerId} />
    </PaymentProvider>
  );
}
```

## 表格视图

若要获得更详细、结构化的展示，您可以设置 `type="table"`。此模式会在一个带有可排序列的分页表格中显示发票。

```tsx CustomerInvoiceTablePage.tsx icon=logos:react
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function InvoiceHistoryTable() {
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList
        customer_id={customerId}
        type="table"
        relatedSubscription={true} // 显示相关订阅的列
        pageSize={5}
      />
    </PaymentProvider>
  );
}
```

在此示例中，启用了 `relatedSubscription` 属性来添加一列，该列直接链接到与每张发票关联的订阅，这对于基于订阅的服务非常有用。

## 筛选发票

您可以使用各种属性来筛选所显示的发票。例如，要仅显示与质押相关的已支付发票：

```tsx FilteredInvoiceListPage.tsx icon=logos:react
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function FilteredInvoiceList() {
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList
        customer_id={customerId}
        type="table"
        status="paid" // 仅显示已支付的发票
        include_staking={true} // 同时包括质押交易
      />
    </PaymentProvider>
  );
}
```

## 为待支付发票启用支付功能

通过将 `action` 属性设置为 `'pay'`，您可以为任何状态为 `open` 或 `uncollectible` 的发票添加一个“支付”按钮。点击此按钮将使用 `PaymentProvider` 中的 `connect` 实例来启动支付流程。

```tsx PayableInvoiceListPage.tsx icon=logos:react
import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

function PayableInvoiceList() {
  const customerId = 'cus_xxxxxxxxxxxxxx';

  return (
    <PaymentProvider>
      <CustomerInvoiceList
        customer_id={customerId}
        status="open,uncollectible" // 仅显示需要支付的发票
        action="pay" // 添加“支付”按钮
      />
    </PaymentProvider>
  );
}
```