# 动态组件服务 **Repository Path**: ice-gl/dynamic-component-service ## Basic Information - **Project Name**: 动态组件服务 - **Description**: dynamic-component-service（loadDynamicComponent） 是 tvt.js 生态下的一套动态组件发布、加载与调试解决方案。 它的核心目标是： 让 自研或第三方组件 可以 脱离 tvt.js 开源基座独立维护， 同时又能被 tvt.js 在线编辑器动态加载，获得完整编辑能力，并支持源码导出与二次开发。 - **Primary Language**: JavaScript - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: https://dcser.icegl.cn - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2025-12-26 - **Last Updated**: 2026-03-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: tvtjs, three, Threejs, 三维可视化, 数字孪生 ## README # dynamic-component-service（loadDynamicComponent） > 基于 **tvt.js** 生态的动态组件发布与加载服务 > Dynamic Component Service for tvt.js > 点击下方 👇🏻 预览地址：https://dcser.icegl.cn tres.js webgl three.js 📦 项目地址： 👉 [https://gitee.com/ice-gl/dynamic-component-service](https://gitee.com/ice-gl/dynamic-component-service) --- ## ✨ 项目简介 **dynamic-component-service（loadDynamicComponent）** 是 **tvt.js 生态下的一套动态组件发布、加载与调试解决方案**。 它的核心目标是： 让 **自研或第三方组件** 可以 **脱离 tvt.js 开源基座独立维护**， 同时又能被 **tvt.js 在线编辑器动态加载**，获得完整编辑能力，并支持源码导出与二次开发。 --- ## 🎯 设计目的 ### 1️⃣ 解耦商业组件与 tvt.js 基座 * 一些开发者的组件属于 **商业项目** * 不希望直接提交到 **tvt.js 开源仓库** * 希望组件 **独立发布、独立部署** * 但在生产项目中，仍然可以通过 **tvt.js 基座动态加载并使用** 👉 dynamic-component-service 提供了一种 **解耦但可集成** 的方案。 --- ### 2️⃣ 动态组件 + 在线编辑 + 源码导出 * 将 **自研或第三方代码** 简单封装成「动态组件」 * 挂载到 **tvt.js 在线三维场景编辑器** * 自动获得： * 组件参数可视化配置 * 与现有 **高级组件 / 模型库 / 场景系统** 联动 * 支持： * 在线调试与预览 * 导出组件配置 * **直接导出插件源码包** * 在 tvt.js 基座中进行 **二次开发** --- ## 🧱 技术栈说明 | 技术 | 说明 | | ------------------------------------ | -------------------- | | **Vue 3** | tvt.js 生态整体基于 Vue 3 | | **@originjs/vite-plugin-federation** | 动态组件发布与加载的核心机制 | | **Three.js** | 三维渲染基础 | | **Tres.js** | Vue + Three.js 的桥接方案 | | **@tresjs/cientos** | 常用 Three.js 高级组件集合 | --- ### 关于 vite-plugin-federation 本项目通过 **@originjs/vite-plugin-federation** 实现动态组件的 **发布 / 远程加载 / 模块共享**。 * 官方文档： 👉 [https://www.npmjs.com/package/@originjs/vite-plugin-federation](https://www.npmjs.com/package/@originjs/vite-plugin-federation) * 本项目中： * 已完成 federation 默认配置 * tvt.js 开源基座中也已配置好对应加载逻辑 * 只需简单配置，即可完成 **组件互通** --- ## 🚀 快速开始 ### 环境要求 * Node.js（推荐 LTS） * Yarn --- ### 获取代码 ```bash git clone https://gitee.com/ice-gl/dynamic-component-service cd dynamic-component-service ``` --- ### 安装依赖 ```bash yarn ``` --- ### 常用命令说明 #### 🔧 本地开发（仅调试） ```bash yarn dev ``` > ⚠️ **注意** > federation 动态组件机制 **不支持 dev 模式发布服务** > `dev` 仅用于本地组件页面调试 --- #### 📦 构建组件服务 ```bash yarn build ``` 构建完成后，可将产物部署到自己的服务器。 **注意事项：** 1. 当前版本仅支持 **域名根目录部署** 2. 请注意 **HTTP / HTTPS 跨域问题** * 建议提前了解 Web 服务跨域配置（CORS） --- #### 👀 本地预览（推荐） ```bash yarn preview ``` * 默认端口：`5000` * 启动后即可作为 **完整的动态组件服务** 可将该地址配置到： * tvt.js 开源基座 👉 [https://opensource.icegl.cn/#/plugins/loadDynamicComponent/readConfig](https://opensource.icegl.cn/#/plugins/loadDynamicComponent/readConfig) * 区域三维场景编辑器 👉 [https://oss.icegl.cn/p/zone3Deditor/#/plugins/zone3Deditor/index](https://oss.icegl.cn/p/zone3Deditor/#/plugins/zone3Deditor/index) 用于 **调试 / 编辑 / 开发**。 --- #### 🔁 热更新服务（推荐开发方式） ```bash yarn serve ``` 等价于： ```text yarn build + yarn preview（带监听） ``` * 文件改动自动重新编译 * 本地 5000 端口实时更新组件服务 --- ## 📂 项目结构说明 ```text ├── public/ # 静态资源 & 组件预览图 ├── src/ │ ├── common/ # 公共工具函数 │ ├── components/ # 动态组件目录 │ │ ├── common/ # 公共组件 │ │ └── simpleColumn/ # 示例组件目录（可自定义） │ │ └── dynamicRotatingBase.vue │ ├── router/ # 路由配置 │ │ ├── componentList # 服务说明 & 组件列表 │ │ └── previewEntry # 单组件预览调试 │ └── dcsConfig.ts # ⭐ 动态组件核心配置文件 ├── ... ``` > 其余文件均为标准 Vue 3 + Vite 项目结构， > 并已按 `vite-plugin-federation` 要求完成配置。 --- ## ⚙️ dcsConfig.ts 配置详解（核心） ./src 目录下的 `dcsConfig.ts` 是 **整个动态组件服务的核心配置文件** 原则上增加/修改完组件代码后，再更改`dcsConfig.ts`即可发布服务。 --- 如下为参考实例： ```ts const config = { name: 'baseSample', version: '1.1.0', description: '动态组件服务示例组件库', components: [ { name: '测试组件', type: 'testBase', comFile: './src/components/testBase.vue', previewPath: './preview/testBase.png', default: {}, defaultObject3D: {}, config: {}, }, ... ] } ``` --- ### 基础字段 ```ts name: string // 动态组件服务名称（仅支持英文） version: string // 服务版本号 description: string // 服务描述 ``` --- ### components（组件列表） ```ts components: [ { name: string type: string comFile: string previewPath: string defaultObject3D?: { ... } default?: { ... } config?: { ... } } ] ``` --- ### 单个组件字段说明 #### 🧩 基础信息 | 字段 | 说明 | | ------------- | -------- | | `name` | 组件名称 | | `type` | 组件唯一英文标识 | | `comFile` | 组件入口文件 | | `previewPath` | 组件预览图路径 | --- #### 🎯 defaultObject3D（可选） 默认 Three.js 物体参数（**仅支持** 位置 / 缩放 / 旋转）： ```ts defaultObject3D: { position: { x: 0, y: 0.2, z: 0 }, scale: { x: 0.5, y: 0.5, z: 0.5 }, rotation: { x: -Math.PI / 2, y: 0, z: 0 }, } ``` > 可只写其中任意项，或完全不写。 --- #### 🔧 default（组件默认参数） ```ts default: { color: '#ffffff', opacity: 1, // ...其他自定义参数 } ``` --- #### 🎛 config（参数 UI 配置） > 将自动生成 **在线编辑器配置面板** ⚠️ 字段必须与 `default` 一一对应。 ```ts config: { color: { name: '颜色', com: 'ColorPicker' }, type: { name: '类型', com: 'Select', options: ['imgA', 'imgB', 'imgC'].map(item => ({ label: item, value: item, })), }, videoLoop: { name: '视频重复', com: 'Switch' }, opacity: { name: '透明度', com: 'Slider', min: 0, max: 1, step: 0.01, }, jsonText: { name: '数据配置', com: 'jsonText', }, } ``` --- ### 当前支持的 UI 组件类型 | com | 说明 | | ------------- | -------- | | `ColorPicker` | 颜色选择器 | | `Select` | 下拉选择 | | `Switch` | 开关 | | `Slider` | 数值滑动条 | | `jsonText` | JSON 编辑器 | --- ## 🧩 总结 dynamic-component-service 是： * tvt.js 生态下的 **动态组件基础设施** * 实现： * 组件独立发布 * 动态加载 * 在线编辑 * 源码导出 * 二次开发 * 面向： * 商业项目 * 插件作者 * 三维应用开发者 ---