@hatiolab/things-scene

中文文档
10.1.122发布于 2026/11/16SEE LICENSE IN http://things-scene.hatiolab.com/EULA/TypeScriptESM + CJS近 30 天下载 1.9万

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

中文使用文档
文档目录15 节
  1. 特征
  2. 安装
  3. 使用量
  4. 无害环境管理(建议)
  5. UMD 图像
  6. 三维特性( v10)
  7. 启用 三维模式
  8. 材质3D API
  9. 3D 组件类型
  10. GLTF 模型
  11. 构建
  12. 发展
  13. 迁移 v9 – v10
  14. 中断更改
  15. 许可证

场景

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

特征

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

安装

npm install @hatiolab/things-scene

使用量

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

// create and render a scene

UMD 图像

<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 属性 :

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 模型

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无头/安全部门改革模拟
npm run build       # types + rollup (production)
npm test            # 2460+ tests (mocha)
npm run type-check  # tsc --noEmit

发展

见 发展.md 为开发设置.

迁移 v9 – v10

中断更改

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

见 变动情况 完整名单.

许可证

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

版本与发布记录

@hatiolab/things-scene 共发布 773 个版本,首次发布于 2017/12/17;过去 12 个月发布了 271 个版本。

版本发布日期距今
10.1.122latest2026/11/161 天前
10.1.1212026/11/152 天前
10.1.1202026/11/143 天前
10.1.1192026/11/133 天前
10.1.1182026/11/134 天前
10.1.1172026/11/124 天前

其他发布通道:beta → 10.0.0-beta.6。

关于 @hatiolab/things-scene 的常见问题

@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 和提交记录判断。