文档浏览器

文档浏览器提供交互式界面以浏览 Three.js API 文档。它由带分层导航和搜索功能的侧边栏面板，以及显示单个文档页面的 iframe 组成。该系统处理 URL 路由、搜索和旧版 URL 迁移，实现对 API 参考材料的无缝探索。

有关示例浏览器的信息，请参阅示例系统与浏览器。有关文档页面生成和内容的详情，请参阅构建系统文档。

架构概览

文档浏览器是一个用原生 JavaScript 构建的单页应用，协调导航、搜索和内容显示。

100%

用户界面布局

界面采用固定的双面板布局，包含导航侧边栏和内容区域。

面板结构

组件	ID/类	用途
`面板容器`	`#panel`	固定侧边栏，桌面端 300px 宽
`头部`	`#header`	徽标、章节标签、展开按钮
`输入包装器`	`#inputWrapper`	搜索输入框容器
`过滤输入框`	`#filterInput`	搜索文本字段
`清除按钮`	`#clearSearchButton`	清除搜索输入
`内容`	`#content`	静态导航链接
`搜索结果`	`#searchResults`	动态搜索结果

| 查看器 | iframe[name=viewer] | 显示文档页面 |

面板宽度由 CSS 变量 --panel-width 控制（默认 300px，大屏幕 360px）。iframe 通过 padding-left: var(--panel-width) 定位以填充剩余空间。

导航系统

导航系统将页面名称映射到 URL 并管理链接选择。

100%

PageLinks 数据结构

pageLinks 对象中的每个条目将页面标识符映射到其元数据：

pageLinks['BoxHelper'] = {
  linkElement: <a> 元素,
  pageURL: 'pages/BoxHelper.html',
  anchor: '',
  href: 'BoxHelper.html'
}

pageLinks['BoxHelper.update'] = {
  linkElement: <a> 元素,
  pageURL: 'pages/BoxHelper.html',
  anchor: '#update',
  href: 'BoxHelper.html#update'
}

setupNavigation() 函数位于 docs/index.html185-264，处理所有导航链接，提取页面名称和锚点，并将它们存储在 pageLinks 中。类中的成员方法以点表示法存储（例如 BoxHelper.update）。

搜索系统

搜索系统提供带高亮和结果分组的实时过滤。

搜索索引结构

search.json 文件包含所有可搜索文档条目的索引：

{
  "Core / Animation": [
    { "title": "AnimationAction", "kind": "class" },
    { "title": "AnimationAction#play", "kind": "function" },
    { "title": "AnimationAction#paused", "kind": "property" }
  ],
  "Core / Math": [
    { "title": "Vector3", "kind": "class" },
    { "title": "Vector3#add", "kind": "function" }
  ]
}

成员用 #（方法/属性）或 ~（静态方法）表示。搜索函数对类别和标题进行匹配。

搜索流程

100%

updateFilter() 函数位于 docs/index.html300-569，实现多词搜索，所有单词必须匹配（AND 逻辑）。结果按类分组，类名显示为标题，成员缩进在下方。

搜索功能

功能	实现
多词搜索	`escapeRegExp() 将 "mesh light" 转换为 (?=.mesh)(?=.light)`
高亮	`highlightMatch() 将匹配文本包裹在 <strong> 标签中`
结果分组	`grouped[className] 对象将成员分组到类下`
类别标题	`结果以 <h2> 类别标题显示`
选择状态	当前页面链接上的 .selected 类
空状态	无匹配时显示 "No results found" 消息

URL 路由与历史

路由系统使用基于哈希的导航，支持成员锚点。

哈希格式

哈希格式	含义	示例
`#ClassName`	导航到类页面	`#BoxHelper`
`#ClassName.member`	导航到类成员	`#BoxHelper.update`
`#global.Symbol`	导航到全局符号	`#global.Break`
`#TSL.function`	导航到 TSL 函数	`#TSL.add`

路由流程

100%

createNewIframe() 函数位于 docs/index.html573-668，处理所有路由逻辑。它在每次导航时替换 iframe 元素以确保干净状态，然后加载带锚点的相应页面。

iframe 链接拦截

setupIframeLinks() 函数位于 docs/index.html670-719，拦截文档页面内链接的点击，实现无需整页刷新的无缝导航：

获取 iframe 的文档：iframe.contentDocument
查找 iframe 中的所有 <a> 链接
对于指向 .html 文件的链接，阻止默认行为并更新父级哈希
将 BoxHelper.html#update 转换为哈希 #BoxHelper.update

旧版 URL 处理

该系统将旧版文档 URL 迁移到新格式以保持向后兼容。

旧版 URL 映射

100%

位于 docs/index.html50-90 的旧版 URL 处理器在页面加载时立即运行。它处理以下转换：

