@blocklet/payment-react 1.20.16 → 1.20.18

package/docs/components-checkout-checkout-form.zh.md

@@ -0,0 +1,163 @@
+# CheckoutForm
+
+`CheckoutForm` 组件是处理支付链接和结账会话的主要入口点。它作为一个高级封装器，根据提供的 ID 获取所有必要数据，并渲染相应的支付或捐赠界面。此组件是将完整的结账流程集成到您的应用程序中的最简单方法。
+
+必须用 `PaymentProvider` 包裹 `CheckoutForm` 或其任何父组件，以确保它能访问必要的上下文，例如会话信息和 API 配置。更多详情，请参阅 [PaymentProvider 文档](./providers-payment-provider.md)。
+
+## 工作原理
+
+该组件协调整个结账流程：
+
+1.  **初始化**：它通过 `paymentLink` ID（前缀为 `plink_`）或 `checkoutSession` ID（前缀为 `cs_`）进行挂载。
+2.  **数据获取**：它与支付后端通信，以检索所有必要的上下文，包括支付方式、订单项和客户详细信息。
+3.  **UI 渲染**：根据 `formType` 属性，它在内部渲染标准的 `Payment` 组件或专门的 `DonationForm` 组件。
+4.  **状态管理**：它处理支付的整个生命周期，包括加载状态、完成状态和错误处理。
+
+```d2 CheckoutForm 的基本流程 icon=lucide:workflow
+direction: down
+shape: sequence_diagram
+
+User-Action: {
+  shape: c4-person
+  label: "用户"
+}
+
+Application: {
+  label: "你的 React 应用"
+
+  CheckoutForm-Component: {
+    label: "CheckoutForm"
+  }
+
+  Payment-Component: {
+    label: "Payment 组件"
+  }
+
+  Donation-Component: {
+    label: "DonationForm 组件"
+  }
+}
+
+Payment-API: {
+  label: "支付后端 API"
+  shape: cylinder
+}
+
+User-Action -> Application.CheckoutForm-Component: "1. 使用 'id' 属性挂载"
+Application.CheckoutForm-Component -> Payment-API: "2. 获取会话数据"
+Payment-API -> Application.CheckoutForm-Component: "3. 返回结账上下文"
+
+alt "如果 formType 是 'payment'" {
+  Application.CheckoutForm-Component -> Application.Payment-Component: "4. 渲染支付 UI"
+}
+
+alt "如果 formType 是 'donation'" {
+  Application.CheckoutForm-Component -> Application.Donation-Component: "5. 渲染捐赠 UI"
+}
+
+User-Action -> Application.Payment-Component: "6. 完成支付"
+User-Action -> Application.Donation-Component: "7. 完成捐赠"
+
+```
+
+## 属性
+
+`CheckoutForm` 组件接受以下属性：
+
+| 属性          | 类型                                                                       | 必填 | 默认值       | 描述                                                                                             |
+|---------------|----------------------------------------------------------------------------|----------|---------------|-------------------------------------------------------------------------------------------------------------------------|
+| `id`          | `string`                                                                   | 是      | -             | 支付链接（`plink_...`）或结账会话（`cs_...`）的唯一标识符。                                |
+| `mode`        | `'standalone'` \| `'inline'` \| `'popup'` \| `'inline-minimal'` \| `'popup-minimal'` | 否       | `'inline'`    | 定义渲染模式。`'standalone'` 用于全页视图，`'inline'` 用于嵌入容器。                  |
+| `formType`    | `'payment'` \| `'donation'`                                                 | 否       | `'payment'`   | 决定要渲染的表单类型。使用 `'donation'` 以实现专门的捐赠流程。                          |
+| `onPaid`      | `(res: CheckoutContext) => void`                                           | 否       | -             | 支付成功后执行的回调函数。接收最终的结账上下文作为参数。               |
+| `onError`     | `(err: Error) => void`                                                     | 否       | `console.error` | 在流程中发生错误时执行的回调函数。                                                   |
+| `onChange`    | `(data: CheckoutFormData) => void`                                         | 否       | -             | 当任何表单字段值发生变化时触发的回调函数。                                                         |
+| `goBack`      | `() => void`                                                               | 否       | -             | 如果提供，则渲染一个返回按钮，并在点击时调用此函数。                                                |
+| `extraParams` | `Record<string, any>`                                                      | 否       | `{}`          | 从支付链接启动会话时，在 URL 中传递的额外参数对象。                  |
+| `theme`       | `'default'` \| `'inherit'` \| `PaymentThemeOptions`                            | 否       | `'default'`   | 控制组件的主题。`'inherit'` 使用父主题，或者您可以传递一个自定义主题对象。             |
+| `action`      | `string`                                                                   | 否       | `''`          | 一个字符串标识符，用于自定义 UI 元素（如按钮文本）或跟踪特定流程。                   |
+
+## 用法
+
+### 基本内联支付表单
+
+这是将支付表单直接嵌入到您的应用程序 UI 中的最常见用例。该组件在内部处理所有逻辑。
+
+```tsx MyStorePage.tsx icon=lucide:shopping-cart
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/session-context'; // 您的应用的会话钩子
+
+export default function MyStorePage() {
+  const { session, connectApi } = useSessionContext();
+
+  const handlePaymentSuccess = (result) => {
+    console.log('支付成功！', result);
+    alert('感谢您的购买！');
+  };
+
+  const handlePaymentError = (error) => {
+    console.error('支付失败：', error);
+    alert('抱歉，您的支付无法处理。');
+  };
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <div style={{ maxWidth: '960px', margin: '0 auto' }}>
+        <h1>结账</h1>
+        <CheckoutForm
+          id="plink_xxxxxxxxxxxxxx" // 替换为您的支付链接 ID
+          mode="inline"
+          onPaid={handlePaymentSuccess}
+          onError={handlePaymentError}
+        />
+      </div>
+    </PaymentProvider>
+  );
+}
+```
+
+### 独立全页结账
+
+使用 `mode="standalone"` 来渲染一个专用的全页结账体验。这对于将用户重定向到单独页面以完成支付的场景非常理想。
+
+```tsx CheckoutPage.tsx icon=lucide:layout-template
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/session-context';
+
+export default function CheckoutPage() {
+  const { session, connectApi } = useSessionContext();
+  const paymentLinkId = 'plink_xxxxxxxxxxxxxx'; // 可从 URL 参数中检索
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <CheckoutForm id={paymentLinkId} mode="standalone" />
+    </PaymentProvider>
+  );
+}
+```
+
+### 捐赠表单
+
+通过设置 `formType="donation"`，该组件会渲染一个专为捐赠活动量身定制的 UI，包括金额预设和权益显示等功能。
+
+```tsx DonationPage.tsx icon=lucide:gift
+import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
+import { useSessionContext } from './hooks/session-context';
+
+export default function DonationPage() {
+  const { session, connectApi } = useSessionContext();
+
+  return (
+    <PaymentProvider session={session} connectApi={connectApi}>
+      <div style={{ padding: '2rem' }}>
+        <h2>支持我们的事业</h2>
+        <CheckoutForm
+          id="plink_yyyyyyyyyyyyyy" // 替换为您的捐赠链接 ID
+          formType="donation"
+          onPaid={() => alert('感谢您的慷慨捐赠！')}
+        />
+      </div>
+    </PaymentProvider>
+  );
+}
+```

