# @hatiolab/things-scene 中文文档

规范地址：https://npmcn.com/package/%40hatiolab/things-scene/

版本：10\.1\.122
npm 元数据更新时间：2026-11-16T09:38:45.589Z
中文译文更新时间：2026-11-17T11:49:28.322Z
软件包许可：SEE LICENSE IN http://things-scene\.hatiolab\.com/EULA/

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

原始 npm 页面：https://www.npmjs.com/package/%40hatiolab/things-scene
原文对照：https://npmcn.com/package/%40hatiolab/things-scene/?lang=original
项目主页：https://github.com/hatiolab/things-scene#readme
源码仓库：https://github.com/hatiolab/things-scene

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

- 包体积（解压后）：10.5 MB，440 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：7 个
- 首次发布：2017-12-17T01:51:11.561Z
- 最新版本发布：2026-11-16T09:38:45.309Z
- 近 30 天下载量：18696（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：773（近 12 个月 271 个）

## 中文简介

用于构建交互式视觉编辑器的高性能 2D/3D 场景图库,将 HTML5 Canvas 和 Three.js 组合在一起,以启用设施可视化,数据驱动动画,实时监测仪表板

## 安装

```sh
npm install @hatiolab/things-scene
```

也可以使用：`pnpm add @hatiolab/things-scene`、`yarn add @hatiolab/things-scene`、`bun add @hatiolab/things-scene`

## README

# 场景

一个高性能的2D/3D场景图库,用于构建交互式视觉编辑器. 它结合了HTML5 Canvas和Tree.js,可以实现设施可视化,由数据驱动的动画,以及从单一组件模型产生的实时监测仪表板.

## 特征

-   高性能 Canvas 二维渲染
-   三.js基于三维渲染(WebGL)
-   基于构成部分的架构
-   Gizmo 编辑系统( 移动 / 旋转 / 缩放)
-   材料3D预置系统(金属、玻璃、塑料、木材、陶瓷、橡胶)
-   无缝2D QQ 3D 属性绑定
-   GLTF/GLB 模型装入每个节点的控制
-   无害环境管理和UMD建设
-   类型脚本严格模式

## 安装

```bash
npm install @hatiolab/things-scene
```

## 使用量

### 无害环境管理(建议)

```javascript
import { Scene, Component } from '@hatiolab/things-scene'

// create and render a scene
```

### UMD 图像

```html
<script src="node_modules/@hatiolab/things-scene/things-scene-min.js"></script>
<script>
  const { Scene, Component } = window['things-scene']
</script>
```

## 三维特性( v10)

### 启用 三维模式

设定 `threed: true` 在模型层上启用 三维模式。 单一组成部分模式 制取到2D和3D,使用活模式切换.

### 材质3D API

通过组件控制三维材料 `material3d` 属性 :

```javascript
component.set('material3d', {
  preset: 'glass',      // default, metal, glass, plastic, wood, ceramic, rubber
  metalness: 0.5,       // 0–1
  roughness: 0.3,       // 0–1
  opacity: 0.3,         // 0–1 (preset default or explicit)
  envMapIntensity: 1.5, // 0–3
  side: 'double',       // double, front, back
  castShadow: true,
  receiveShadow: false,
})
```

### 3D 组件类型

球体 立方体 圆柱体 班纳相机 墙体 GLTF Object, Light, Sprite.

### GLTF 模型

```javascript
component.set('src', '/models/building.glb')
component.set('nodes', {
  Wall: { color: '#ff0000', opacity: 0.5 },
  Door: { visible: false },
})
```

## 构建

| 格式 | 文件 | 目标 |
| --- | --- | --- |
| 无害环境管理 | `things-scene.mjs` | 现代浏览器 |
| UMD 图像 | `things-scene-min.js` | 任何环境 |
| 节点 | `things-scene-transfer.mjs` | 无头/安全部门改革模拟 |

```bash
npm run build       # types + rollup (production)
npm test            # 2460+ tests (mocha)
npm run type-check  # tsc --noEmit
```

## 发展

见 [发展.md](https://npmcn.com/package/%40hatiolab/things-scene/DEVELOPMENT.md) 为开发设置.

## 迁移 v9 – v10

### 中断更改

-   `strict: true` - 自定义组件必须满足 `strictPropertyInitialization`等 (中文(简体) ).
-   硬化评估沙盒 - `window` 编号 : `document` 编号 : `globalThis` 访问被屏蔽 (单位:千美元)`scene`, (中文(简体) ), `setTimeout`, (中文(简体) ), `Math`,并保留类似内容).
-   `innerHTML` → `textContent`,通过 DOMPurify 进行安全 HTML 渲染.
-   这个 `state` getter 现在是一个代理服务器(行为兼容: get / 有 / 拥有 Keys / 分布所有支持) .
-   `bounds` 返回值为 `Object.freeze`d) 变异前带有散射的复制件.

见 [变动情况](https://npmcn.com/package/%40hatiolab/things-scene/CHANGELOG.md) 完整名单.

## 许可证

这个项目是根据专利许可证发放的. 许可条件 : [http://things-scene.hatiolab.com/EULA/ (英语)](http://things-scene.hatiolab.com/EULA/)

## 常见问题

### @hatiolab/things-scene 是什么？

用于构建交互式视觉编辑器的高性能 2D/3D 场景图库,将 HTML5 Canvas 和 Three\.js 组合在一起,以启用设施可视化,数据驱动动画,实时监测仪表板

### 如何安装 @hatiolab/things-scene？

在项目目录运行 npm install @hatiolab/things-scene，或使用 pnpm add / yarn add / bun add。

### @hatiolab/things-scene 支持 TypeScript 吗？

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

### @hatiolab/things-scene 支持 ESM 还是 CommonJS？

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

### @hatiolab/things-scene 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @hatiolab/things-scene 可以商用吗？

@hatiolab/things-scene 使用 SEE LICENSE IN http://things-scene\.hatiolab\.com/EULA/ 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @hatiolab/things-scene 的下载量有多少？

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

### @hatiolab/things-scene 还在维护吗？

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

