入門指南 | ArcBlock

本指南將引導您完成安裝 @blocklet/payment-react 並將一個基本的、功能齊全的支付表單整合到您的應用程式中的必要步驟。只需幾分鐘，您就能擁有一個可運作的結帳體驗。

步驟 1：安裝

首先，使用 npm 或您偏好的套件管理器將該函式庫新增至您的專案中。

Installation Command

npm install @blocklet/payment-react

步驟 2：設定 PaymentProvider

此函式庫中的大多數元件都需要存取共用的支付上下文。PaymentProvider 元件提供了這個上下文，並且必須放置在您的應用程式或將處理支付的元件樹的根部。

它需要來自您應用程式身份驗證上下文的 session 物件和 connect API 函式才能正常運作。

App.tsx

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 文件。

步驟 3：新增 CheckoutForm

CheckoutForm 是呈現支付流程的主要元件。它可以處理從支付連結發起的單次支付和訂閱。

要使用它，只需將其放置在 PaymentProvider 內部，並傳入支付連結（plink_...）或結帳會話（cs_...）所需的 id。

完整範例

這是一個結合了上述步驟的完整、最小化的範例。您可以使用此程式碼作為整合的起點。

PaymentPage.tsx

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：深入了解 CheckoutForm 的屬性和自訂選項。
Providers：了解更多關於支援此函式庫的上下文提供者。
Components：探索所有可用的 UI 和業務邏輯元件。