@intercartx/booster-react

基于 React 的结账组件库，提供完整的结账页面和业务组件。构建在 @intercartx/booster-core 之上，为 React 应用提供开箱即用的结账功能。

安装

npm install @intercartx/booster-react
# 或
pnpm add @intercartx/booster-react
# 或
yarn add @intercartx/booster-react

peerDependencies

本包需要以下 peer dependencies：

npm install react react-dom
# React 版本要求: ^18.2.0

功能特性

🎨 完整结账页面

• CheckoutPage: 开箱即用的完整结账页面组件
• CheckoutProvider: 结账上下文提供者，管理配置和状态

📦 业务组件

• Address: 地址输入组件，支持 Google Places 自动完成
• CustomInfo: 客户信息输入组件（姓名、邮箱、电话）
• PaymentMethod: 支付方式选择组件
• PayButton: 支付按钮组件
• OrderSummary: 订单摘要组件
• ShippingMethods: 运费方式选择组件
• AddTips: 小费添加组件
• PaypalModal: PayPal 支付模态框
• BuyNow: 立即购买按钮
• MultiRegions: 多地区选择组件
• PhoneRegionInput: 带地区选择的电话输入组件
• GoogleAddressSuggestion: Google 地址建议组件

🎯 UI 组件

• ItxButton: 按钮组件
• ItxInput: 输入框组件
• ItxSelect: 选择器组件
• ItxSelectList: 选择列表组件
• FullScreenLoading: 全屏加载组件
• Accordion: 手风琴组件

🔧 Hooks

• useCheckout: 获取结账上下文和配置
• useModel: 使用业务模型

快速开始

基础使用

最简单的使用方式是直接使用 CheckoutPage 组件：

import { CheckoutPage } from '@intercartx/booster-react'
import '@intercartx/booster-react'

function App() {
  return (
    <CheckoutPage
      token="your-checkout-token"
      googleApiKey="your-google-api-key"
      onOrderCompleted={(order) => {
        console.log('Order completed:', order)
        // 跳转到成功页面
      }}
    />
  )
}

使用 CheckoutProvider

如果需要更多自定义控制，可以使用 CheckoutProvider 和各个业务组件：

import { 
  CheckoutProvider, 
  Address, 
  CustomInfo, 
  PaymentMethod, 
  PayButton, 
  OrderSummary 
} from '@intercartx/booster-react'
import '@intercartx/booster-react'

function App() {
  return (
    <CheckoutProvider
      token="your-checkout-token"
      googleApiKey="your-google-api-key"
      onOrderCompleted={(order) => {
        console.log('Order completed:', order)
      }}
    >
      <div className="checkout-container">
        <div className="checkout-form">
          <CustomInfo />
          <Address />
          <PaymentMethod />
          <PayButton />
        </div>
        <div className="checkout-summary">
          <OrderSummary />
        </div>
      </div>
    </CheckoutProvider>
  )
}

使用 useCheckout Hook

在 CheckoutProvider 内部，可以使用 useCheckout hook 访问配置和状态：

import { CheckoutProvider, useCheckout } from '@intercartx/booster-react'

function CustomComponent() {
  const { config, globalState } = useCheckout()
  
  return (
    <div>
      <h1>Welcome to {config.website.name}</h1>
      <p>Currency: {config.currency}</p>
    </div>
  )
}

function App() {
  return (
    <CheckoutProvider token="your-token">
      <CustomComponent />
    </CheckoutProvider>
  )
}

组件 API

CheckoutPage

完整的结账页面组件，包含所有必要的结账步骤。

interface CheckoutPageProps {
  token: string                    // 结账 token（必需）
  googleApiKey?: string            // Google API Key（可选，用于地址自动完成）
  initTst?: string                 // 初始化追踪 ID（可选）
  tst?: string                     // 追踪 ID（可选）
  onOrderCompleted?: (order: any) => void  // 订单完成回调（可选）
  fallback?: ReactNode             // 加载失败时的回退 UI（可选）
}

