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") 會呈現一個按日期分組的簡單發票列表，並具有無限滾動機制以載入更多項目。

CustomerInvoiceListPage.tsx

import { PaymentProvider, CustomerInvoiceList } from '@blocklet/payment-react';

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

篩選發票

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

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