package/docs/components-checkout-checkout-table.ja.md

@@ -0,0 +1,148 @@
+# CheckoutTable
+
+`CheckoutTable`コンポーネントは、サブスクリプションのチェックアウトのための、すぐに使える完全なソリューションを提供します。価格表を取得してレンダリングし、ユーザーがプランを選択できるようにし、その後シームレスに支払いフォームに移行して購入を完了させます。この高レベルコンポーネントは、プランベースの支払いフローをアプリケーションに統合する最も速い方法です。
+
+内部では、プランを表示するために[`PricingTable`](./components-ui-pricing-table.md)コンポーネントを使用し、支払いを処理するために[`CheckoutForm`](./components-checkout-checkout-form.md)コンポーネントを使用しています。
+
+## 仕組み
+
+`CheckoutTable`によって管理されるチェックアウトフローは単純です。
+
+1.  **データの取得**: コンポーネントは、提供された`id`を使用してサーバーから価格表の設定を取得します。
+2.  **プランの表示**: サブスクリプションプランをレスポンシブなテーブルでレンダリングし、ユーザーが請求期間（例：月次/年次）や通貨を切り替えられるようにします。
+3.  **セッションの作成**: ユーザーがプランを選択すると、コンポーネントはバックエンドと通信して安全なチェックアウトセッションを作成します。
+4.  **支払いの処理**: その後、セッション詳細が事前に入力された`CheckoutForm`を表示し、ユーザーが支払い情報を入力して取引を完了できるようにします。
+
+```d2 CheckoutTable フロー図
+direction: down
+
+ユーザー: {
+  shape: c4-person
+}
+
+CheckoutTable-Component: {
+  label: "CheckoutTable コンポーネント"
+  shape: rectangle
+
+  Pricing-Table-View: {
+    label: "価格表ビュー"
+  }
+
+  Checkout-Form-View: {
+    label: "チェックアウトフォームビュー"
+  }
+}
+
+Payment-API: {
+  label: "支払いAPI"
+  shape: cylinder
+}
+
+ユーザー -> CheckoutTable-Component.Pricing-Table-View: "1. プランを閲覧"
+CheckoutTable-Component.Pricing-Table-View -> ユーザー: " "
+ユーザー -> CheckoutTable-Component.Pricing-Table-View: "2. プランを選択"
+CheckoutTable-Component.Pricing-Table-View -> Payment-API: "3. チェックアウトセッションを作成"
+Payment-API -> CheckoutTable-Component.Pricing-Table-View: "4. セッションIDを返す"
+CheckoutTable-Component.Pricing-Table-View -> CheckoutTable-Component.Checkout-Form-View: "5. セッションIDで移行"
+ユーザー -> CheckoutTable-Component.Checkout-Form-View: "6. 支払い詳細を入力して支払う"
+CheckoutTable-Component.Checkout-Form-View -> ユーザー: ""
+
+```
+
+## 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)にレンダリングします。

