@blocklet/payment-react/docs/components-checkout-checkout-table.ja.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.ja.jpg)
<!-- DIAGRAM_IMAGE_END -->

## Props

| Prop          | Type                              | Required | Default      | Description                                                                                                                              |
|---------------|-----------------------------------|----------|--------------|------------------------------------------------------------------------------------------------------------------------------------------|
| `id`          | `string`                          | はい      | -            | 表示する価格表のID（`prctbl_`で始まる必要があります）。                                                                      |
| `mode`        | `'standalone'` or `'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` or `'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`プロパティを使用すると、ユーザーが支払いフォームから価格表に戻る際のカスタムロジックを定義できます。コンポーネントはビューの遷移を自動的に処理しますが、このコールバックはアプリケーションの状態を同期させるのに役立ちます。

```javascript goBack Prop Example icon=logos:react
const handleGoBack = () => {
  console.log('ユーザーが価格表に戻りました。');
  // ここにアプリの状態を更新するなどのカスタムロジックを追加できます。
};

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

### 追加パラメータの受け渡し

`extraParams`プロパティを使用して、チェックアウトセッションを作成する際に追加データを送信します。このデータは結果の支払いに関連付けることができ、バックエンドでの追跡や照合に役立ちます。

```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)にレンダリングします。