# @billboard\.js/react 中文文档

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

版本：1\.1\.1
npm 元数据更新时间：2023-11-30T01:58:42.280Z
中文译文更新时间：2026-11-08T02:27:48.047Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：9.8 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：billboard\.js \>=3\.0\.0，react \>=16\.8\.0
- 首次发布：2022-09-01T13:31:47.069Z
- 最新版本发布：2023-11-30T01:58:42.042Z
- 近 30 天下载量：3062（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

Billboard.js 的反应组件

## 安装

```sh
npm install @billboard.js/react
```

也可以使用：`pnpm add @billboard.js/react`、`yarn add @billboard.js/react`、`bun add @billboard.js/react`

## README

# @ billboard.js/反应

Billboard.js 的反应组件

## 安装

```bash
# Install billboard.js together if you don't have it already
$ npm install billboard.js @billboard.js/react
```

## 如何使用

> i️ 组件将创建一个 `<div>` 元素并附加到母元素中 [`bindto`](https://naver.github.io/billboard.js/release/latest/doc/Options.html#.bindto) 在此情况下不支持选项.

### 基本用途

```jsx
import React, {useEffect, useRef} from "react";

// import billboard.js
import bb, {line} from "billboard.js";
import "billboard.js/dist/billboard.css";  // default css

// import react wrapper
import BillboardJS, {IChart} from "@billboard.js/react";
// const BillboardJS = require("@billboard.js/react");  // for CJS

function App() {
    // to get the instance, create ref and pass it to the component
    const chartComponent = useRef<IChart>(null);
    const options = {
        data: {
            columns: [
                ["data1", 300, 350, 300]
            ],
            type: line()
        }
    };

    useEffect(() => {
        // get the instance from ref
        const chart = chartComponent.current?.instance;

        // call APIs
        if (chart) {
            chart.load( ... );
        }
    }, []);

    return <BillboardJS 
        bb={bb}
        options={options}
        ref={chartComponent}

        /* The values will be specified to the bound element as inlined styles */
        style={{
            width: "500px",
            ...
        }}

        /* When class name doesn't contains `bb`,
           then you also need to update the default CSS to be rendered correctly. */
        className={"bb my-classname"}
    />;
}
```

### 使用 `props` 转到组件

当选项传递到"图"组件时.

```js
// index.tsx
import App from "./App.tsx";

const options = {
    data: {
        columns: [
            ["data1", 300, 350, 300]
        ],
        type: "bar"
    }
};

<App {...options} />

// or
// <App data={
//     columns: [
//         ["data1", 300, 350, 300]
//     ],
//     type: "bar"
// } />

// App.tsx
import * as Chart from "billboard.js";
import "billboard.js/dist/billboard.css";  // default css
import BillboardJS, {IChart, IChartOptions} from "../src/index";

export function App(props: IChartOptions) {
    const chartComponent = useRef<IChart>(null);

    // when chart "type" is passed from props, chart types need to be initialized separately.
    // in this scenario, can't be "tree-shaken" only used chart type modules.
    Chart[props.data.type]();

    useEffect(() => {
        const chart = chartComponent.current?.instance;

        if (chart) {
            chart.load( ... );
        }
    }, []);

    return <BillboardJS 
        bb={Chart.bb} 
        options={props} 
        ref={chartComponent}
     />;
}
```

### 类型脚本接口

```ts
// chart options
interface IChartOptions;

// @billboard.js/react props
interface IProp extends Pick<HTMLProps<HTMLDivElement>, "className" | "style"> {
    bb: typeof bb;
    options: ChartOptions;
}

// Chart instance
interface IChart {
    instance: Chart;
}
```

## 常见问题

### @billboard\.js/react 是什么？

Billboard\.js 的反应组件

### 如何安装 @billboard\.js/react？

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

### @billboard\.js/react 支持 TypeScript 吗？

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

### @billboard\.js/react 支持 ESM 还是 CommonJS？

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

### @billboard\.js/react 可以商用吗？

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

### @billboard\.js/react 的下载量有多少？

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

### @billboard\.js/react 还在维护吗？

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