PaymentProvider | ArcBlock

PaymentProvider 是 @blocklet/payment-react 库的基石。它作为一个上下文提供者，必须包裹您的应用程序或相关的支付组件。它负责获取必要的设置、管理应用程序状态，并向其所有子组件提供辅助函数和 API 客户端。

该库中几乎所有的组件和钩子都需要嵌套在 PaymentProvider 中才能正常工作。

工作原理

提供者在挂载时会初始化并从 Payment Kit 后端获取配置数据。这些数据连同用户会话和其他实用工具，通过 usePaymentContext 钩子提供给任何后代组件。这种模式确保您的支付组件始终能够访问必要的上下文，而无需进行属性钻取（prop drilling）。

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 提供会话和 connectApi
export function useSessionContext() {
  const { session, connect } = useDidSessionContext();
  return { session, connectApi: connect };
}

一旦您的会话管理就位，请使用 PaymentProvider 包裹您的主应用程序组件。

App.tsx

import { PaymentProvider } from '@blocklet/payment-react';
import { useSessionContext } from './SessionContext'; // 你的会话上下文钩子
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	类型	必需	描述
`session`	`Session`	是	来自您的身份验证上下文（例如，`@arcblock/did-connect-react`）的用户会话对象。
`connect`	`Connect`	是	来自您的身份验证上下文的 `connect` API 函数，用于 DID Connect 操作。
`children`	`React.ReactNode`	是	将有权访问支付上下文的子组件。
`baseUrl`	`string`	否	Payment Kit blocklet 的基础 URL。仅在从不同源（跨源）集成支付组件时需要。
`authToken`	`string`	否	用于 API 请求的特定身份验证令牌。如果提供，它将取代基于会话的身份验证。

上下文值

PaymentProvider 内的组件可以使用 usePaymentContext 钩子访问以下值。

MyComponent.tsx

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

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

  return (
    <div>
      <p>Base Currency: {settings.baseCurrency?.name}</p>
      <p>Mode: {livemode ? 'Live' : 'Test'}</p>
      <button onClick={() => setLivemode(!livemode)}>Toggle Mode</button>
    </div>
  );
}

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

键	类型	描述
`session`	`object`	经过身份验证的用户会话，包括用户详细信息。
`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 令牌而不是默认的基于会话的身份验证（例如，用于服务器到服务器的通信或特定的访问授权），您可以传递 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 组件来创建支付流程。