@blocklet/payment-react/docs/components-checkout-checkout-table.zh-TW.md

Reusable react components for payment kit v2

# CheckoutTable

`CheckoutTable` 元件為訂閱結帳提供了一個完整、開箱即用的解決方案。它會獲取並呈現價格表，允許使用者選擇方案，然後無縫地將他們轉換到付款表單以完成購買。這個高階元件是將基於方案的付款流程整合到您的應用程式中最快的方法。

它在內部使用 [`PricingTable`](./components-ui-pricing-table.md) 元件來顯示方案，並使用 [`CheckoutForm`](./components-checkout-checkout-form.md) 元件來處理付款。

## 運作方式

`CheckoutTable` 管理的結帳流程非常直接：

1.  **獲取資料**：該元件使用提供的 `id` 從伺服器獲取價格表設定。
2.  **顯示方案**：它在一個響應式表格中呈現訂閱方案，允許使用者在計費週期（例如，每月/每年）和貨幣之間切換。
3.  **建立會話**：當使用者選擇一個方案時，該元件會與後端通訊以建立一個安全的結帳會話。
4.  **處理付款**：然後它會顯示 `CheckoutForm`，預先填入會話詳細資訊，讓使用者輸入他們的付款資訊並完成交易。

<!-- DIAGRAM_IMAGE_START:flowchart:4:3::1765377358 -->
![CheckoutTable](assets/diagram/components-checkout-checkout-table-01.zh-TW.jpg)
<!-- DIAGRAM_IMAGE_END -->

## Props

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `id` | `string` | 是 | - | 要顯示的價格表的 ID（必須以 `prctbl_` 開頭）。 |
| `mode` | `'standalone'` 或 `'embedded'` | 否 | `'embedded'` | 顯示模式。`'standalone'` 會重新導向到一個獨立的頁面，而 `'embedded'` 會在元件內處理流程。 |
| `onPaid` | `(sessionId: string) => void` | 否 | - | 付款成功完成時觸發的回呼函式。 |
| `onError` | `(error: Error) => void` | 否 | - | 用於處理結帳過程中錯誤的回呼函式。 |
| `onChange` | `(data: any) => void` | 否 | - | 結帳表單內任何狀態變更的回呼。 |
| `extraParams` | `Record<string, any>` | 否 | `{}` | 建立結帳會話時要傳送的額外參數物件，可用於傳遞自訂資料，例如使用者 ID。 |
| `goBack` | `() => void` | 否 | - | 一個用於處理從付款表單返回動作的函式，將使用者返回到價格表視圖。 |
| `theme` | `object` 或 `'inherit'` | 否 | - | 自訂 Material-UI 主題物件，用於設定元件樣式。更多詳細資訊，請參閱 [主題指南](./guides-theming.md)。 |

## 使用方式

要使用 `CheckoutTable` 元件，您必須將其包裹在 `PaymentProvider` 中。傳入價格表的 `id` 和一個 `onPaid` 回呼函式來處理成功的交易。

```javascript Basic CheckoutTable Example icon=logos:react
import { PaymentProvider, CheckoutTable } from '@blocklet/payment-react';
import { useSessionContext } from './path-to-your-session-context'; // 根據指南集中管理此上下文

export default function MyCheckoutPage() {
  const { session, connectApi } = useSessionContext();

  const handlePaymentSuccess = (sessionId) => {
    console.log(`付款成功，會話： ${sessionId}`);
    alert('感謝您的訂閱！');
  };

  if (!session) {
    return <div>正在載入會話...</div>;
  }

  return (
    <PaymentProvider session={session} connectApi={connectApi}>
      <div style={{ height: '700px', width: '100%' }}>
        <CheckoutTable
          id="prctbl_xxxxxxxxxxxxxxxx" // 請替換為您實際的價格表 ID
          onPaid={handlePaymentSuccess}
        />
      </div>
    </PaymentProvider>
  );
}
```

## 操作模式

### 嵌入模式（預設）

預設情況下，`CheckoutTable` 在 `'embedded'` 模式下運作。該元件在其自己的容器內管理整個流程，從價格表視圖轉換到付款表單。這對於希望結帳過程感覺像是頁面整合一部分的單頁應用程式來說非常理想。

### 獨立模式

透過設定 `mode='standalone'`，元件的行為會改變。當使用者選擇一個方案時，他們會被重新導向到一個專用的託管結帳頁面。這種模式對於不需要嵌入式付款表單的簡單整合非常有用。

```javascript Standalone Mode icon=logos:react
<CheckoutTable
  id="prctbl_xxxxxxxxxxxxxxxx"
  mode="standalone"
/>
```

## 進階用法

### 處理返回導航

`goBack` prop 允許您定義當使用者從付款表單導航回價格表時的自訂邏輯。元件會自動處理視圖轉換，但這個回呼對於同步您的應用程式狀態非常有用。

```javascript goBack Prop Example icon=logos:react
const handleGoBack = () => {
  console.log('使用者已返回價格表。');
  // 您可以在此處新增自訂邏輯，例如更新您的應用程式狀態。
};

<CheckoutTable
  id="prctbl_xxxxxxxxxxxxxxxx"
  onPaid={handlePaymentSuccess}
  goBack={handleGoBack}
/>
```

### 傳遞額外參數

使用 `extraParams` prop 在建立結帳會話時傳送額外資料。這些資料可以與最終的付款相關聯，對於在您的後端進行追蹤和對帳非常有用。

```javascript extraParams Example icon=logos:react
<CheckoutTable
  id="prctbl_xxxxxxxxxxxxxxxx"
  onPaid={handlePaymentSuccess}
  extraParams={{ userId: 'user_123', source: 'marketing_campaign' }}
/>
```

## 自訂

雖然 `CheckoutTable` 是一個為易用性而設計的高階元件，但您可以透過使用其組成部分來實現更精細的控制。對於完全自訂的 UI，您可以使用 [`PricingTable`](./components-ui-pricing-table.md) 元件來顯示方案，然後手動觸發一個結帳會話，並在 [`CheckoutForm`](./components-checkout-checkout-form.md) 中呈現。