@blocklet/payment-react/docs/getting-started.zh.md

Reusable react components for payment kit v2

# 快速入门

本指南将引导您完成安装 `@blocklet/payment-react` 并将一个基础、功能齐全的支付表单集成到您的应用程序中的基本步骤。只需几分钟，您就可以拥有一个可用的结账体验。

## 第 1 步：安装

首先，使用 npm 或您偏好的包管理器将该库添加到您的项目中。

```bash Installation Command icon=lucide:terminal
npm install @blocklet/payment-react
```

## 第 2 步：设置 PaymentProvider

此库中的大多数组件都需要访问共享的支付上下文。`PaymentProvider` 组件提供了此上下文，并且必须放置在将处理支付的应用程序或组件树的根部。

它需要来自您应用程序身份验证上下文的 `session` 对象和 `connect` API 函数才能正常工作。

```tsx App.tsx icon=logos:react
import { PaymentProvider } from '@blocklet/payment-react';
// 这是您应用程序身份验证上下文钩子的占位符。
// 它应返回当前用户会话和一个 API 连接器。
import { useSessionContext } from './contexts/session'; 

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

  return (
    <PaymentProvider session={session} connect={connectApi}>
      {/* 您的支付组件将放在这里 */}
      {children}
    </PaymentProvider>
  );
}
```

> 有关设置会话上下文和高级 `PaymentProvider` 配置的详细信息，请参阅 [PaymentProvider 文档](./providers-payment-provider.md)。

## 第 3 步：添加 CheckoutForm

`CheckoutForm` 是用于呈现支付流程的主要组件。它可以处理一次性支付和通过支付链接发起的订阅。

要使用它，只需将其放置在 `PaymentProvider` 内部，并传递支付链接 (`plink_...`) 或结账会话 (`cs_...`) 所需的 `id`。

## 完整示例

这是一个结合了以上步骤的完整、最小化的示例。您可以使用此代码作为集成的起点。

```tsx PaymentPage.tsx icon=logos:react
import { PaymentProvider, CheckoutForm } from '@blocklet/payment-react';
// 这是您应用程序身份验证上下文钩子的占位符。
import { useSessionContext } from './contexts/session'; 

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

  // 支付链接 ID 是从您的 Payment Kit 仪表板生成的。
  const paymentLinkId = 'plink_xxx'; 

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <CheckoutForm 
        id={paymentLinkId}
        mode="inline" // 将表单直接嵌入到您的页面中
        showCheckoutSummary={true}
        onChange={(state) => console.log('Checkout State Changed:', state)}
        onPaid={(result) => console.log('Payment Successful:', result)}
      />
    </PaymentProvider>
  );
}

export default PaymentPage;
```

通过此设置，`CheckoutForm` 将呈现一个完整的支付 UI，处理用户输入，并无缝处理交易。

## 后续步骤

恭喜！您已成功集成您的第一个支付表单。现在，您可以开始探索更高级的功能和组件了。

- **[CheckoutForm](./components-checkout-checkout-form.md)**：深入了解 `CheckoutForm` 的 props 和自定义选项。
- **[Providers](./providers.md)**：了解更多关于支持该库的上下文提供程序的信息。
- **[Components](./components.md)**：发现可用的全系列 UI 和业务逻辑组件。