# @chargebee/chargebee-js-react-wrapper 中文文档

规范地址：https://npmcn.com/package/%40chargebee/chargebee-js-react-wrapper/

版本：0\.6\.9
npm 元数据更新时间：2025-12-10T06:09:23.927Z
中文译文更新时间：2026-11-09T10:44:20.200Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40chargebee/chargebee-js-react-wrapper
原文对照：https://npmcn.com/package/%40chargebee/chargebee-js-react-wrapper/?lang=original
项目主页：https://github.com/chargebee/chargebee-js-wrappers/tree/master/chargebee-js-react#readme
源码仓库：https://github.com/chargebee/chargebee-js-wrappers

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：64.1 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^19\.0\.0 \|\| ^18\.0\.0 \|\| ^17\.0\.0，react-dom ^19\.0\.0 \|\| ^18\.0\.0 \|\| ^17\.0\.0
- 首次发布：2019-04-28T13:50:28.855Z
- 最新版本发布：2025-10-10T09:41:31.957Z
- 近 30 天下载量：161142（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 0 个）

## 中文简介

Curgebee.js组件的反效果包装器

## 安装

```sh
npm install @chargebee/chargebee-js-react-wrapper
```

也可以使用：`pnpm add @chargebee/chargebee-js-react-wrapper`、`yarn add @chargebee/chargebee-js-react-wrapper`、`bun add @chargebee/chargebee-js-react-wrapper`

## README

# 充电蜂JS反应收发器

充电器组件的回放包装器

## 实例

