@hatiolab/things-scene

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

A high-performance 2D/3D scene graph library for building interactive visual editors, combining HTML5 Canvas and Three.js to enable facility visualization, data-driven animations, and real-time monitoring dashboards

原始使用文档
文档目录15 节
  1. Features
  2. Installation
  3. Usage
  4. ESM (recommended)
  5. UMD
  6. 3D Features (v10)
  7. Enabling 3D mode
  8. Material3D API
  9. 3D component types
  10. GLTF models
  11. Builds
  12. Development
  13. Migrating v9 → v10
  14. Breaking changes
  15. License

Things-Scene

A high-performance 2D/3D scene graph library for building interactive visual editors. It combines the HTML5 Canvas and Three.js to enable facility visualization, data-driven animations, and real-time monitoring dashboards from a single component model.

Features

  • High-performance Canvas-based 2D rendering
  • Three.js-based 3D rendering (WebGL)
  • Component-based architecture
  • Gizmo editing system (Move / Rotate / Scale)
  • Material3D preset system (metal, glass, plastic, wood, ceramic, rubber)
  • Seamless 2D ↔ 3D property binding
  • GLTF/GLB model loading with per-node control
  • ESM and UMD builds
  • TypeScript strict mode

Installation

npm install @hatiolab/things-scene

Usage

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>

3D Features (v10)

Enabling 3D mode

Set threed: true on the model-layer to enable 3D mode. A single component model renders to both 2D and 3D, with live mode switching.

Material3D API

Control 3D materials through a component's material3d property:

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 component types

Sphere, Cube, Cylinder, Banner, Camera, Wall, GLTFObject, Light, Sprite.

GLTF models

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

Builds

FormatFileTarget
ESMthings-scene.mjsModern browsers
UMDthings-scene-min.jsAny environment
Nodethings-scene-transfer.mjsHeadless / SSR simulation
npm run build       # types + rollup (production)
npm test            # 2460+ tests (mocha)
npm run type-check  # tsc --noEmit

Development

See DEVELOPMENT.md for the development setup.

Migrating v9 → v10

Breaking changes

  • strict: true — custom components must satisfy strictPropertyInitialization, etc.
  • Hardened evaluator sandbox — window / document / globalThis access is blocked (scene, setTimeout, Math, and similar remain available).
  • innerHTML → textContent, with safe HTML rendering via DOMPurify.
  • The state getter is now a Proxy (behavior-compatible: get / has / ownKeys / spread all supported).
  • bounds return values are Object.freezed — copy with a spread before mutating.

See CHANGELOG.md for the full list.

License

This project is distributed under a proprietary license. License terms: 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 是什么?

A high-performance 2D/3D scene graph library for building interactive visual editors, combining HTML5 Canvas and Three.js to enable facility visualization, data-driven animations, and real-time monitoring dashboards

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