应用App

App是基于vjmap3d开发出的3d应用，他作为 vjmap3d 的核心，主要负责管理场景渲染, 事件交互等。

应用模块

App类本身基本上没有什么方法和属性，他是由以下应用模块 Module功能组合而成。

📌 模块成员是 mixin 注入：模块唤醒时经 applyMixinsTo(app, [...]) 把成员挂到 app 上。App.defaultModules（即下表全部模块，含 StatModule/CameraModule）不论是否传对应选项都会注入——只有用 options.modules 自定义模块列表去掉某模块时，对应 app.* 才不存在。getter 的值可能是 undefined（如未设 stat.show 时 app.showStat === undefined），但 app.showStat = true 照常生效；判断模块是否存在请用 app.getModule(vjmap3d.StatModule)，不要用 typeof app.showStat。

let svc = new vjmap3d.Service(env.serviceUrl, env.accessToken);
let app = new vjmap3d.App(svc, {
    container: "map", // 容器id
    scene: {
        gridHelper: { visible: true } // 是否显示坐标网格
    }
})
const ui = await app.getConfigPane();
let cfg = app.uiConfig
ui.appendChild(cfg)

信号事件

App 常用的信号事件如下：

📌 帧信号的派发机制：callModules("onAppUpdate") 是三通道扇出——同一调用同时派发 moduleManager.callModules（模块方法）、app.dispatch("onAppUpdate")（app.on 监听）和 app.signal.onAppUpdate.dispatch（signal .add 回调）。三条通道等价可用。注意 RAF 节流：页面不可见/无变化时帧率骤降（同一段 400ms 窗口回调 0~9 次），自动化验证勿按固定帧率断言，单帧确定性回调用 app.onNextFrame(cb)。 |onAppBeforeAddEntity|实体增加前回调| |onAppAddEntity|实体增加回调| |onAppBeforeRemoveObject|object3d对象移除前回调| |onAppRemoveObject|object3d对象移除回调| |onAppBeforeRemoveEntity|实体移除前回调| |onAppRemoveEntity|实体移除回调| |onContainerSizeChange|窗口大小变化事件| |onCameraControl|相机控件事件| |onCameraUpdate|相机更新事件| |onCameraChange|相机变化事件，当相机对象变化或远近裁剪面变化时触发| |contextMenuPreOpen|上下文菜单即将打开| |contextMenuOpened|上下文菜单已打开| |contextMenuNoContent|上下文菜单打开无内容| |contextMenuCancel|上下文菜单取消| |onCustomEvent|自定义事件| |onAddScene|新增场景| |onActiveScene|把场景置为当前| |onRemoveScene|移除场景|

示例： 响应点击事件，弹出信息

app.signal.onMouseClick.add(e => app.logInfo("您点击了下!", "success" , 1000))

let svc = new vjmap3d.Service(env.serviceUrl, env.accessToken);
        let app = new vjmap3d.App(svc, {
            container: "map", // 容器id
            // 渲染参数
            scene: {
                gridHelper: { visible: true } // 是否显示坐标网格
            },
            camera: {  // 相机设置
                viewHelper: { enable: true } // 是否显示视角指示器
            }
        })
        //
        app.signal.onMouseClick.add(e => app.logInfo("您点击了下!", "success" , 1000))

模块中常用方法属性

WebGLRendererModule

渲染引擎模块。模块参数 render 中可通过 engine 选择渲染引擎："webgl"（默认，WebGLRenderer）或 "webgpu"（WebGPURenderer，可配 forceWebGL: true 强制 WebGL2 后端，v2.0.0 起提供，旧版 1.0.23 仅 webgl）。浏览器不支持 WebGPU 时由 three 的 WebGPURenderer 自动降级为 WebGL2 后端（仍属 webgpu 引擎：app.renderer.isWebGPURenderer === true、仍只认 TSL/NodeMaterial）；只有 three/webgpu/three/tsl 动态加载失败、渲染器 init() 抛错或地图图层（map2d）模式时才回退到 webgl 引擎，详见 WebGPU 渲染引擎。

CSS2DRendererModule

css2d渲染引擎模块

CSS3DRendererModule

css3d渲染引擎模块

SceneModule

场景模块

EntityManagerModule

实体管理模块

StatModule

性能统计模块

CameraModule

相机模块

CoordSystemModule

坐标转换模块

⚠️ 屏幕位置无实体命中时 unproject / unprojectAsync 返回形态不一致——unproject 返回 null，而 unprojectAsync 返回一个 x/y/z 全为 undefined 的 Vector3（不是 null）。判空须用 v == null || v.x == null 之类写法兼容两者。

PickModule

拾取交互模块

InputModule

鼠标键盘输入模块

EntityQueryModule

实体查询模块

PostProcessModule

后期处理模块。webgpu 引擎下由 WebGPU 后处理模块自动接管，下列方法在 App 上保持同名可用（composer 返回的是兼容对象而非 pmndrs 的 EffectComposer，其 passes 恒为空数组；bloomEffect 只有 selection/intensity/luminanceThreshold，outlineEffect/selectedEffect 只有 selection/edgeStrength/visibleEdgeColor/hiddenEdgeColor/pulseSpeed；部分 postProcess 参数被忽略），详见 后期处理。

RectCollideModule

矩形碰撞检测模块

ToolStateModule

工具交互模块

CommandModule

命令模块

UiModule

UI界面模块

ParticleRenderModule

粒子效果模块

PhysicsManagerModule

物理引擎模块

生命周期补充

• app.destroy()：AppBase 上的方法，仅停止渲染循环并置 app.destroyed === true，不移除模块、不释放渲染器/canvas/window resize 监听。彻底销毁用 app.dispose()（先 removeAllModules() 再 destroy()，会 renderer.dispose() 并移除 canvas）。
• App 没有 resize 方法——画布尺寸只在 window 的 resize 事件（防抖）时按容器 clientWidth/clientHeight 更新，不监听容器元素本身（没有 ResizeObserver）。容器因布局变化（侧栏折叠、隐藏的 tab 变为显示）而 window 尺寸未变时不会自适应，需手动 window.dispatchEvent(new Event('resize'))。
• app.clearScenes()：清空所有场景但不销毁 app。
• app.toJSON()（d.ts 存在但文档未列）：对正常 new App() 实例直接调用抛 Cannot convert undefined or null to object——序列化依赖的内部状态未就绪时不可用，调用前需自行 try/catch。