旧格式	新格式
#api/core/Object3D	#Object3D
#examples/loaders/GLTFLoader	#GLTFLoader
#api/BufferGeometryUtils	#module-BufferGeometryUtils
#api/Animation	#global

特殊映射处理重命名的类和命名空间变更。该函数在 IIFE（立即调用函数表达式）中加载时执行一次。

控制台沙箱集成

文档浏览器提供控制台沙箱，可直接从浏览器控制台测试 Three.js 代码。

<script type="module">
  import * as THREE from '../build/three.module.js';
  window.THREE = THREE;
</script>

此脚本位于 docs/index.html11-14，导入 Three.js 库并将其暴露为 window.THREE，允许用户在浏览文档时在浏览器开发者控制台中直接输入 new THREE.Vector3() 等命令。

搜索 URL 参数

搜索查询保存在 URL 查询参数中，以便共享和书签保存搜索结果。

URL 格式	行为
?q=vector	用 "vector" 预填搜索
?q=mesh%20light	用 "mesh light" 预填搜索
?q=vector#Vector3	显示搜索结果，展示 Vector3 页面

extractQuery() 函数位于 docs/index.html279-291，从 URL 中提取 q 参数。当搜索激活时，updateFilter() 通过 window.history.replaceState() 更新 URL 以包含查询字符串。

移动端响应性

文档浏览器适应移动设备，具有可折叠侧边栏。

移动端行为

桌面端	移动端
面板始终可见（300px）	面板默认隐藏
固定位置侧边栏	覆盖面板从右侧滑入
无展开按钮	汉堡菜单按钮
点击穿透面板	面板遮罩覆盖层阻挡内容

位于 files/main.css607-684 的 CSS 断点在 640px 以下转换布局：

@media all and ( max-width: 640px ) {
  #panel {
    height: var(--header-height); /* 折叠 */
  }
  #panel.open {
    height: 100%;               /* 展开 */
  }
  #contentWrapper {
    transform: translate3d(-380px, 0, 0); /* 滑入 */
  }
}

位于 docs/index.html124-129 的展开按钮切换 #panel 上的 .open 类。位于 docs/index.html131-136 的遮罩覆盖层（#panelScrim）提供半透明背景，点击时关闭面板。

模板生成

文档浏览器 HTML 在构建过程中从模板生成。

100%

位于 utils/docs/template/static/index.html1-739 的模板在第 39 行包含占位符 ，在文档构建期间被替换为分层导航链接。最终输出写入 docs/index.html。

导航结构组织为：

<h2> 用于顶级类别（Core, Addons）
<h3> 用于子类别（Animation, Math, Loaders）
<ul><li><a> 用于单个类链接

样式系统

文档浏览器使用双层 CSS 系统进行面板和内容样式设计。

CSS 文件	用途	作用域
files/main.css	面板布局、导航 UI、搜索结果	父页面
docs/styles/page.css	排版、代码块、表格	iframe 内容

CSS 变量

两个样式表使用 CSS 自定义属性进行主题和响应式设计：

:root {
  --panel-width: 300px;      /* 大屏幕 360px */
  --font-size: 16px;          /* 大屏幕 18px */
  --line-height: 26px;        /* 大屏幕 28px */
  --color-blue: #049EF4;
  --text-color: #444;         /* 深色模式 #bbb */
}

面板宽度通过 files/main.css451 的 padding-left: var(--panel-width) 影响 iframe 定位

深色模式支持

两个样式表使用 @media (prefers-color-scheme: dark) 和 docs/styles/page.css19-27 实现深色模式，调整以下颜色：

背景颜色
文本颜色
边框颜色
代码块背景

文档浏览器 ​

架构概览 ​

用户界面布局 ​

面板结构 ​

导航系统 ​

PageLinks 数据结构 ​

搜索系统 ​

搜索索引结构 ​

搜索流程 ​

搜索功能 ​

URL 路由与历史 ​

哈希格式 ​

路由流程 ​

iframe 链接拦截 ​

旧版 URL 处理 ​

旧版 URL 映射 ​

控制台沙箱集成 ​

搜索 URL 参数 ​

移动端响应性 ​

移动端行为 ​

模板生成 ​

样式系统 ​

CSS 变量 ​

深色模式支持 ​

文档浏览器

架构概览

用户界面布局

面板结构

导航系统

PageLinks 数据结构

搜索系统

搜索索引结构

搜索流程

搜索功能

URL 路由与历史

哈希格式

路由流程

iframe 链接拦截

旧版 URL 处理

旧版 URL 映射

控制台沙箱集成

搜索 URL 参数

移动端响应性

移动端行为

模板生成

样式系统

CSS 变量

深色模式支持