示例：

<CheckoutPage
  token="your-token"
  googleApiKey="your-google-api-key"
  onOrderCompleted={(order) => {
    window.location.href = '/order-success'
  }}
  fallback={<div>Loading failed. Please refresh.</div>}
/>

CheckoutProvider

结账上下文提供者，管理配置和全局状态。

interface CheckoutProviderProps {
  token: string                    // 结账 token（必需）
  googleApiKey?: string            // Google API Key（可选）
  children: ReactNode              // 子组件（必需）
  onOrderCompleted?: (token: string) => void  // 订单完成回调（可选）
  fallback?: ReactNode             // 加载失败时的回退 UI（可选）
  tst?: string                     // 追踪 ID（可选）
  initTst?: string                 // 初始化追踪 ID（可选）
}

示例：

<CheckoutProvider
  token="your-token"
  googleApiKey="your-google-api-key"
  onOrderCompleted={(orderToken) => {
    console.log('Order token:', orderToken)
  }}
>
  {/* 你的结账组件 */}
</CheckoutProvider>

Address

地址输入组件，支持 Google Places 自动完成。

<Address />

CustomInfo

客户信息输入组件。

<CustomInfo />

PaymentMethod

支付方式选择组件。

<PaymentMethod />

PayButton

支付按钮组件。

interface PayButtonProps {
  style?: CSSProperties
  className?: string
}

<PayButton 
  style={{ backgroundColor: '#0042fb', color: 'white' }}
  className="custom-pay-button"
/>

OrderSummary

订单摘要组件，显示订单详情和总价。

<OrderSummary />

ShippingMethods

运费方式选择组件。

<ShippingMethods />

AddTips

小费添加组件。

interface AddTipsProps {
  shopName?: string
}

<AddTips shopName="Your Shop Name" />

PaypalModal

PayPal 支付模态框。

interface PaypalModalProps {
  visible: boolean
  onVisibleChange: (visible: boolean) => void
}

const [paypalVisible, setPaypalVisible] = useState(false)

<PaypalModal 
  visible={paypalVisible} 
  onVisibleChange={setPaypalVisible} 
/>

BuyNow

立即购买按钮。

<BuyNow />

PhoneRegionInput

带地区选择的电话输入组件。

<PhoneRegionInput />

GoogleAddressSuggestion

Google 地址建议组件。

<GoogleAddressSuggestion />

MultiRegions

多地区选择组件。

<MultiRegions />

UI 组件

ItxButton

按钮组件。

interface ItxButtonProps {
  children: ReactNode
  onClick?: () => void
  disabled?: boolean
  type?: 'button' | 'submit' | 'reset'
  style?: CSSProperties
  className?: string
}

<ItxButton onClick={() => console.log('Clicked')}>
  Click Me
</ItxButton>

ItxInput

输入框组件。

interface ItxInputProps {
  value?: string
  onChange?: (value: string) => void
  placeholder?: string
  type?: string
  disabled?: boolean
  error?: string
  style?: CSSProperties
  className?: string
}

<ItxInput 
  placeholder="Enter text"
  onChange={(value) => console.log(value)}
/>

ItxSelect

选择器组件。

interface ItxSelectProps {
  value?: string
  onChange?: (value: string) => void
  options: Array<{ label: string; value: string }>
  placeholder?: string
  disabled?: boolean
  style?: CSSProperties
  className?: string
}

<ItxSelect 
  options={[
    { label: 'Option 1', value: '1' },
    { label: 'Option 2', value: '2' }
  ]}
  onChange={(value) => console.log(value)}
/>

FullScreenLoading

全屏加载组件。

<FullScreenLoading />

Accordion

手风琴组件。

import { Accordion } from '@intercartx/booster-react'

<Accordion>
  <Accordion.Item title="Section 1">
    Content 1
  </Accordion.Item>
  <Accordion.Item title="Section 2">
    Content 2
  </Accordion.Item>