详细例子: [点击这里](https://github.com/chargebee/chargebee-checkout-samples/tree/master/components/react-app#readme)

## 现场直播

查看实况演示 [这里](https://www.recur.in/components-examples/react/#/example1)

## 安装

从 npm 安装 :

```bash
npm install @chargebee/chargebee-js-react-wrapper
```

## 使用量

充电蜂组件需要您以 `site` 财务报告和审定财务报表 `publishableKey`

> 想知道在哪里获得您的 API 密钥吗 ? [参考这里](https://www.chargebee.com/docs/api_keys.html)

在你身边 `index.html`数字 :

```html
<html>
    <head>
        ...
        <script src="https://js.chargebee.com/v2/chargebee.js"></script>
        <script>
            Chargebee.init({
                site: 'your-site',
                publishableKey: 'your-publishable-key'
            })
        </script>
    </head>
    <body>
        <div id='root'></div>
    </body>
</html>
```

### 基本用途

在您的反应组件中

```jsx
import { CardComponent } from '@chargebee/chargebee-js-react-wrapper';

class App extends React.Component {
    cardRef = React.createRef()
    ...
    onSubmit = (e) => {
        if(e) e.preventDefault()
        this.cardRef.current.tokenize()
        .then((data) => {
          console.log('chargebee token', data.token)
        });
    }
    ...
    render() {
        // Using combined mode
        return(
            <div className="App">
                <form>
                    ...
                    <CardComponent ref={this.cardRef} onChange={this.onChange}/>
                    <button type="submit" onClick={this.onSubmit}>Submit</button>
                    ...
                </form>
            </div>
        )
    }
}
```

### 一个更为复杂的例子是:

```jsx
import {CardComponent, CardNumber, CardExpiry, CardCVV} from "react-cb";
import './App.css'

class App extends Component {
  cardRef = React.createRef()

  state = {
    errors: {},
    errorMessage: '',
    // CSS class names for field's status
    classes: {
        'focus': 'focus-css-class',
        'complete': 'complete-css-class',
        'invalid': 'invalid-css-class',
        'empty': 'empty-css-class',
    },
    // Google Fonts and other whitelisted fonts
    fonts: [
        'https://fonts.googleapis.com/css?family=Open+Sans'
    ],
    // Style customizations
    styles: {
        base: {
            color: '#fff',
            fontWeight: 600,
            fontFamily: 'Quicksand, Open Sans, Segoe UI, sans-serif',
            fontSize: '16px',
            fontSmoothing: 'antialiased',

            ':focus': {
                color: '#424770',
            },

            '::placeholder': {
                color: '#9BACC8',
            },

            ':focus::placeholder': {
                color: '#CFD7DF',
            },
        },
        invalid: {
            color: '#fff',
            ':focus': {
                color: '#FA755A',
            },
            '::placeholder': {
                color: '#FFCCA5',
            },
        },
    }
  }

  onSubmit = (e) => {
    if(e) e.preventDefault()
    if(this.cardRef) {
      // Call tokenize method on card element
      this.cardRef.current.tokenize().then((data) => {
          console.log('chargebee token', data.token)
      });
    }
  }

  onChange = (status) => {
    let errors = {
      ...this.state.errors,
      [status.field]: status.error
    };
    let errMessages = Object.values(errors).filter(message => !!message);
    this.setState({
      errors,
      errorMessage: errMessages.pop() || '',
    })
  }

  onReady = (el) => {
    el.focus();
  }

  render() {
    const { fonts, styles, classes, locale } = this.state;
    // Using individual fields mode
    return (
      <div className="App">
          <div className="cell example example3" id="example-3">
            <form>
              <div className="fieldset">
                <CardComponent className="field" 
                    fonts={fonts} 
                    classes={classes} 
                    locale={locale} 
                    styles={styles} 
                    ref={this.CardRef} 
                    showTestCards={true}           
                    onReady={this.onReady}
                >
                    <CardNumber placeholder='4111 1111 1111 1111' className="field empty" onChange={this.onChange} onReady={this.onReady} />
                    <CardExpiry placeholder='MM / YY' className="field empty" onChange={this.onChange} />
                    <CardCVV placeholder='CVV' className="field empty" onChange={this.onChange} />
                </CardComponent>
              </div>
              <button type="submit" onClick={this.onSubmit}>Pay now</button>
            </form>
            <div id="errors">{this.state.errorMessage}</div>
          </div>
      </div>
    );
  }
}

```

## 使用下个JS 的服务器侧面渲染

#### 先决条件:

充蜜蜂实例应初始化 `site` 财务报告和审定财务报表 `API Key` 启动的 cb 实例应作为道具传递给 `Provider` 组件。 进行了验证,以检查三件事:

-   通过 `site` 作为非空字符串, 在初始化调用时
-   通过 `API Key` 作为非空字符串, 在初始化调用时
-   cb 初始状态

另外,一个使用 `NextJS` 应设置

#### 用法 :

1.  装入 `chargebee.js script` 在任何其他代码/标语执行之前(一般) `index.html`) (中文(简体) ). 这是用来启动 `Chargebee` 成为客户端浏览器的一部分 `window`

```html
<script src="https://js.chargebee.com/v2/chargebee.js"> </script>
```

2.  初始化组件内部的充电蜂 DidMount( ), 在使用 SSR 时不要在构造器( ) 或渲染器( ) 中使用它

```jsx
componentDidMount() {
..
    // initialize with site, publishableKey
    window.Chargebee.init({
        site: "...",
        publishableKey: "..."
    });
    
    // get cb Instance
    cbInstance = window.Chargebee.getInstance();
..
}
```

3.  从模块中导入提供者、 纸质组件等组件

```jsx
import {CardComponent, CardNumber, CardExpiry, CardCVV, Provider} from "@chargebee/chargebee-js-react-wrapper";
```

4.  在自定义组件中,将 `CardComponent` 内置 a `Provider` 组件,通过 cbInstance 作为道具

```jsx
<Provider cbInstance={this.props.cbInstance}>
   <CardComponent ... >
    ...
    </CardComponent>
</Provider>
```

#### 示例

详细实例 :

```jsx
import {CardComponent, CardNumber, CardExpiry, CardCVV, Provider} from "@chargebee/chargebee-js-react-wrapper";

...
componentDidMount() {
  window.Chargebee.init({
    site: "honeycomics-v3-test",
    publishableKey: "your_site_pub_api_key"
  })

  this.setState({
    cbInstance: window.Chargebee.getInstance()
  })
}

render() {
...
<script src="https://js.chargebee.com/v2/chargebee.js" ></script>
...
<Provider cbInstance={this.state.cbInstance}>
  <CardComponent ref={this.cardRef} className="fieldset field"
    styles={style} 
    classes={classes} 
    locale={locale}
    placeholder={placeholder}
    fonts={fonts}
    showTestCards={true}
  >
    <div className="ex1-field">
      {/* Card number component */}
      <CardNumber className="ex1-input"/>
      <label className="ex1-label">Card Number</label><i className="ex1-bar"></i>
    </div>

    <div className="ex1-fields">
      <div className="ex1-field">
        {/* Card expiry component */}
        <CardExpiry className="ex1-input"/>
        <label className="ex1-label">Expiry</label><i className="ex1-bar"></i>
      </div>

      <div className="ex1-field">
        {/* Card cvv component */}
        <CardCVV className="ex1-input"/>
        <label className="ex1-label">CVC</label><i className="ex1-bar"></i>
      </div>

    </div>
  </CardComponent>
</Provider>
... 
}
```

#### 运行应用程序

-   npm 安装
-   (NextJS项目结构,安装了充电蜂-js-反应-收发机) - > npm 运行构建 / start / dev

```jsx
"scripts": {
   "dev": "next dev",
   "build": "next build",
   "start": "next start"
 }
```

### 3DS 授权

在您的反应组件中

```jsx
import { CardComponent } from '@chargebee/chargebee-js-react-wrapper';

class App extends React.Component {
    cardRef = React.createRef()
    ...
    createPaymentIntent() {
      // make ajax call to server to create payment intent
    }
    ...
    componentDidMount() {
      this.createPaymentIntent().then(intent => {
        this.state.intent = intent;
      })
    }
    ...
    onSubmit = (e) => {
        if(e) e.preventDefault()
        
        const intent = this.state.intent;
        const additionalData = this.state.additionalData;
        
        this.cardRef.current.authorizeWith3ds(intent, additionalData)
        .then(authorizedPaymentIntent => {
          console.log('Authorized payment intent', authorizedPaymentIntent.id)
        }).catch(error => {
          console.error('Error occured', error)
        });
    }
    ...
    render() {
        // Using combined mode
        return(
            <div className="App">
                <form>
                    ...
                    <CardComponent ref={this.cardRef} onChange={this.onChange}/>
                    <button type="submit" onClick={this.onSubmit}>Submit</button>
                    ...
                </form>
            </div>
        )
    }
}
```

## 组件和API

#### 卡片组件[文档](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#card-component-object)(中文(简体) )

| 道具 | 说明 | 数据类型 |
| --- | --- | --- |
| `className` | 容器 div 的 CSS 类名称 | 字符串 |
| `fonts` | 字体面或链接的阵列 | [字体](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-3) |
| `classes` | 用于替换各种 CSS 类名的集 [事件](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#on) | [类](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-3) |
| `locale` | 语言代码 | [语言](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-3) |
| `styles` | 样式定制集 | [样式](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-3) |
| `placeholder` | 卡片字段的一组占位符 | [占位符](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-3) |
| `ref` | 用于表示数据的Ref 元素 | [反应参考文献](https://reactjs.org/docs/refs-and-the-dom.html#creating-refs) |
| `showTestCards` | 添加在测试站点显示测试卡的能力 | 布尔 |

##### 活动支持( E)[文档](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#on)(中文(简体) )

| 道具 | 说明 | 参数 |
| --- | --- | --- |
| `onReady` | 组件挂起并准备好时触发器 | [外地](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#card-field-object) |
| `onChange` | 每个州变化的触发器 | [战地状态](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-6) |
| `onFocus` | 当组件被聚焦时触发 | [战地状态](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-6) |
| `onBlur` | 组件模糊时触发 | [战地状态](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-6) |
| `onKeyPress` | 在组件内按下密钥时触发  
支助 `ESC` 键 | [战地状态](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-6) |

#### 外地构成部分([文档](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#card-field-object)(中文(简体) )

-   卡片号码
-   纸质打印
-   纸牌CVV

| 道具 | 说明 | 数据类型 |
| --- | --- | --- |
| `className` | 容器的 CSS 类名 `div` | 字符串 |
| `styles` | 二元字段样式 | [样式](http://localhost:8081/checkout-portal-docs/components-fields-reference.html#parameters-5) |
| `placeholder` | 字段的占位符 | 字符串 |

##### 活动支持( E)[文档](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#on-2)(中文(简体) )

| 道具 | 说明 | 参数 |
| --- | --- | --- |
| `onReady` | 组件挂起并准备好时触发器 | [外地](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#card-field-object) |
| `onChange` | 每个州变化的触发器 | [战地状态](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-6) |
| `onFocus` | 当组件被聚焦时触发 | [战地状态](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-6) |
| `onBlur` | 组件模糊时触发 | [战地状态](https://chargebee.com/checkout-portal-docs/components-fields-reference.html#parameters-6) |

## 参考:

[充气管组件-联署文件](https://chargebee.com/checkout-portal-docs/components-fields-integrations.html#quick-start-integration)

## 支助

是否有人询问执行情况? 联系 [支持@ forcebee.com](mailto:support@chargebee.com)

## 常见问题

### @chargebee/chargebee-js-react-wrapper 是什么？

Curgebee\.js组件的反效果包装器

### 如何安装 @chargebee/chargebee-js-react-wrapper？

在项目目录运行 npm install @chargebee/chargebee-js-react-wrapper，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0 \|\| ^18\.0\.0 \|\| ^17\.0\.0）、react-dom（^19\.0\.0 \|\| ^18\.0\.0 \|\| ^17\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @chargebee/chargebee-js-react-wrapper 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @chargebee/chargebee-js-react-wrapper 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @chargebee/chargebee-js-react-wrapper 可以商用吗？

@chargebee/chargebee-js-react-wrapper 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @chargebee/chargebee-js-react-wrapper 的下载量有多少？

根据 npm 官方下载统计，@chargebee/chargebee-js-react-wrapper 在 2026/10/10 – 2026/11/08 这 30 天内被下载 161,142 次，日均约 5,371 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @chargebee/chargebee-js-react-wrapper 还在维护吗？

最新版本 0\.6\.9 发布于 2025/10/10（1\.1 年前）；至今共发布 25 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/04/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。