# @beeq/react 中文文档

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

版本：1\.18\.0
npm 元数据更新时间：2026-11-13T06:56:20.905Z
中文译文更新时间：2026-11-13T07:02:33.894Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40beeq/react
原文对照：https://npmcn.com/package/%40beeq/react/?lang=original
源码仓库：https://github.com/Endava/BEEQ

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

- 包体积（解压后）：208 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^18 \|\| ^19，react-dom ^18 \|\| ^19
- 首次发布：2024-02-21T10:42:53.498Z
- 最新版本发布：2026-11-13T06:56:20.519Z
- 近 30 天下载量：2143（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：89（近 12 个月 34 个）

## 中文简介

对 BEEQ 设计系统组件进行特定包装

## 安装

```sh
npm install @beeq/react
```

也可以使用：`pnpm add @beeq/react`、`yarn add @beeq/react`、`bun add @beeq/react`

## README

# BEEQ 反应收发器

一个轻量级的公用设备,可以包装BEEQ自定义元素("web 组件"),从而可以像本土反应组件一样被使用.

## 为什么有必要?

反应和定制元素不能很好地一起发挥. 这个问题最好由下列文件来描述: [自定义元素出处](https://custom-elements-everywhere.com/#react)数字 :

> **处理数据**
> 
> React以HTML属性的形式将所有数据传递给自定义元素. 对于原始数据来说,这是好的,但是系统在传递丰富的数据时会崩溃,比如物体或阵列. 在这种情况下,你最后会得到一些字符串的值,如“\[对象对象\]”实际上不能使用.
> 
> **处理事件**
> 
> 由于React执行自己的合成事件系统,它不能听从来自自定义元素的DOM事件而不使用工作绕道. 开发者需要使用一个参考器引用其自定义元素, 并手动附加带有添加EventListener的事件倾听器 。 这使得与自定义元素的合作变得麻烦.

此工具通过曝光一个将属性和事件映射到基本自定义元素的本地反应组件来解决这些问题. QQ

## 软件包安装

> \[TIP\] 请永远提到 [bEEQ 正式文件](https://www.beeq.design/3d466e231/p/359a26-for-developers/b/28e01f) 关于安装的更多信息.

-   安装软件包

```
npm install @beeq/{core,react}
```

> \[注\] 确保您安装了 `@beeq/core` 软件包.

### 添加 BEEQ 样式和资产

将 BEEQ 样式导入您的应用程序主样式文件 :

```css
@import "@beeq/core/dist/beeq/beeq.css";
```

> \[TIP\] BEEQ使用SVG图标,这些资产被运入单独的文件夹. 你可以用这个 `setBasePath` 设置图标路径的方法。 确保您的工程将图标捆绑在浏览器可以访问的方式 .

您可以将图标从节点模块文件夹移动到您的资产文件夹并设置这样的路径 :

```js
// vite.config.js
import { defineConfig } from 'vite';
import { viteStaticCopy } from 'vite-plugin-static-copy';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react(),
    viteStaticCopy({
      targets: [
        {
          src: './node_modules/@beeq/core/dist/beeq/svg/*',
          dest: 'icons/svg',
        },
        // add more targets if needed
      ],
    }),
  ],
  // other configurations
});
```

```js
// main.ts
import { setBasePath } from "@beeq/core/dist/components";

setBasePath('icons/svg');
```

> 请注意路径

但您也可以使用不同的图标库或CDN:

```js
import { setBasePath } from "@beeq/core/dist/components";

// Using heroicons library
setBasePath('https://cdn.jsdelivr.net/npm/heroicons@2.1.5/24/outline');
```

> \[叹息\] 在使用不同的图标库时,确保您使用由库或CDN提供的正确的图标名称.

## 使用量

```jsx
import React from 'react';
import { BqButton } from '@beeq/react';

function App() {
  const handleButtonClick = (ev: CustomEvent) => {
    console.log(ev.detail);
  };

  return (
    <BqButton appearance="primary" onBqClick={handleButtonClick}>
      Click Me
    </BqButton>
  );
}

export default App;
```

## 常见问题

### @beeq/react 是什么？

对 BEEQ 设计系统组件进行特定包装

### 如何安装 @beeq/react？

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

### @beeq/react 支持 TypeScript 吗？

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

### @beeq/react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @beeq/react 可以商用吗？

@beeq/react 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @beeq/react 的下载量有多少？

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

### @beeq/react 还在维护吗？

最新版本 1\.18\.0 发布于 2026/11/13（今天）；至今共发布 89 个版本，其中过去 12 个月发布了 34 个；首次发布于 2024/02/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。