Three.js Wiki

简体中文

English

简体中文

English

Appearance

开发者工具 ​

目的与范围 ​

本文档描述了基于 Three.js 构建的开发者工具生态系统，包括可视化编辑器应用、示例浏览器、文档系统和测试基础设施。这些工具使开发者能够学习、实验、构建和维护 Three.js 项目。

有关特定工具的实现细节，请参阅：

  • 可视化编辑器应用：#6.1
  • 示例系统与浏览器：#6.2
  • 文档浏览器：#6.3
  • 测试与质量保证：#6.4

有关这些工具所依赖的 Three.js 核心库信息，请参阅 Three.js 概述。

开发者工具生态系统概览 ​

Three.js 项目包含四个主要开发者工具：

工具用途入口点主要功能
可视化编辑器3D 场景创作与编辑editor/index.html可视化场景构建、多格式导入、撤销/重做、IndexedDB 持久化
示例浏览器交互式演示目录examples/index.html400+ 分类示例、搜索/过滤、截图测试
文档浏览器API 参考与手册docs/index.html可搜索 API 文档、实时代码控制台、iframe 集成
测试基础设施质量保证test/e2e/puppeteer.js视觉回归测试、确定性渲染、CI 集成

所有工具都作为 Three.js 仓库的一部分分发，并使用库的构建输出（build/three.module.js、build/three.webgpu.js）。

高层架构 ​

SVG
100%

架构概览：开发者工具消费 Three.js 构建输出并提供不同的开发工作流。编辑器通过 import maps 加载 ESM 和 WebGPU 构建，示例系统引用单个示例文件，文档暴露带有集成搜索的 API 参考页面。

可视化编辑器应用架构 ​

可视化编辑器是基于 Three.js 构建的完整 3D 创作应用。它提供场景渲染的视口、属性编辑的侧边栏面板、菜单栏操作和持久化存储。

SVG
100%

编辑器架构：Editor 类管理场景状态并通过基于信号的事件系统协调 UI 组件。用户操作调度命令，通过历史系统执行，实现撤销/重做。视口使用可配置的渲染器（WebGL 或 WebGPU）渲染场景，而侧边栏面板暴露对象属性。多格式加载由 Loader 类处理，该类委托给 examples/jsm/loaders/ 中的格式特定加载器。

编辑器信号系统 ​

编辑器使用发布-订阅模式进行组件协调：

SVG
100%

信号系统：编辑器在 Editor.js 中定义了 40+ 个信号来解耦 UI 组件。当命令修改场景状态时，它会调度相关信号（例如 objectChanged、sceneGraphChanged）。Viewport.js 中的监听器触发重新渲染，侧边栏面板刷新 UI，自动保存系统在防抖期后将状态持久化到 IndexedDB。

编辑器存储与持久化 ​

SVG
100%

持久化架构：编辑器使用 Three.js 的 ObjectLoader 格式将整个状态（场景、相机、脚本、历史）序列化为 JSON。状态存储在 IndexedDB 中并在页面加载时恢复。自动保存由信号触发（对象更改、材质更改等），具有 1 秒防抖以避免过度写入。序列化格式与 Three.js 的 ObjectLoader 兼容，支持完整项目的导出和导入。

示例系统架构 ​

示例浏览器提供 400+ Three.js 演示的可过滤目录，带实时预览：

SVG
100%

示例系统：浏览器在启动时获取 files.json 和 tags.json，使用 screenshots/ 目录中的缩略图构建可导航目录。用户交互更新 URL 哈希并将示例加载到 iframe 中。搜索使用针对文件名和标签的正则匹配过滤示例。每个示例 HTML 文件使用 import map 将 three 和 three/addons/ 路径解析为构建输出。

示例浏览器数据流 ​

SVG
100%

浏览器流程：页面加载时，浏览器获取元数据文件并用示例链接构建侧边栏。点击示例更新 URL 哈希并将示例 HTML 加载到 iframe 中。搜索输入触发针对文件名和标签的正则过滤，动态显示/隐藏示例。这种架构允许示例在隔离环境中运行，同时保持一致的导航框架。