package/docs/components-checkout-checkout-table.zh-TW.md

@@ -0,0 +1,148 @@
+# CheckoutTable
+
+`CheckoutTable` 元件為訂閱結帳提供了一個完整、開箱即用的解決方案。它會獲取並呈現價格表，允許使用者選擇方案，然後無縫地將他們轉換到付款表單以完成購買。這個高階元件是將基於方案的付款流程整合到您的應用程式中最快的方法。
+
+它在內部使用 [`PricingTable`](./components-ui-pricing-table.md) 元件來顯示方案，並使用 [`CheckoutForm`](./components-checkout-checkout-form.md) 元件來處理付款。
+
+## 運作方式
+
+`CheckoutTable` 管理的結帳流程非常直接：
+
+1.  **獲取資料**：該元件使用提供的 `id` 從伺服器獲取價格表設定。
+2.  **顯示方案**：它在一個響應式表格中呈現訂閱方案，允許使用者在計費週期（例如，每月/每年）和貨幣之間切換。
+3.  **建立會話**：當使用者選擇一個方案時，該元件會與後端通訊以建立一個安全的結帳會話。
+4.  **處理付款**：然後它會顯示 `CheckoutForm`，預先填入會話詳細資訊，讓使用者輸入他們的付款資訊並完成交易。
+
+```d2 CheckoutTable 流程圖
+direction: down
+
+使用者: {
+  shape: c4-person
+}
+
+CheckoutTable-Component: {
+  label: "CheckoutTable 元件"
+  shape: rectangle
+
+  Pricing-Table-View: {
+    label: "價格表視圖"
+  }
+
+  Checkout-Form-View: {
+    label: "結帳表單視圖"
+  }
+}
+
+Payment-API: {
+  label: "付款 API"
+  shape: cylinder
+}
+
+使用者 -> CheckoutTable-Component.Pricing-Table-View: "1. 查看方案"
+CheckoutTable-Component.Pricing-Table-View -> 使用者: " "
+使用者 -> CheckoutTable-Component.Pricing-Table-View: "2. 選擇方案"
+CheckoutTable-Component.Pricing-Table-View -> Payment-API: "3. 建立結帳會話"
+Payment-API -> CheckoutTable-Component.Pricing-Table-View: "4. 返回會話 ID"
+CheckoutTable-Component.Pricing-Table-View -> CheckoutTable-Component.Checkout-Form-View: "5. 透過會話 ID 轉換"
+使用者 -> CheckoutTable-Component.Checkout-Form-View: "6. 填寫付款詳細資訊並付款"
+CheckoutTable-Component.Checkout-Form-View -> 使用者: ""
+
+```
+
+## 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) 中呈現。

