讲师天瀑——易知微高级开发工程师在数字孪生应用日益普及的今天不同行业、不同项目对三维可视化呈现的需求千差万别。通用组件虽然能满足大部分常规场景但面对温度阵列展示、有限元结构建模、热力图渲染或体渲染烟雾等特殊需求时我们必须拥有自主扩展的能力。这正是EasyTwin平台赋予开发者的重要价值——通过定制化3D组件开发打造真正差异化的孪生体验。本文将基于EasyTwin平台的组件开发实践从平台简介、环境配置、架构剖析、蓝图交互到进阶案例全方位梳理整个开发流程帮助读者建立起从入门到精通的系统认知。一、EasyTwin平台简介低代码数字孪生的核心能力EasyTwin是一个低代码数字孪生开发平台采用B/S架构旨在让开发者乃至设计师都能以极低的门槛构建三维交互场景。它的核心设计理念是“重塑开发体验”将传统的“代码拼装”模式转变为“一站式平台”服务。在场景构建层面EasyTwin支持直接拖拽FBX或GLB格式的模型文件进入场景进行实时预览无需编写任何加载代码。渲染方面平台内置了完善的天空系统、光照环境及后期特效这些效果全部通过零代码的配置面板即可完成调整即便没有图形学背景的用户也能快速获得精美的视觉输出。平台最引人注目的功能当属“蓝图交互系统”它实现了EasyTwin与EasyV之间的双向通信。简单来说用户可以通过EasyV前端的图表、按钮、下拉菜单等控件去控制EasyTwin三维场景中模型的运动、动画的启停、材质的切换甚至相机视角的定位。这种数据驱动与可视化联动的机制让数字孪生不再只是静态的模型展示而是真正可交互、可响应的智能系统。之所以选择基于EasyTwin引擎进行开发是因为它内置了多项关键能力资源管理器可以轻松读取模型、贴图、HDR等资源无需手动管理加载队列高效的渲染系统借助实例化技术能够稳定渲染数百万个粒子而保持流畅帧率蓝图化的交互系统让设计师也能通过连线方式完成场景联动极大降低了协作门槛同时平台提供了大量精美的正式组件覆盖了绝大多数通用需求。然而在实际项目中客户往往有独特的定制化诉求比如温度场阵列的可视化、ANSYS导出的结构网格建模、烟雾体渲染等这些通用组件无法覆盖因此自定义组件开发便成了项目落地的关键环节。二、环境配置及开发前准备在正式开始编码之前我们需要正确配置本地开发环境。1.首先确保Node.js版本高于18因为整个工具链依赖pnpm进行包管理。如果本地有多个Node版本共存建议安装nvm进行版本切换避免冲突。安装pnpm的方法参考官方文档即可。教程可见nvm安装教程-CSDN博客安装完成后我们通过一条命令创建monorepo仓库pnpm create easytwin-component 仓库名2.这条命令会在当前路径下生成一个同名文件夹内部已经包含了基础的仓库结构和配置文件并且会自动从npm查询并写入easytwin-runtime和runtime-frontend的最新版本。由于网络原因这一步可能需要多次尝试才能成功。仓库创建完成后进入该目录并执行pnpm i安装所有依赖项这一步至关重要因为后续的所有脚手架命令和工具包都依赖这些本地模块。3.依赖安装完毕后我们就可以创建第一个组件了。使用pnpm easytwin-cli create 组件名命令例如pnpm easytwin-cli create ExampleAaa会在packages目录下生成一个以easytwin-components-example-aaa命名的文件夹这就是我们组件的全部源码存放位置。每个组件独立成包互不干扰便于管理和版本控制。在发布组件之前必须配置AccessKey这是上传到线上环境的身份凭证。获取方式是在EasyTwin的场景编辑页中点击“调试工具”并选择“获取Access Key”确保当前用户角色拥有相应权限。复制该Key后通过命令行执行pnpm easytwin-cli key -s 粘贴的key -m 环境其中环境可选dev、test、prod或pre。需要注意的是Windows系统下使用PowerShell粘贴时可能出现数据不正确的问题此时建议手动将Key写入.vscode目录下对应的环境文件中如access_key.test.json。不同环境的Key彼此独立务必要在对应环境下获取。最后为了验证整个链路是否通畅我们可以在package.json中找到upload命令并执行。但要注意默认的upload命令指向正式组件我们需要在命令后追加--source officialCustom标识让平台识别这是定制组件而非内置组件。这样首次上传成功后就完成了环境的全部配置接下来便可以专注于组件逻辑的开发了。三、组件架构深度剖析生命周期、配置面板与核心管理器运行时组件一个标准的自定义组件目录下核心文件集中在core文件夹中。其中ExampleComponent.ts是主逻辑类initState.ts负责为配置项提供默认值config.ts声明了配置面板上的UI结构setting.ts定义组件名称、分类、版本和唯一类型标识。每次发布新版本时setting.ts中的version字段必须递增否则服务器会拒绝上传。同时type字段必须全局唯一否则会覆盖已有组件。组件的生命周期函数是驱动一切行为的基础。引擎为每个组件提供了一系列按特定时机调用的钩子开发者可以根据需求选择合适的钩子实现业务逻辑。具体包括onInitialize在帧循环前调用无论组件是否处于激活状态。这是绑定蓝图事件、初始化资源、加载模型的最佳入口因为此时可以安全访问到组件的根节点sceneObjectThree.js的Object3D对象以及引擎的camera、scene、renderer等核心对象。onAwake同样在帧循环前调用但仅在组件active为true时执行若初次为false则延迟到第一次激活时调用且整个生命周期只会调用一次。onStart在帧循环最开始调用也仅执行一次适合放置那些只需运行一次的初始化代码。onUpdate每帧调用一次晚于onStart通常在此处理持续更新的逻辑比如动画插值、Uniforms参数变化等。参数dt为与上一帧的时间间隔秒可用于实现帧率无关的运动。onFixedUpdate以固定间隔目前设定为60FPS调用适合处理物理模拟或需要稳定步长的计算如粒子系统的状态迭代。onEnable当组件变为可见时调用即activeInScene为true。onDisable当组件变为隐藏时调用activeInScene为false。onDestroy组件被销毁时调用在此必须手动释放所有监听器、几何体、材质等资源防止内存泄漏。组件提供了两个重要的活动状态属性active表示本地的激活状态与世界大纲中的显隐图标直接对应而activeInScene表示全局激活状态它受父子层级影响——只有所有父级和自身active均为true时activeInScene才为true并且其变化会自动触发onEnable或onDisable回调。组件配置面板配置面板的渲染完全由config.ts驱动。在该文件中StateSchemaFunc函数返回一个数组数组的每一项都是一个UI组件的描述对象。引擎内置了丰富的UI类型如inputNumber数字输入框、inputVector3三维向量输入、select下拉选择框、colorPicker颜色选择器等这些类型均来自UIGenerator模块该模块位于packages/easytwin-runtime-frontend/src/UIGenerator/uicomponents提供了完善的TypeScript注释开发者可以在编写schema时直接查看类型提示。如果需要更自由的布局也可以使用custom类型嵌入自己编写的Vue或React组件但此时数据的双向绑定需要自行实现。Manager引擎实现了一些提供给组件使用的Manager除了生命周期和配置引擎还提供了多个实用的Manager方便组件与平台核心能力交互。最常用的是ResourceManager通过this.engine.getManager(ResourceManager)即可获取它提供了loadModelAsync加载模型、loadTextureAsync加载贴图、loadHDRTextureAsync加载HDR环境贴图等异步方法极大简化了资源加载流程。另一个是InputManager用于管理键盘和鼠标操作例如检测空格键是否被按下适用于需要用户交互的场景。这些Manager的抽象让开发者无需关心底层实现细节专注于业务逻辑本身。值得特别说明的是数字要素组件它与普通组件在架构上有明显区别。数字要素的core目录下除了component外还有一个childComponent这就是点击“新增子要素”时所实例化的模板。数字要素本身不保存子元素的状态而是通过virtualChildren数组管理所有子实例并在onRenderState中遍历每个子要素调用其refresh方法完成更新。这种设计使得数字要素非常适合动态增删子对象的场景比如批量创建信息面板、动态生成标签阵列等。四、蓝图交互系统连接三维场景与前端应用蓝图是EasyTwin与EasyV进行通信的桥梁它让组件能够以可视化方式暴露自己的“事件”和“动作”从而与EV端的图表、按钮等控件联动形成完整的交互链路。在蓝图上一个组件节点可以拥有两类端口动作Action代表组件可以接收的外部输入在蓝图上表现为左侧的输入引脚。其他节点可以通过连线触发该动作组件内部则通过监听对应的事件名称来执行逻辑。事件Event代表组件在某个时刻主动向外发出通知在蓝图上表现为右侧的输出引脚。当组件内部调用发送方法后后续节点会依次被执行。要为一个组件添加蓝图能力首先需要在组件根目录下新建blueprint.json文件其结构为一个包含name、events和actions三个字段的对象。其中name与组件的settings.name保持一致便于识别events和actions均为数组每个元素包含name显示名称和value内部标识符。例如定义一个“隐藏测试”动作其value为hideTest那么在组件的onInitialize中我们就可以调用this.addEasyvEventListener(hideTest, callback)来注册监听器当蓝图触发该动作时回调函数便会执行。发送事件同样简单使用this.emitEasyvFunc(eventName, data)方法即可。data是一个对象可以包含任意字段蓝图会将它们传递给下游节点。为了保证易用性引擎还支持在fields字段中为每个参数添加详细说明。fields是一个数组每一项包括id字段名、desc字段描述和type数据类型这些信息会显示在EasyV蓝图面板的小问号提示中极大方便了团队协作——使用组件的同事无需翻看源码即可知道每个参数的含义和格式。在实现蓝图交互时有一个容易被忽视但至关重要的细节内存管理。每一个addEventListener注册的监听器都会占用内存如果组件被频繁创建销毁或者场景中有多个实例必须要在onDestroy生命周期中调用this.removeEasyvEventListener(value)移除对应的监听器。同时如果监听器中引用了外部对象如场景中的网格也要一并释放其几何体和材质。只有做到“有始有终”才能确保长时间运行时不会出现内存泄漏导致页面卡顿甚至崩溃。蓝图不仅让组件具备了可编排的能力更重要的是它打通了三维世界与前端数据看板的界限。比如我们在EV端放置一个按钮用户点击按钮后蓝图将“点击”事件连接到三维组件的“旋转”动作即可实现按钮控制模型旋转反之当模型被鼠标悬停时组件触发“悬停”事件蓝图再连接到一个弹出面板显示模型的详细信息。这种双向互动正是数字孪生应用最具魅力的地方。五、从零到一开发实战亲手实现一个可交互组件理论铺垫之后我们通过一个完整的开发实例来串联所有知识点。假设我们已经按照第二部分配置好了环境并创建了一个名为ExampleAaa的组件。首次上传成功后在场景的自定义组件列表中将其拖入场景会发现它默认显示一个立方体Box配置面板中有“网格类型”的下拉选项但切换并没有实际效果因为对应的逻辑尚未实现。第一步我们来实现网格类型的切换功能。打开core/ExampleComponent.ts找到onRenderState方法该方法接收的state参数即为当前配置项的状态对象。在config.ts中查看meshType字段的定义发现其uiType为select可选值为cube和sphere。因此在onRenderState中我们只需解构出meshType然后判断其值若为sphere则删除当前的立方体新建一个球体并赋值给this.sceneObject若为cube则做相反操作。注意不能简单地将新物体直接添加到this.scene因为this.scene是引擎的全局场景而每个组件有自己的根节点this.sceneObject应当操作后者以避免影响其他组件。同时每次新建物体前务必对旧物体的几何体和材质调用dispose()方法这是Three.js内存管理的基本准则。第二步我们新增一个控制物体缩放的配置项。在config.ts的StateSchemaFunc数组中追加一项类型为inputNumberfieldName设为scalelabel设为“缩放”。然后在ExampleComponentStateConfig接口中补充scale?: number再在initState.ts中为其赋默认值如1.0。最后回到onRenderState在更新逻辑中读取state.scale并应用到this.sceneObject.scale.setScalar(scale)。重新发布记得更新version刷新场景后即可在配置面板中看到新的“缩放”输入框调整数值时立方体或球体的大小会实时变化。第三步我们加上拖拽移动功能。默认情况下自定义组件在场景中是无法拖拽的因为引擎的变换控制器TransformControls需要监听拖拽结束事件。在onRenderState中我们找到onTransformControlDragEnd回调当拖拽结束时newState中包含了最新的position和rotation我们需要将这些值同步到state中并调用this.setState(newState)触发更新。这样用户拖拽组件后配置面板中的位置和旋转数值也会同步刷新并且再次发布后拖拽功能就永久生效了。最后我们为这个组件添加一个蓝图动作比如“隐藏/显示”切换。在blueprint.json的actions中添加一项{ name: 切换显隐, value: toggleVisible }然后在onInitialize中注册监听器this.addEasyvEventListener(toggleVisible, () { this.sceneObject.visible !this.sceneObject.visible; })。这里要注意visible是Three.js原生的属性但引擎推荐使用this.active或this.sceneObject.active来控制显隐因为后者会触发生命周期钩子保持状态一致性。不过简单演示中直接操作visible也可行。发布后在EasyV的蓝图中拖出该组件的节点从按钮的“点击”事件连线到“切换显隐”动作保存并预览点击按钮就能看到三维组件的显隐切换了。通过这个完整的从零到一流程我们不仅掌握了组件开发的基本范式还熟悉了配置项扩展、状态更新、拖拽交互和蓝图联动的全部环节。这些步骤在后续更复杂的组件开发中会反复出现形成肌肉记忆后开发效率将大幅提升。六、进阶案例后处理、文字贴图与自定义材质的实战技巧掌握了基础开发之后我们来看看几个来自实际项目的高阶需求它们展示了如何利用引擎的底层机制实现更具视觉冲击力和实用价值的效果。案例一双屏渲染后处理在某项目中客户希望同时展示宏观地形与局部细节——上半屏固定显示某个俯瞰视角下半屏跟随相机自由漫游。这本质上是后处理管线的定制。我们通过继承Three.js的Pass类编写了一个HalfScreenPass在render方法中通过scissor和viewport裁剪渲染区域将场景分别渲染到屏幕的上下两部分。在组件的onInitialize中通过this.engine.postProcessingComponent获取后处理组件实例再拿到其内部的effectComposer然后移除默认的RenderPass插入我们的HalfScreenPass并保留泛光Bloom和外描边Outline等后续Pass。为了增强灵活性我们还通过蓝图暴露了“启用/关闭双屏”和“调节分屏比例”的动作用户可以在EV端动态控制这些参数。这个案例展示了如何将Three.js的后处理生态无缝集成到EasyTwin中关键在于正确操作effectComposer的Pass队列以及利用this.hook机制将配置项的更新拆分为独立监听避免频繁重建渲染管线从而保障性能。案例二Canvas生成的文字标识在测绘类场景中我们经常需要在地面或墙面上标注距离或编号。使用Three.js的Sprite虽然简单但永远面向相机的特性在某些设计风格下显得不够自然。我们的方案是创建一个平面网格PlaneGeometry然后使用Canvas绘制文字生成纹理并作为网格材质的map。在更新文字内容时重新绘制Canvas并标记texture.needsUpdate true即可实现动态刷新。这个方法的优势在于文字完全固定在世界坐标系中可以随场景旋转俯仰更具真实感。我们在组件中封装了一个CanvasTextMesh类支持设置字体大小、颜色、背景透明等参数并提供了便捷的updateText(text)方法极大简化了标签类组件的开发。案例三基于ShaderMaterial的体渲染烟雾工业仿真中经常需要展示粉尘扩散、气流流动等效果这些往往需要体渲染技术。在EasyTwin中我们直接使用Three.js的ShaderMaterial编写自定义着色器将体数据如噪声纹理传入片元着色器通过光线步进Ray Marching算法生成半透明的烟雾体积。在顶点着色器中我们传递模型的UV坐标和世界位置片元着色器中则根据时间uniform和噪声采样计算密度场最终与场景颜色混合。每帧在onUpdate中更新timeuniform烟雾便会缓缓流动。为了提升性能我们还将计算部分移到GPU通过GPUComputationRenderer实现粒子位置的迭代这个工具类同样从Three.js官方示例中移植而来只需要注意版本匹配即可。这个案例充分体现了自定义材质和着色器编程在视觉差异化上的巨大潜力。这些进阶案例并非孤立的炫技而是切实解决项目中的真实痛点。它们的共同思路是深入理解EasyTwin对Three.js的封装边界在需要时大胆穿透抽象层直接操作底层对象如effectComposer、shaderMaterial、canvas等同时利用平台提供的生命周期和管理器来确保集成后的稳定性和性能。七、总结与建议定制化3D组件开发本质上是基于EasyTwin平台强大的底层能力和灵活的扩展机制将业务需求转化为可视、可交互的三维功能模块。从环境配置到架构理解从蓝图联调到进阶渲染每一步都有章可循。回顾整个知识体系有几个要点值得反复强调版本管理是生命线每次发布前务必递增version且type不可重复。配置项的声明必须与TypeScript类型和初始值三者同步否则编辑器会报错影响开发效率。内存释放不可忽视每一个addEventListener、每一个new Geometry和new Material都应当在onDestroy中清理干净。蓝图参数的fields说明一定要写详细这不仅是文档更是团队协作的润滑剂。当内置UI类型不足时大胆使用custom并嵌入自定义组件但要注意数据流的一致性。最后希望本文能帮助开发者建立起对EasyTwin组件开发的系统认知并在实际项目中灵活运用这些技术打造出真正差异化、高价值的数字孪生应用。随着平台能力的持续迭代定制化开发的想象空间也将不断扩大期待大家在实践中创造出更多精彩的作品。