文档浏览器架构 ​

文档系统提供可搜索的 API 参考页面和实时代码控制台：

SVG
100%

文档架构：文档浏览器加载预构建的搜索索引（search.json），包含所有 API 符号。用户输入触发模糊搜索，在下拉列表中显示结果。点击结果将相应的 API 页面加载到 iframe 中。主页面导入 Three.js 并将其暴露为 window.THREE，使开发者能够在阅读文档时在浏览器控制台中试验该库。

文档搜索实现 ​

SVG
100%

搜索实现：搜索系统对页面标题、路径和关键词执行不区分大小写的子字符串匹配。结果按匹配质量排名（完全匹配优先，然后前缀匹配，最后子字符串匹配），限制为 10 条条目。搜索在每次按键时运行，提供即时反馈。点击结果导航 iframe 到相应的 API 页面并更新 URL 哈希以便书签保存。

编辑器多格式加载系统 ​

编辑器的 Loader 类通过动态导入支持 30+ 3D 文件格式：

SVG
100%

加载器架构：Loader 类检查文件扩展名并从 examples/jsm/loaders/ 动态导入适当的加载器。对于 GLTF/GLB 文件，它显示导入对话框询问是替换整个场景还是作为对象添加。加载的对象通过命令系统添加到场景中，支持撤销。加载器还处理多文件格式的映射文件（例如 OBJ+MTL）和压缩档案（ZIP）。

编辑器命令模式 ​

所有编辑器操作都通过支持撤销/重做的命令模式执行：

SVG
100%

命令模式：每个状态修改操作都封装在具有 execute() 和 undo() 方法的命令对象中。命令传递给 editor.execute()，后者将其转发到历史系统。历史维护两个栈：撤销（已执行命令）和重做（已撤销命令）。执行新命令会清除重做栈。这种架构确保所有编辑器操作都是可逆的，并为通过 MultiCmdsCommand 进行批量操作提供一致接口。

共享 UI 框架 ​

所有三个开发者工具共享通用 CSS 和 UI 模式：

UI 模式实现使用者
面板布局#panel 侧边栏 + #viewer iframe示例、文档
搜索框带实时过滤的 #filterInput示例、文档
深色模式CSS prefers-color-scheme: dark所有工具
响应式设计移动友好的断点所有工具
图标系统files/ 目录中的 SVG 图标示例、编辑器

编辑器使用自定义 UI 框架（editor/js/libs/ui.js），包含 UIPanel、UIRow、UIInput 等类，在所有面板中提供一致的外观。

与 Three.js 核心的集成 ​

所有开发者工具通过 import maps 或 script 标签消费 Three.js：

编辑器 Import Map (editor/index.html15-27)：

{
  "imports": {
    "three": "../build/three.module.js",
    "three/webgpu": "../build/three.webgpu.js",
    "three/addons/": "../examples/jsm/"
  }
}

文档控制台 (docs/index.html11-14)：

import * as THREE from '../build/three.module.js';
window.THREE = THREE;

示例：每个示例 HTML 文件都包含自己的 import map，引用相同的构建输出。

这种一致的集成模式确保所有工具使用相同的 Three.js 版本，并能共享来自 examples/jsm/ 插件库的代码。

总结 ​

Three.js 开发者工具生态系统提供：

  1. 可视化编辑器：功能齐全的 3D 场景创作，具有基于信号的架构、用于撤销/重做的命令模式和 IndexedDB 持久化
  2. 示例浏览器：400+ 演示目录，带过滤、缩略图和视觉回归测试
  3. 文档：带实时代码控制台集成的可搜索 API 参考
  4. 测试：基于 Puppeteer 的截图测试，用于视觉回归检测

这些工具共享通用 UI 模式，与核心库一致集成，并为学习、实验和生产级创作提供互补的工作流。

Copyright © 2026 LZUGIS