</Accordion>

Hooks

useCheckout

获取结账上下文和配置。

import { useCheckout } from '@intercartx/booster-react'

function MyComponent() {
  const { config, globalState } = useCheckout()
  
  // 使用 config 和 globalState
  return <div>{config.website.name}</div>
}

返回值：

interface CheckoutContextValue {
  config: CheckoutConfig
  globalState: typeof globalState
}

useModel

使用业务模型（内部 hook，通常不需要直接使用）。

样式

本包会自动导入必要的样式。如果需要自定义样式，可以覆盖 CSS 变量或使用自定义类名。

导入样式

样式会自动通过 JavaScript 注入，无需手动导入。如果需要单独导入：

import '@intercartx/booster-react'
// 这会自动导入所有必要的样式

类型定义

所有组件都提供完整的 TypeScript 类型定义。

import type { 
  CheckoutConfig,
  CheckoutEvents 
} from '@intercartx/booster-react'

完整示例

import { 
  CheckoutProvider, 
  CheckoutPage,
  useCheckout 
} from '@intercartx/booster-react'
import '@intercartx/booster-react'
import { useState } from 'react'

// 方式 1: 使用完整的 CheckoutPage
function SimpleCheckout() {
  return (
    <CheckoutPage
      token="your-token"
      googleApiKey="your-google-api-key"
      onOrderCompleted={(order) => {
        console.log('Order completed:', order)
        window.location.href = '/success'
      }}
    />
  )
}

// 方式 2: 使用 CheckoutProvider 自定义布局
function CustomCheckout() {
  return (
    <CheckoutProvider
      token="your-token"
      googleApiKey="your-google-api-key"
      onOrderCompleted={(order) => {
        console.log('Order completed:', order)
      }}
    >
      <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '20px' }}>
        <div>
          <h2>Customer Information</h2>
          <CustomInfo />
          
          <h2>Shipping Address</h2>
          <Address />
          
          <h2>Payment Method</h2>
          <PaymentMethod />
          
          <PayButton />
        </div>
        <div>
          <h2>Order Summary</h2>
          <OrderSummary />
        </div>
      </div>
    </CheckoutProvider>
  )
}

// 方式 3: 使用 useCheckout hook
function CheckoutWithCustomLogic() {
  return (
    <CheckoutProvider token="your-token">
      <CheckoutContent />
    </CheckoutProvider>
  )
}

function CheckoutContent() {
  const { config } = useCheckout()
  const [step, setStep] = useState(1)
  
  return (
    <div>
      <h1>Checkout - {config.website.name}</h1>
      {step === 1 && <CustomInfo />}
      {step === 2 && <Address />}
      {step === 3 && <PaymentMethod />}
      <button onClick={() => setStep(step + 1)}>Next</button>
    </div>
  )
}

依赖项

核心依赖

• @intercartx/booster-core: 核心功能库
• react: React 库 (^18.2.0)
• react-dom: React DOM 库 (^18.2.0)

开发依赖

• @types/react: React 类型定义
• @types/react-dom: React DOM 类型定义
• vite: 构建工具
• @vitejs/plugin-react: Vite React 插件
• vite-plugin-dts: TypeScript 声明文件生成
• vite-plugin-css-injected-by-js: CSS 注入插件

构建

# 开发模式
pnpm run dev

# 构建
pnpm run build

# 类型检查
pnpm run typecheck

浏览器支持

• Chrome (最新版本)
• Firefox (最新版本)
• Safari (最新版本)
• Edge (最新版本)

许可证

GPL-3.0-only

相关包

• @intercartx/booster-core: 核心功能库
• @intercartx/booster-solid: SolidJS 组件库
• @intercartx/booster-elements: Web Components 库

贡献

欢迎提交 Issue 和 Pull Request！

支持

如有问题，请访问 GitHub Issues。