讲师孟德——易知微高级开发工程师1. 组件开发基础1.1. 组件化开发的价值与挑战在前端工程或大型项目中将复杂系统拆分为多个模块、再将每个模块细化为若干功能单元——每一个功能单元即可理解为一个组件。组件化开发之所以成为主流实践主要基于以下优点提升复用性通过抽象通用功能避免重复开发。例如一个项目中多个模块都需要选项卡切换功能可开发一个通用选项卡组件在各模块中直接复用大幅减少重复工作量提升构建效率。增强可维护性将功能封装为独立组件后若出现缺陷只需修改该组件的代码即可无需在每一个业务模块中逐一排查和调整。支持团队协作组件提供标准化的对外接口团队成员可以并行开发、相互调用整体开发效率随之提升。推动业务标准化组件的抽象过程有助于提炼业务共性形成可复用的资产库促进技术方案的统一。然而组件开发也面临诸多实际问题。仍以选项卡组件为例交互逻辑复杂选项卡的点击、切换需要与页面其他内容产生联动。不同模块中选项卡需要交互的元素各不相同模块A需联动元素a、b、c模块B需联动d、e、f。若直接在代码中编写交互逻辑流程会十分繁琐需在不同模块单独定义对应行为。数据源异构不同项目的数据来源差异巨大有的来自API接口有的是静态数据还有CSV文件、数据库直取等形式。一个组件需要兼容多种数据源内部就必须编写大量适配代码产生冗余和复杂度。样式调整依赖开发传统模式下组件基本由前端工程师通过代码实现。当设计师需要调整样式时常规流程是设计师输出设计稿 → 前端编写代码落地 → 设计稿变更 → 前端重新改代码、测试、上线。反复返工严重降低效率。图层管理能力不足带有计算能力的组件如飞线、点标记、路线路径往往存在多图层场景。如果没有合理的图层管理体系图层排布会变得混乱难以维护。1.2. EasyV组件如何解决上述问题EasyV组件通过一系列设计有效应对了上述挑战配置化样式面板将组件的功能抽象为配置项生成配置文件该文件可渲染出可视化样式配置面板。设计师可以直接在线调整组件样式如颜色、字体、布局无需前端修改代码。多数据源无缝切换组件支持静态数据、API接口、SQL、CSV等多种数据源平台自动处理数据格式转换组件根据数据内容动态渲染。例如选项卡的选项个数和文字完全由数据驱动。逻辑与配置分离组件的核心逻辑代码独立维护而样式、数据等动态部分通过配置文件开放给非开发人员降低了协作成本。子组件与图层管理针对GIS等复杂组件引入子组件机制。每个子组件独立管理自己的样式、数据和交互可动态添加、删除、排序解决多图层编排难题。在EasyV平台中每个组件右侧面板均分为“样式”“数据”“交互”三大部分。样式板块由配置文件生成修改后组件实时响应数据板块支持多种数据源修改后组件自动重新渲染交互板块则提供回调、自定义事件、自定义动作三大能力实现组件间通信。1.3. 组件目录结构常规EasyV组件项目包含以下核心文件package.json定义项目依赖、脚本命令等。组件入口文件如index.jsx或index.vue所有基础代码的起点。config文件夹main.json定义组件的配置项对应样式面板。main.data.json定义组件的静态数据对应数据面板的初始值。其他如样式文件夹、图片资源文件夹、工具函数文件夹等为可选内容按需创建。GIS组件由于图层众多通常还会包含多个子组件目录每个子组件拥有独立的manifest.json和manifest-data.json。1.4. 回调、自定义事件与自定义动作EasyV组件提供了三种标准的组件间通信机制1.4.1. 回调Callback回调用于实现组件间的数据传递。例如当选项卡切换时希望标题组件同步显示当前选项内容。具体做法在选项卡组件的配置中定义回调字段如content并设置自定义变量名。在目标组件标题中创建过滤器过滤器接收两个参数data组件自身静态数据和callbackArgs回调传递的参数。从callbackArgs中提取数据处理成目标组件所需的格式如数组并返回。切换选项卡时标题内容即同步更新。1.4.2. 自定义事件Custom Event自定义事件用于当前组件主动控制其他组件。配置步骤在当前组件如选项卡的交互面板中添加自定义事件设置触发条件如“状态改变”。选择执行动作如“显隐切换”“移动”“缩放”等平台默认动作或组件自定义动作。配置完成后触发事件即可控制其他组件的行为。1.4.3. 自定义动作Custom Action自定义动作允许其他组件控制当前组件的行为。例如点击标题组件使选项卡自动选中某一项。实现方式在当前组件选项卡中注册自定义动作如setSelectedItem。在控制方组件标题的自定义事件中选择目标组件选项卡及已注册的自定义动作并通过代码框返回参数如选中项的下标。当前组件监听该动作根据参数执行内部逻辑。这三种机制共同构成了灵活、解耦的组件通信体系既支持简单数据传递也支持复杂行为编排。2. 开发一个新组件2.1. 准备开发环境教程链接https://dtstack.yuque.com/easyv/vk5frm/onwyp2?singleDoc#2.2. 开发一个极简选项卡组件本次目标开发一个包含四个选项的选项卡组件选中项文字为红色未选中项为绿色颜色配置对外暴露支持设计师在线调整。2.2.1. 修改静态数据编辑main.data.json配置四个选项的内容例如[ { name: Tab A }, { name: Tab B }, { name: Tab C }, { name: Tab D } ]2.2.2. 修改配置项main.json当前配置面板为空需添加“选中颜色”和“未选中颜色”两个配置项。main.json中的base节点用于定义组件基础信息如初始宽高。配置项以数组形式定义在configuration节点下每个配置项对象包含name英文标识displayName中文显示名type配置项类型如color、text、number、select等value默认值添加如下配置{ name: selectColor, displayName: 选中颜色, type: color, value: #ff0000 }, { name: unselectColor, displayName: 未选中颜色, type: color, value: #00ff00 }保存后平台样式面板即出现对应颜色选择器。2.2.3. 编写组件逻辑在入口文件index.jsx中组件接收props参数包含data对应main.data.json中的数据configuration对应main.json中定义的所有配置项的值实现步骤使用useState定义selectIndex状态记录当前选中项下标。从configuration中解构出selectColor和unselectColor。循环渲染data数组生成选项列表根据当前下标是否等于selectIndex动态应用背景色或文字颜色。为每个选项绑定点击事件点击时更新selectIndex。保存代码后运行easyv dev启动本地开发服务即可在预览中看到选项卡组件点击切换时颜色正确变化。2.2.4. 添加回调能力为使组件能够向外部传递数据需添加回调配置。回调相关的配置必须写在main.json中name为interaction的配置项内部。示例{ name: interaction, displayName: 交互, children: [ { name: callbacks, displayName: 回调, type: array, value: [], template: { name: callback, displayName: 回调, value:[ { name: origin, displayName: 字段值, type: input, value: }, { name: target, displayName: 变量名, type: input, value: } ] } } ] }在组件代码中使用平台提供的onRelative函数发送回调。函数接收两个参数目标组件ID和回调数据。遍历configuration.interaction.callbacks中的配置根据当前选中项的数据构造callbackData调用onRelative向外传递。2.2.5. 添加自定义事件自定义事件的注册节点为triggers与configuration同级。示例triggers: [ { value: onTabChange, name: 选项卡切换 } ]在组件代码中从props解构出emit函数。在点击事件中调用emit(onTabChange, currentData)即可触发自定义事件。发布组件后用户可在交互面板中配置该事件触发的动作如显隐切换并可添加条件判断仅当传递的数据满足某条件时才执行。2.2.6. 添加自定义动作自定义动作的注册节点为actions同样与configuration同级。示例actions: [ { value: setSelectedIndex, name: 设置选中项 } ]在组件代码中使用useEffect添加事件监听。监听名称格式为动作标识_组件ID如setSelectedIndex_组件ID并在组件销毁时移除监听。监听回调的event对象包含data常规配置项静态数据和dynamicData代码框动态返回的数据。通常使用dynamicData调用setSelectIndex修改选中项。发布组件后其他组件即可通过自定义事件调用该自定义动作传入下标值控制选项卡选中状态。2.3. 组件发布与测试完成开发后执行easyv publish命令发布组件。填写测试环境域名/IP及更新日志即可。发布成功后在EasyV平台的组件列表中可找到该组件拖拽至大屏即可使用其样式、数据、交互配置。3. GIS组件开发规范GIS组件地理信息系统组件相比普通2D组件更为复杂需要遵循以下开发规范以确保功能完整、性能稳定。3.1. 图层管理能力动态增删图层GIS组件必须支持子图层的动态添加、删除和排序。用户应能通过平台界面对地图上的点、线、面、热力图等图层进行显示、隐藏、上移、下移或删除操作。子组件独立配置每个地图图层作为独立子组件拥有自己的样式、数据和交互配置。主组件的children字段定义可添加的子组件列表presentChildren定义默认自带的子组件。每个子组件的main.json中base.moduleName必须与主组件中children列表的标识完全一致否则无法识别。3.2. 基础地图交互支持地图拖拽、平移、缩放等常规操作。支持多种底图加载目前平台兼容Mapbox、XYZ等类型的底图服务。3.3. 初始化与渲染流程做好地图初始化、数据叠加、分层渲染等基础能力。通常在主组件入口中统一引入所有子组件代码根据配置动态渲染子图层。子组件的配置和数据从props的childrenConfig、childrenData字段中获取。3.4. 坐标系统一关键开发GIS组件前必须确认主地图框架所使用的坐标系以及子图层中点、线、面、标记等元素使用的坐标系。两者必须严格一致否则地理点位会显示错位。主流地图框架的坐标系差异Leaflet默认使用EPSG:3857Web墨卡托投影。Mapbox GL JS同样以EPSG:3857为主。OpenLayers可支持多种坐标系EPSG:4326、EPSG:3857等需显式配置。高德地图使用GCJ-02坐标系国测局加密坐标。百度地图使用BD-09坐标系在GCJ-02基础上二次加密。开发前应查阅对应官方文档确认坐标系参数并在代码中统一转换逻辑。3.5. 目录结构示例myGISComponent/ ├── index.jsx # 主组件入口 ├── config/ │ ├── main.json # 主组件配置 │ └── manifest-data.json # 主组件静态数据 ├── children/ # 子组件目录 │ ├── MarkerLayer/ │ │ ├── index.jsx │ │ ├── config/manifest.json │ │ └── config/manifest-data.json │ ├── PolylineLayer/ │ │ └── ... │ └── ... └── ...每个子组件独立维护主组件通过动态渲染机制加载。4. 注意事项及开发技巧4.1. 页面缩放系数的处理EasyV大屏存在页面缩放系数用户可设置整体缩放比例。该系数一般不影响样式展示但会干扰拖拽类交互逻辑。例如大屏缩放比例为0.8代码中设置元素向右移动10像素受缩放影响页面实际仅偏移8像素。若要使视觉上偏移10像素需计算10 / 0.8 12.5设置偏移12.5像素。获取缩放系数的方法大屏最外层容器ID为bigscreen-container读取该元素的style.transform属性中的scale值即可。4.2. 配置项编写优化原生编写配置项需要重复定义name、displayName、type、value等字段工作量较大。建议根据业务需求封装通用配置项生成函数。例如对于回调等通用结构也可统一封装为模板减少重复代码提升开发效率和一致性。4.3. 鼠标类事件绑定规则拖拽、滑动类组件的事件绑定需注意鼠标按下事件onMouseDown可以绑定在组件自身的DOM元素上。但鼠标移动onMouseMove和鼠标抬起onMouseUp事件必须绑定到document全局对象。如果仅绑定在组件元素上一旦鼠标移出组件范围移动和抬起事件就会失效导致交互异常。正确做法示例4.4. 其他实用技巧性能优化GIS组件中大量图层的渲染应考虑使用Web Worker或数据分页加载避免一次性加载过多数据导致卡顿。错误处理对数据源异常、坐标系转换失败等情况增加友好提示和降级方案。文档与示例为每个自定义组件编写清晰的README包含配置项说明、回调/事件/动作的用法并提供最小化示例。以上便是基于EasyV的自定义2D及GIS组件开发的核心内容。掌握这些基础概念、实操流程与规范技巧能够帮助开发者高效构建复用性强、可维护性高的组件并充分利用EasyV平台的低代码能力实现设计与开发的顺畅协作。后续如有问题欢迎通过线上渠道交流讨论。目前训练营课程已完结完整内容与案例资料已整理开放访问易知微官网加入交流群即可获取Web篇下期文章预告《定制化3D组件开发打造差异化孪生体验》易知微专注于AI数字孪生与数据可视化领域致力于将数据、业务与三维场景深度融合构建“数智视融合、虚实人联动”的数字化应用体系。依托自研数字孪生引擎与低代码可视化平台具备三维建模渲染、实时数据接入、仿真推演及业务联动等核心能力已服务智慧城市、能源、水利、交通、园区等多个行业的数千家客户。如果您有数据可视化、数字孪生或相关数智化项目需求欢迎访问易知微官网联系专业客户顾问获取专属解决方案与案例演示。