概述nVisual 支持通过 URL 查询参数精确控制视图的打开行为。只需构造特定格式的链接即可从外部系统直接跳转到 nVisual 的指定视图、高亮目标对象、锁定相机位置甚至自动触发搜索。适用场景从 CMDB、网管系统、工单系统等外部平台生成链接一键跳转到 nVisual 的精准定位视图。基础入口所有深链以diagram.html为基础入口https://{nVisual 域名}/diagram.html?id{视图ID}参数通过 URL Query String 方式拼接多个参数用连接。完整参数速查表参数类型必填说明示例值idnumber/string✅目标视图DiagramID24000000000001blinkstring❌需要高亮闪烁的目标对象 ID24000000000001viewstring❌视图渲染模式2dXnumber条件相机 X 坐标与view配套350.5Ynumber条件相机 Y 坐标与view配套220.0Znumber条件相机 Z 坐标3D 模式必需50zoomnumber条件缩放级别与view配套1.2centerXnumber❌视口中心 X 偏移0centerYnumber❌视口中心 Y 偏移0centerZnumber❌视口中心 Z 偏移0mapJSON string❌地图模式定位参数支持经纬度{center:[x,y],zoom:12}xnumber❌地图经度 / 投影 X 坐标116.404ynumber❌地图纬度 / 投影 Y 坐标39.915mapZoomnumber❌地图缩放层级12searchBusinessstring❌触发业务搜索传1即生效1businessNamestring❌搜索关键词与searchBusiness配套核心交换机editableboolean❌是否允许编辑传false关闭编辑falseisShareboolean❌是否为分享模式true参数分类详解一、id— 目标视图最重要的参数。每个 Diagram视图在 nVisual 中都有唯一 ID通过此参数指定要打开的视图。diagram.html?id24000000000001如果 URL 中不传id或传入无效值nVisual 会自动回退到顶层视图。二、blink— 目标对象高亮视图加载完成后自动高亮并居中显示指定对象是最常用的深链定位手段。diagram.html?id24000000000001blink24000000000001行为说明视图模式高亮行为普通 2D 视图画布自动居中到目标对象目标对象持续闪烁地图模式地图自动飞行至目标对象的经纬度目标对象持续闪烁注意blink参数为一次性消费闪烁完成后自动从 URL 中移除。用户刷新页面不会再次触发闪烁。目标对象 ID 的获取方式在 nVisual 中选中图元通过postMessage的nvisualPatrolSelectedNodeIdList消息获取参见《通过 postMessage 获取 nVisual 状态》通过 nVisual 的搜索 API 查询对象列表从 nVisual 导出数据中获取三、view/X/Y/Z/zoom— 视图模式与相机位置精确控制视图的渲染模式和初始视角实现打开即定位。diagram.html?id24000000000001view2dX350.5Y220.0zoom1.2view取值值渲染模式必需配套参数2d/2D2D 平面视图X,Y,zoom3d/3D3D 立体视图X,Y,Zmap地图模式X,Y,zoomname名称模式X,Y,zoommodel型号模式X,Y,zoomperson人物视角X,Y,Z参数校验缺少必需参数时nVisual 会忽略view设置回退到该视图的默认渲染模式和默认视角。centerX/centerY/centerZ视口中心偏移量可选参数默认为0。四、map/x/y/mapZoom— 地图定位专为地图模式设计的精确定位参数。方式一JSON 格式diagram.html?id24000000000001map{center:[116.404,39.915],zoom:14,isLonLat:true}字段类型说明center[number, number]中心点坐标zoomnumber地图缩放级别isLonLatboolean坐标是否为经纬度。true时自动转为投影坐标false或省略时按投影坐标处理方式二简单参数diagram.html?id24000000000001x12950000y4850000mapZoom12适合与blink配合使用当目标对象在地图模式下的自身坐标不可用时nVisual 从x/y/mapZoom参数中读取定位信息。五、searchBusiness/businessName— 自动触发搜索打开视图后自动展开左侧搜索面板填入关键词并触发搜索。diagram.html?id24000000000001searchBusiness1businessName汇聚交换机参数说明searchBusiness1触发自动搜索传任意非空值即可businessName搜索关键词六、editable/isShare— 权限与模式控制diagram.html?id24000000000001editablefalseisSharetrue参数说明editablefalse以只读模式打开视图禁止编辑、拖拽、删除图元isSharetrue标记为分享链接深链场景示例场景 1告警定位网管系统产生告警运维人员点击告警直接跳转到 nVisual 中对应设备所在视图并高亮。diagram.html?id24000000000001blinkSW-CORE-01场景 2工单关联工单系统关联设备变更点击查看拓扑以 2D 模式打开指定视图并定位。diagram.html?id24000000000001view2dX350Y220zoom1.5editablefalse场景 3GIS 地图定位从资产管理平台跳转到 nVisual 地图视图定位到指定经纬度。diagram.html?id24000000000001viewmapmap{center:[116.404,39.915],zoom:14,isLonLat:true}场景 4模糊搜索入口从 CMDB 搜索页面带关键词跳转到 nVisual 自动执行搜索。diagram.html?id24000000000001searchBusiness1businessName核心交换机场景 5组合使用只读分享链接打开视图 → 高亮设备 → 禁止编辑diagram.html?id24000000000001blinkSW-A3-01editablefalseisSharetrue外部系统集成代码JavaScript 深链构造器/** * 构造 nVisual 深链 * * param {object} options * param {number} options.id - Diagram ID必填 * param {string} [options.blink] - 高亮对象 ID * param {string} [options.view] - 视图模式: 2d | 3d | map | name | model * param {number} [options.x] - 相机 X 坐标 * param {number} [options.y] - 相机 Y 坐标 * param {number} [options.z] - 相机 Z 坐标3D 必需 * param {number} [options.zoom] - 缩放级别 * param {number} [options.centerX] - 视口中心 X 偏移 * param {number} [options.centerY] - 视口中心 Y 偏移 * param {object} [options.map] - 地图定位 { center, zoom, isLonLat } * param {boolean}[options.editable] - 是否可编辑 * param {string} [options.businessName]- 搜索关键词 * returns {string} 完整的深链 URL */functionbuildNvisualDeepLink(options){constbaseUrlhttps://{nVisual 域名}/diagram.html;constparamsnewURLSearchParams();// 必填if(!options.id)thrownewError(id 为必填参数);params.set(id,options.id);// 高亮if(options.blink)params.set(blink,options.blink);// 视图模式if(options.view)params.set(view,options.view);if(options.x!null)params.set(X,options.x);if(options.y!null)params.set(Y,options.y);if(options.z!null)params.set(Z,options.z);if(options.zoom!null)params.set(zoom,options.zoom);if(options.centerX!null)params.set(centerX,options.centerX);if(options.centerY!null)params.set(centerY,options.centerY);// 地图定位if(options.map)params.set(map,JSON.stringify(options.map));// 权限模式if(options.editablefalse)params.set(editable,false);// 搜索if(options.businessName){params.set(searchBusiness,1);params.set(businessName,options.businessName);}return${baseUrl}?${params.toString()};}使用示例// 场景1告警定位constalarmLinkbuildNvisualDeepLink({id:24000000000001,blink:SW-CORE-01,});window.open(alarmLink,_blank);// 场景2工单只读查看constticketLinkbuildNvisualDeepLink({id:24000000000001,view:2d,x:350,y:220,zoom:1.5,editable:false,});document.getElementById(nvisual-frame).srcticketLink;// 场景3GIS 定位constgisLinkbuildNvisualDeepLink({id:24000000000001,view:map,map:{center:[116.404,39.915],zoom:14,isLonLat:true},});window.open(gisLink,_blank);// 场景4搜索入口constsearchLinkbuildNvisualDeepLink({id:24000000000001,searchBusiness:1,businessName:核心交换机,});window.open(searchLink,_blank);// 场景5分享链接constshareLinkbuildNvisualDeepLink({id:24000000000001,blink:SW-A3-01,editable:false,isShare:true,});copyToClipboard(shareLink);与 postMessage 的配合使用深链负责初始定位postMessage负责运行时通信。两者结合可实现完整的交互闭环// 父窗口集成代码 constnVisualFramedocument.getElementById(nvisual-frame);// 1. 初始加载通过 URL 参数定位functionopenNvisual(diagramId,highlightNodeId){nVisualFrame.srcbuildNvisualDeepLink({id:diagramId,blink:highlightNodeId,editable:false,});}// 2. 运行时跳转通过 postMessage 发送 jumpTo 指令无需刷新 iframefunctionjumpToDiagram(diagramId){nVisualFrame.contentWindow.postMessage({type:DASHBOARD-EVENT,event:jumpTo,id:diagramId,},*);}// 3. 监听 nVisual 状态变化window.addEventListener(message,(event){const{type,value}event.data||{};// 视图切换时外部系统同步更新if(typenvisualPatrolDiagramIdList){updateExternalBreadcrumb(value);}// 用户选中图元时外部系统可同步展示详情if(typenvisualPatrolSelectedNodeIdList){showSelectedInfo(value.nodeIdList,value.linkIdList);}});// 示例外部告警 → 一键定位 nVisualfunctiononAlarmClicked(alarm){openNvisual(alarm.diagramId,alarm.deviceNodeId);}注意事项blink一次性消费高亮完成后自动从 URL 移除刷新不会再次闪烁。如需每次打开都高亮每次重新构造链接即可。view仅首次加载生效仅在 iframe 初始加载时读取内部视图跳转后不会重新应用。坐标系统map参数中若使用经纬度务必设置isLonLat: true若已是投影坐标省略此字段即可。History 路由模式nVisual 使用 History 模式URL 中不含#。如将 nVisual 作为独立页面部署需确保 Web 服务器配置了 SPA fallback。跨域如果父窗口与 nVisual 不同源通过postMessage通信时注意校验event.origin。
