three-demos/注释说明.md

12/index.vue 详细注释说明

概述

已为 src/views/three/12/index.vue 文件添加了详细的中文注释，涵盖了所有关键代码部分。

注释内容分类

1. 文件头部注释

• 文件功能描述
• 主要特性列表（8大功能点）
• 作者信息和时间戳

2. 导入和变量声明注释

• 公共 Composables：详细说明每个导入函数的用途

  • useThreeScene() - 场景基础设置
  • useEnvironment() - 环境相关功能
  • useParticleSystem() - 粒子系统
  • usePostProcessing() - 后期处理
  • useThreeLighting() - 灯光系统

• 状态变量：按功能分类注释

  • Three.js 核心对象（场景、相机、渲染器等）
  • 粒子系统（蒸汽、火焰）
  • 火焰蔓延相关变量
  • 设备告警系统
  • 物体选择与信息显示
  • 射线检测

3. 核心函数注释

init() - 初始化函数

• 分为多个逻辑块，每个块都有标题注释：

  • 初始化公共工具函数
  • 创建场景
  • 创建环境背景
  • 创建相机
  • 创建渲染器
  • 创建控制器
  • 设置灯光系统
  • 创建地板
  • 设置后期处理
  • 初始化射线检测
  • 加载 3D 模型
  • 事件监听
  • 启动动画循环

• 每个配置参数都有说明

loadModel() - 模型加载函数

• 遍历模型子对象的处理逻辑
• 特定设备的识别和初始化
• 蒸汽和火焰效果的创建

spreadFire() - 火焰蔓延函数

• 蔓延算法说明
• 距离计算逻辑
• 阈值判断说明
• 中心大火触发条件

removeInitialFire() - 移除初始火焰

• 功能说明和调用时机

createCenterFire() - 创建中心大火

• 多层火焰效果的创建逻辑
• 四周火焰柱的配置
• 参数计算说明

animate() - 动画循环函数

• 各个系统的更新逻辑
• 火焰蔓延时间控制
• 告警闪烁效果计算
• 标签位置更新

updateLabelPosition() - 标签位置更新

• 3D 到 2D 坐标转换
• 屏幕像素坐标计算

onCanvasClick() - 点击事件处理

• 归一化设备坐标转换
• 射线检测逻辑
• 材质信息获取
• 轮廓描边设置

showDeviceDialog() - 显示设备弹窗

• 弹窗内容配置

clearSelection() - 清除选择

• 状态重置

toggleAlert() - 切换告警状态

• 开启告警的视觉效果
• 关闭告警的状态恢复

toggleParticles() - 切换蒸汽效果

• 粒子发射器控制

toggleFlame() - 切换火焰效果

• 火焰系统的完整启停逻辑
• 状态重置和资源清理

closeDialog() - 关闭弹窗

onResize() - 窗口大小变化处理

• 相机和渲染器尺寸更新

生命周期钩子

• onMounted - 组件挂载时初始化
• onUnmounted - 组件卸载时资源清理

4. 模板部分注释

• Three.js 渲染容器：说明用途
• 物体信息标签：
  • 显示时机
  • 位置动态跟随
  • 内容结构（名称、材质、坐标）
• 设备详情弹窗：
  • 触发条件
  • 告警/正常状态展示
  • 关闭逻辑
• 控制面板：
  • 场景特性列表
  • 设备控制按钮
  • 交互说明
  • 技术信息

5. 样式部分注释

• 文件级说明：主题色和样式分类
• 物体信息标签：
  • 定位和动画
  • 内容样式
• 弹窗：
  • 遮罩层和主体
  • 告警状态特殊样式
  • 动画效果
• 控制面板：
  • 布局和定位
  • 按钮样式和交互效果
  • 自定义滚动条

注释特点

1. 结构清晰：使用分隔线和标题组织注释
2. 说明详细：不仅说明"是什么"，还说明"为什么"
3. 中文友好：所有注释均使用中文
4. 参数说明：配置项都有注释解释
5. 逻辑分组：相关代码按功能分组并添加标题注释

涉及的技术点

1. Three.js 核心：场景、相机、渲染器、控制器
2. 模型加载：GLTFLoader
3. 粒子系统：蒸汽效果、火焰效果、火焰蔓延
4. 后期处理：轮廓描边（OutlinePass）
5. 射线检测：物体点击选择
6. 材质系统：发光效果（emissive）
7. 动画系统：requestAnimationFrame 循环
8. 坐标转换：3D 世界坐标到 2D 屏幕坐标
9. Vue 3：Composition API、响应式状态、生命周期钩子
10. CSS 动画：淡入、滑入、脉冲动画

使用的公共 Composables

1. useThreeScene() - 场景、相机、渲染器、控制器的创建
2. useEnvironment() - 天空盒、地板、网格、流动光效
3. useThreeLighting() - 多光源照明系统
4. usePostProcessing() - 后期处理合成器和效果
5. useParticleSystem() - 粒子发射器（蒸汽、火焰）

文件统计

• 总行数：约 1260 行
• 注释覆盖：
  • 脚本部分：每个函数和重要代码块都有注释
  • 模板部分：每个主要组件都有说明
  • 样式部分：添加了分类和关键样式说明