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

Reusable react components for payment kit v2

# CustomerInvoiceList

`CustomerInvoiceList` 元件旨在呈現客戶的發票歷史記錄。它會從支付服務中擷取並顯示發票資料，提供兩種不同的版面配置：一種是簡單的、按日期分組的無限滾動列表，另一種是詳細的、分頁的表格。此元件必須在 `PaymentProvider` 中使用才能正常運作。

## Props

| Prop | 類型 | 說明 | 預設值 |
| --- | --- | --- | --- |
| `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` | 在表格模式下，如果為 `true`，則顯示一個包含相關訂閱連結的欄位。 | `false` |

## 基本用法（列表視圖）

預設視圖 (`type="list"`) 會呈現一個按日期分組的簡單發票列表，並具有無限滾動機制以載入更多項目。

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

function InvoiceHistoryPage() {
  // 假設 customerId 可用，例如，來自會話或 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` prop 來新增一個直接連結到每張發票相關訂閱的欄位，這對於基於訂閱的服務非常有用。

## 篩選發票

您可以使用各種 props 來篩選顯示的發票。例如，若要僅顯示與質押相關的已付款發票：

```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` prop 設定為 `'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>
  );
}
```