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

Reusable react components for payment kit v2

# CustomerInvoiceList

`CustomerInvoiceList` コンポーネントは、顧客の請求履歴をレンダリングするために設計されています。支払いサービスから請求書データを取得して表示し、2つの異なるレイアウトを提供します：無限スクロールを備えた日付でグループ化されたシンプルなリストと、詳細なページ分割テーブルです。このコンポーネントが正しく機能するためには、`PaymentProvider` 内で使用する必要があります。

## プロパティ

| プロパティ | 型 | 説明 | デフォルト |
| --- | --- | --- | --- |
| `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` | 1ページあたりに取得する請求書の数。 | `10` |
| `target` | `string` | 請求書リンクの `target` 属性（例：`'_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が利用可能であると仮定します（例：セッションまたは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>
  );
}
```