PaymentProvider | ArcBlock

PaymentProvider 是 @blocklet/payment-react 函式庫的基石。它作為一個上下文提供者，必須包裝您的應用程式或相關的支付元件。它負責取得必要的設定、管理應用程式狀態，並為其所有子元件提供輔助函式和 API 客戶端。

此函式庫中幾乎每個元件和掛鉤都需要嵌套在 PaymentProvider 內才能正常運作。

運作方式

該提供者在掛載時會初始化並從 Payment Kit 後端取得設定資料。這些資料，連同使用者的 session 和其他工具，會透過 usePaymentContext 掛鉤提供給任何後代元件。這種模式確保您的支付元件始終能夠存取必要的上下文，而無需透過屬性傳遞。

PaymentProvider

設定與使用

若要使用 PaymentProvider，您需要從應用程式的驗證上下文中為其提供 session 和 connect 物件。在整個文件中，我們將使用一個自訂掛鉤 useSessionContext 來代表您應用程式的驗證邏輯。以下是此類掛鉤的典型實作：

SessionContext.tsx

import React, { createContext, useContext } from 'react';
import { SessionProvider, useSessionContext as useDidSessionContext } from '@arcblock/did-connect-react';

// 您可以建立自己的上下文或使用現有的上下文
const AppContext = createContext({});

export function AppProvider({ children }) {
  return (
    <SessionProvider>
      <AppContext.Provider value={{}}>
        {children}
      </AppContext.Provider>
    </SessionProvider>
  );
}

// 這個自訂掛鉤為 PaymentProvider 提供 session 和 connectApi
export function useSessionContext() {
  const { session, connect } = useDidSessionContext();
  return { session, connectApi: connect };
}

一旦您的 session 管理就緒，就用 PaymentProvider 包裝您的主應用程式元件。

App.tsx

import { PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from './SessionContext'; // 您的 session 上下文掛鉤
import MyPaymentPage from './MyPaymentPage';

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

  return (
    <PaymentProvider session={session} connect={connectApi}>
      <MyPaymentPage />
    </PaymentProvider>
  );
}

export default App;

Props

PaymentProvider 元件接受以下 props：

Prop	Type	Required	Description
`session`	`Session`	是	來自您的驗證上下文的使用者 session 物件 (例如 `@arcblock/did-connect-react`)。
`connect`	`Connect`	是	來自您的驗證上下文的 `connect` API 函式，用於 DID Connect 操作。
`children`	`React.ReactNode`	是	將有權存取支付上下文的子元件。
`baseUrl`	`string`	否	Payment Kit blocklet 的基礎 URL。僅在從不同來源 (跨來源) 整合支付元件時才需要。
`authToken`	`string`	否	用於 API 請求的特定驗證令牌。如果提供，它將取代基於 session 的驗證。

上下文值

PaymentProvider 內的元件可以使用 usePaymentContext 掛鉤存取以下值。

MyComponent.tsx

import { usePaymentContext } from '@blocklet/payment-react';

function MyComponent() {
  const { settings, livemode, setLivemode } = usePaymentContext();

  return (
    <div>
      <p>基礎貨幣： {settings.baseCurrency?.name}</p>
      <p>模式： {livemode ? '正式' : '測試'}</p>
      <button onClick={() => setLivemode(!livemode)}>切換模式</button>
    </div>
  );
}

以下是可用上下文值的完整列表：

Key	Type	Description
`session`	`object`	經過驗證的使用者 session，包含使用者詳細資訊。
`connect`	`function`	用於啟動 DID Wallet 互動的 `connect` 函式。
`livemode`	`boolean`	表示上下文是處於正式 (`true`) 模式還是測試 (`false`) 模式。
`setLivemode`	`(livemode: boolean) => void`	一個在正式和測試模式之間切換的函式。這將觸發重新取得設定。
`settings`	`Settings`	一個包含從後端取得的 `paymentMethods` 和 `baseCurrency` 設定的物件。
`refresh`	`(forceRefresh?: boolean) => void`	一個手動觸發重新取得設定資料的函式。
`getCurrency`	`(id: string) => TPaymentCurrency`	一個輔助函式，可透過 ID 取得特定貨幣的詳細資訊。
`getMethod`	`(id: string) => TPaymentMethodExpanded`	一個輔助函式，可透過 ID 取得特定支付方式的詳細資訊。
`api`	`AxiosInstance`	一個預先設定的 Axios 實例，用於向 Payment Kit 後端發出經過驗證的 API 呼叫。
`prefix`	`string`	blocklet 的 URL 前綴。
`payable`	`boolean`	一個可用於控制支付操作可用性的狀態。
`setPayable`	`(status: boolean) => void`	一個更新 `payable` 狀態的函式。

進階情境

跨來源整合

如果您的應用程式和 Payment Kit blocklet 託管在不同的網域上，您必須使用 baseUrl prop。這讓 PaymentProvider 能夠正確地定位並與 Payment Kit API 通訊。

CrossOriginApp.tsx

import { PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from './SessionContext';

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

  return (
    <PaymentProvider
      session={session}
      connect={connectApi}
      baseUrl="https://payment-kit.another-domain.com"
    >
      {/* 您的支付元件 */}
    </PaymentProvider>
  );
}

自訂驗證令牌

在您需要使用特定的 API 令牌而不是預設的基於 session 的驗證的情境下 (例如，用於伺服器對伺服器通訊或特定的存取授權)，您可以傳遞 authToken prop。

TokenAuthApp.tsx

import { PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from './SessionContext';

function TokenAuthApp() {
  const { session, connectApi } = useSessionContext();
  const myCustomAuthToken = 'sk_xxxxxx'; // 您的秘密令牌

  return (
    <PaymentProvider
      session={session}
      connect={connectApi}
      authToken={myCustomAuthToken}
    >
      {/* 元件將使用提供的 authToken 進行 API 呼叫 */}
    </PaymentProvider>
  );
}

設定好 PaymentProvider 後，您現在可以開始將支付元件整合到您的應用程式中。一個好的下一步是探索如何使用 CheckoutForm 元件來建立支付流程。