@blocklet/payment-react/docs/components-checkout-checkout-table.zh.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`，预先填充了会话详细信息，允许用户输入他们的支付信息并完成交易。

```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) 中渲染。