@blocklet/payment-react/docs/getting-started.zh-TW.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` 將呈現一個完整的支付使用者介面，處理使用者輸入，並無縫地處理交易。

## 後續步驟

恭喜！您已成功整合您的第一個支付表單。現在您可以開始探索更多進階功能和元件。

- **[CheckoutForm](./components-checkout-checkout-form.md)**：深入了解 `CheckoutForm` 的屬性和自訂選項。
- **[Providers](./providers.md)**：了解更多關於支援此函式庫的上下文提供者。
- **[Components](./components.md)**：探索所有可用的 UI 和業務邏輯元件。