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") 会渲染一个按日期分组的简单发票列表，并带有无限滚动机制来加载更多项目。

CustomerInvoiceListPage.tsx

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"。此模式会在一个带有可排序列的分页表格中显示发票。

CustomerInvoiceTablePage.tsx

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 属性来添加一列，该列直接链接到与每张发票关联的订阅，这对于基于订阅的服务非常有用。

筛选发票

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

FilteredInvoiceListPage.tsx

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 实例来启动支付流程。

PayableInvoiceListPage.tsx

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>
  );
}