package/docs/components-checkout-checkout-table.zh.md

@@ -0,0 +1,149 @@
+# CheckoutTable
+
+`CheckoutTable` 组件为订阅结账提供了一个完整的、开箱即用的解决方案。它会获取并渲染一个价格表，允许用户选择一个方案，然后无缝地将他们过渡到支付表单以完成购买。这个高级组件是将基于方案的支付流程集成到您的应用程序中的最快方法。
+
+它在内部使用 [`PricingTable`](./components-ui-pricing-table.md) 组件来显示方案，并使用 [`CheckoutForm`](./components-checkout-checkout-form.md) 组件来处理支付。
+
+## 工作原理
+
+`CheckoutTable` 管理的结账流程非常直接：
+
+1.  **获取数据**：该组件使用提供的 `id` 从服务器获取价格表配置。
+2.  **显示方案**：它在一个响应式表格中渲染订阅方案，允许用户在计费周期（例如，月度/年度）和货币之间切换。
+3.  **创建会话**：当用户选择一个方案时，该组件会与后端通信以创建一个安全的结账会话。
+4.  **处理支付**：然后它会显示 `CheckoutForm`，预先填充了会话详细信息，允许用户输入他们的支付信息并完成交易。
+
+```d2 CheckoutTable 流程图
+direction: down
+
+User: {
+  shape: c4-person
+  label: "用户"
+}
+
+CheckoutTable-Component: {
+  label: "CheckoutTable 组件"
+  shape: rectangle
+
+  Pricing-Table-View: {
+    label: "价格表视图"
+  }
+
+  Checkout-Form-View: {
+    label: "结账表单视图"
+  }
+}
+
+Payment-API: {
+  label: "支付 API"
+  shape: cylinder
+}
+
+User -> CheckoutTable-Component.Pricing-Table-View: "1. 查看方案"
+CheckoutTable-Component.Pricing-Table-View -> User: " "
+User -> CheckoutTable-Component.Pricing-Table-View: "2. 选择方案"
+CheckoutTable-Component.Pricing-Table-View -> Payment-API: "3. 创建结账会话"
+Payment-API -> CheckoutTable-Component.Pricing-Table-View: "4. 返回会话 ID"
+CheckoutTable-Component.Pricing-Table-View -> CheckoutTable-Component.Checkout-Form-View: "5. 使用会话 ID 进行过渡"
+User -> CheckoutTable-Component.Checkout-Form-View: "6. 填写支付详情并支付"
+CheckoutTable-Component.Checkout-Form-View -> User: ""
+
+```
+
+## 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` 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) 中渲染。