# @dcl/react-ecs 中文文档

规范地址：https://npmcn.com/package/%40dcl/react-ecs/

版本：7\.33\.0
npm 元数据更新时间：2026-11-05T17:51:41.428Z
中文译文更新时间：2026-11-11T17:31:25.956Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40dcl/react-ecs
原文对照：https://npmcn.com/package/%40dcl/react-ecs/?lang=original
项目主页：https://github.com/decentraland/js-sdk-toolchain#readme
源码仓库：https://github.com/decentraland/js-sdk-toolchain

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

- 包体积（解压后）：108 kB，62 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2022-09-12T14:31:20.284Z
- 最新版本发布：2026-11-05T17:51:41.064Z
- 近 30 天下载量：12578（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：1298（近 12 个月 318 个）

## 中文简介

权力下放

## 安装

```sh
npm install @dcl/react-ecs
```

也可以使用：`pnpm add @dcl/react-ecs`、`yarn add @dcl/react-ecs`、`bun add @dcl/react-ecs`

## README

# @dcl/ react-ecs (英语)

对Decentrand的实体组件系统(ECS)的回放装订,提供了使用React组件模型和JSX语法在Decentrand场景中构建UI的宣示方式.

## 特征

-   **基于 Flexbox 的布局**: 执行 CSS Flexbox 的子集,用于强大的和直观的UI布局
-   **反应组件**: 用于构建 UI 的类似 Familier React 组件 API
-   **类型安全**: 带有适当类型定义的完整类型脚本支持
-   **事件处理**: 支持鼠标事件和用户交互
-   **业绩**: 优化最低运行时间间接费用的调节
-   **主题支持**: 内置有上下文切换的光和暗主题系统

## 组成部分准则

@dcl/react-ecs中的所有组件必须:

-   归还JSX。 一致性和可替换性要素
-   通过背景整合支持主题
-   可重复使用,可与其它部件相混合

## 安装

```bash
npm install @dcl/react-ecs
```

## 基本用途

```tsx
import { ReactEcs, UiEntity, Label, Button } from '@dcl/react-ecs'

export function MyUI() {
  return (
    <UiEntity
      uiTransform={{
        width: 300,
        height: 100,
        display: 'flex',
        justifyContent: 'center',
        alignItems: 'center'
      }}
    >
      <Label value="Hello Decentraland!" />
      <Button value="Click Me!" onMouseDown={() => console.log('clicked!')} />
    </UiEntity>
  )
}
```

## 主题系统

软件包包括一个主题系统,用于一致的UI样式:

```tsx
import { ReactEcs, ThemeProvider, Button } from '@dcl/react-ecs'

// Wrap your UI with ThemeProvider
export function MyUI() {
  return (
    <ThemeProvider>
      <Button value="Theme-Aware Button" />
    </ThemeProvider>
  )
}

// Use themes in custom components
function CustomComponent() {
  const { theme, toggleTheme } = React.useContext(ThemeContext)

  return (
    <UiEntity
      uiBackground={{
        color: theme === 'light' ? '#FFFFFF' : '#000000'
      }}
      onMouseDown={toggleTheme}
    />
  )
}
```

## 构成部分

### 核心组成部分

-   **用户实体**: UI 元素的基础组件
-   **标签**: 文本显示组件
-   **按钮**: 交互式按钮组件
-   **投入**: 文本输入字段
-   **下坠**: 选择下拉菜单

### 布局系统

版式系统以Flexbox为基础,支持以下属性: 1

-   `display: 'flex'`
-   `flexDirection: 'row' | 'column'`
-   `justifyContent: 'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around'`
-   `alignItems: 'flex-start' | 'center' | 'flex-end' | 'stretch'`
-   `width`, (中文(简体) ), `height`
-   `margin`, (中文(简体) ), `padding`
-   `positionType: 'absolute' | 'relative'`

## 事件处理

组件支持以下鼠标事件 :

```tsx
<Button onMouseDown={() => {}} onMouseUp={() => {}} onMouseEnter={() => {}} onMouseLeave={() => {}} />
```

## 技术细节

该套件执行自定义的React调和器,将React的组件模型与Decentrand的ECS相接. 它会:

1.  将JSX翻译成ECS实体和组成部分
2.  管理组件生命周期和更新
3.  处理活动 代表团和吹嘘
4.  提供表演者更新机制

## 相关文档

关于UI系统架构和设计决定的更详细信息:

-   [ADR-124:实施基于Flexbox的UI](https://adr.decentraland.org/adr/ADR-124)
-   [ADR-125:用户界面组件](https://adr.decentraland.org/adr/ADR-125)
-   [AR-237: SDK 7 自定义 UI 组件](https://adr.decentraland.org/adr/ADR-237)

## 许可证

Apache 2.0 (英语)

## 常见问题

### @dcl/react-ecs 是什么？

权力下放

### 如何安装 @dcl/react-ecs？

在项目目录运行 npm install @dcl/react-ecs，或使用 pnpm add / yarn add / bun add。

### @dcl/react-ecs 支持 TypeScript 吗？

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

### @dcl/react-ecs 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @dcl/react-ecs 可以商用吗？

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

### @dcl/react-ecs 的下载量有多少？

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

### @dcl/react-ecs 还在维护吗？

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