nVisual 二次开发：URL 参数体系与深链跳转

概述

nVisual 支持通过 URL 查询参数精确控制视图的打开行为。只需构造特定格式的链接，即可从外部系统直接跳转到 nVisual 的指定视图、高亮目标对象、锁定相机位置，甚至自动触发搜索。

适用场景：从 CMDB、网管系统、工单系统等外部平台生成链接，一键跳转到 nVisual 的精准定位视图。

基础入口

所有深链以diagram.html为基础入口：

https://{nVisual 域名}/diagram.html?id={视图ID}

参数通过 URL Query String 方式拼接，多个参数用&连接。

完整参数速查表

参数分类详解

一、id— 目标视图

最重要的参数。每个 Diagram（视图）在 nVisual 中都有唯一 ID，通过此参数指定要打开的视图。

diagram.html?id=24000000000001

如果 URL 中不传id或传入无效值，nVisual 会自动回退到顶层视图。

二、blink— 目标对象高亮

视图加载完成后自动高亮并居中显示指定对象，是最常用的深链定位手段。

diagram.html?id=24000000000001&blink=24000000000001

行为说明：

注意：blink参数为一次性消费，闪烁完成后自动从 URL 中移除。用户刷新页面不会再次触发闪烁。

目标对象 ID 的获取方式：

• 在 nVisual 中选中图元，通过postMessage的nvisualPatrolSelectedNodeIdList消息获取（参见《通过 postMessage 获取 nVisual 状态》）
• 通过 nVisual 的搜索 API 查询对象列表
• 从 nVisual 导出数据中获取

三、view/X/Y/Z/zoom— 视图模式与相机位置

精确控制视图的渲染模式和初始视角，实现"打开即定位"。

diagram.html?id=24000000000001&view=2d&X=350.5&Y=220.0&zoom=1.2

view取值：

参数校验：缺少必需参数时，nVisual 会忽略view设置，回退到该视图的默认渲染模式和默认视角。

centerX/centerY/centerZ：视口中心偏移量，可选参数，默认为0。

四、map/x/y/mapZoom— 地图定位

专为地图模式设计的精确定位参数。

方式一：JSON 格式

diagram.html?id=24000000000001&map={"center":[116.404,39.915],"zoom":14,"isLonLat":true}

方式二：简单参数

diagram.html?id=24000000000001&x=12950000&y=4850000&mapZoom=12

适合与blink配合使用，当目标对象在地图模式下的自身坐标不可用时，nVisual 从x/y/mapZoom参数中读取定位信息。

五、searchBusiness/businessName— 自动触发搜索

打开视图后自动展开左侧搜索面板，填入关键词并触发搜索。

diagram.html?id=24000000000001&searchBusiness=1&businessName=汇聚交换机

六、editable/isShare— 权限与模式控制

diagram.html?id=24000000000001&editable=false&isShare=true

深链场景示例

场景 1：告警定位

网管系统产生告警，运维人员点击告警直接跳转到 nVisual 中对应设备所在视图并高亮。

diagram.html?id=24000000000001&blink=SW-CORE-01

场景 2：工单关联

工单系统关联设备变更，点击"查看拓扑"以 2D 模式打开指定视图并定位。

diagram.html?id=24000000000001&view=2d&X=350&Y=220&zoom=1.5&editable=false

场景 3：GIS 地图定位

从资产管理平台跳转到 nVisual 地图视图，定位到指定经纬度。

diagram.html?id=24000000000001&view=map&map={"center":[116.404,39.915],"zoom":14,"isLonLat":true}

场景 4：模糊搜索入口

从 CMDB 搜索页面，带关键词跳转到 nVisual 自动执行搜索。

diagram.html?id=24000000000001&searchBusiness=1&businessName=核心交换机

场景 5：组合使用

只读分享链接：打开视图 → 高亮设备 → 禁止编辑

diagram.html?id=24000000000001&blink=SW-A3-01&editable=false&isShare=true

外部系统集成代码

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){constbaseUrl='https://{nVisual 域名}/diagram.html';constparams=newURLSearchParams();// 必填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.editable===false)params.set('editable','false');// 搜索if(options.businessName){params.set('searchBusiness','1');params.set('businessName',options.businessName);}return`${baseUrl}?${params.toString()}`;}

使用示例

// 场景1：告警定位constalarmLink=buildNvisualDeepLink({id:24000000000001,blink:'SW-CORE-01',});window.open(alarmLink,'_blank');// 场景2：工单只读查看constticketLink=buildNvisualDeepLink({id:24000000000001,view:'2d',x:350,y:220,zoom:1.5,editable:false,});document.getElementById('nvisual-frame').src=ticketLink;// 场景3：GIS 定位constgisLink=buildNvisualDeepLink({id:24000000000001,view:'map',map:{center:[116.404,39.915],zoom:14,isLonLat:true},});window.open(gisLink,'_blank');// 场景4：搜索入口constsearchLink=buildNvisualDeepLink({id:24000000000001,searchBusiness:'1',businessName:'核心交换机',});window.open(searchLink,'_blank');// 场景5：分享链接constshareLink=buildNvisualDeepLink({id:24000000000001,blink:'SW-A3-01',editable:false,isShare:true,});copyToClipboard(shareLink);

与 postMessage 的配合使用

深链负责初始定位，postMessage负责运行时通信。两者结合可实现完整的交互闭环：

// ===== 父窗口集成代码 =====constnVisualFrame=document.getElementById('nvisual-frame');// 1. 初始加载：通过 URL 参数定位functionopenNvisual(diagramId,highlightNodeId){nVisualFrame.src=buildNvisualDeepLink({id:diagramId,blink:highlightNodeId,editable:false,});}// 2. 运行时跳转：通过 postMessage 发送 jumpTo 指令（无需刷新 iframe）functionjumpToDiagram(diagramId){nVisualFrame.contentWindow.postMessage({type:'DASHBOARD-EVENT',event:'jumpTo',id:diagramId,},'*');}// 3. 监听 nVisual 状态变化window.addEventListener('message',(event)=>{const{type,value}=event.data||{};// 视图切换时，外部系统同步更新if(type==='nvisualPatrolDiagramIdList'){updateExternalBreadcrumb(value);}// 用户选中图元时，外部系统可同步展示详情if(type==='nvisualPatrolSelectedNodeIdList'){showSelectedInfo(value.nodeIdList,value.linkIdList);}});// 示例：外部告警 → 一键定位 nVisualfunctiononAlarmClicked(alarm){openNvisual(alarm.diagramId,alarm.deviceNodeId);}

注意事项

1. blink一次性消费：高亮完成后自动从 URL 移除，刷新不会再次闪烁。如需每次打开都高亮，每次重新构造链接即可。

2. view仅首次加载生效：仅在 iframe 初始加载时读取，内部视图跳转后不会重新应用。

3. 坐标系统：map参数中若使用经纬度，务必设置"isLonLat": true；若已是投影坐标，省略此字段即可。

4. History 路由模式：nVisual 使用 History 模式，URL 中不含#。如将 nVisual 作为独立页面部署，需确保 Web 服务器配置了 SPA fallback。

5. 跨域：如果父窗口与 nVisual 不同源，通过postMessage通信时注意校验event.origin。