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

Reusable react components for payment kit v2

# CreditGrantsList

`CreditGrantsList` 元件會渲染一個分頁表格，用來顯示客戶的信用額度授予。它清晰地概覽了每筆授予的狀態、剩餘額度、適用範圍和有效期限。

這個元件對於客戶端入口網站（使用者可在此追蹤其可用信用額度）和管理員儀表板（用於管理客戶的授予）都至關重要。它必須在 `PaymentProvider` 中使用，才能存取必要的會話和 API 上下文。

## 屬性

| 屬性 | 類型 | 說明 | 預設值 |
| --- | --- | --- | --- |
| `customer_id` | `string` | 可選。客戶的 ID。如果省略，則預設為目前已驗證使用者的 DID（來自會話上下文）。 | `session.user.did` |
| `subscription_id` | `string` | 可選。篩選列表，僅顯示與特定訂閱相關的授予。 | `''` |
| `status` | `string` | 可選。用逗號分隔的狀態字串，用於篩選。有效的狀態包括 `granted`、`pending`、`expired`、`depleted` 和 `voided`。 | `'granted,pending,depleted,expired'` |
| `pageSize` | `number` | 可選。每頁顯示的項目數量。 | `10` |
| `onTableDataChange` | `(data, prevData) => void` | 可選。一個回呼函式，每當表格資料被擷取或更新時都會被呼叫。 | `() => {}` |
| `mode` | `'dashboard' \| 'portal'` | 可選。決定點擊某一行時的導航行為。為客戶端視圖使用 `'portal'`，為管理員面板使用 `'dashboard'`，這會產生不同的連結路徑。 | `'portal'` |

## 使用方式

### 基本用法（適用於已登入的客戶）

預設情況下，`CreditGrantsList` 元件會擷取並顯示目前已驗證使用者的信用額度授予。這是客戶帳戶頁面最常見的使用情境。

```jsx 我的信用額度授予 icon=logos:react
import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from '/path/to/your/session/context'; // 調整此導入路徑

function MyCreditGrantsPage() {
  const { session, connectApi } = useSessionContext();

  if (!session || !connectApi) {
    return <div>載入會話中...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <h2>我的信用額度授予</h2>
      <CreditGrantsList />
    </PaymentProvider>
  );
}
```

### 管理員或儀表板用法

在管理儀表板中，您可以透過提供 `customer_id` 屬性來顯示任何客戶的信用額度授予。您也可以自訂篩選器和頁面大小。

```jsx 客戶信用額度授予 icon=logos:react
import { CreditGrantsList, PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from '/path/to/your/session/context'; // 調整此導入路徑

function CustomerDetailsPage({ customerId }) {
  const { session, connectApi } = useSessionContext();

  if (!session || !connectApi) {
    return <div>載入會話中...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <h3>客戶的有效信用額度授予</h3>
      <CreditGrantsList
        customer_id={customerId}
        status="granted,pending"
        pageSize={5}
        mode="dashboard"
      />
    </PaymentProvider>
  );
}
```

此範例展示了如何僅列出特定客戶的「granted」和「pending」授予，每頁顯示 5 個項目。`mode="dashboard"` 確保點擊某個授予後會導航至管理員專用的 URL。