HXMap JavaScript SDK

快速入门指南

本指南是面向 Web 开发者在建立HXMap地图应用时使用的快速入门指南。

准备开发环境

您可以下载安装并使用 Visual studio、Eclipse、Sublime Text、Webstorm等常用web开发工具。

下载HXMap JavaScript SDK

您可以从室内可视化地图平台相关下载中按需下载HXMap JavaScript SDK开发资源,其中示例下载内容包括:地图显示、事件、覆盖物、控件、搜索、路径规划、模拟导航等。HXMap JavaScript SDK接入步骤请参考开发指南中配置工程的详细步骤。

创建Web项目

新建一个包含html页面的站点

获取红星云SDK密钥

您首先需要注册成为红星云用户,登陆成功后在控制台->我的应用中创建应用并添加JavaScript SDK应用密钥。

获取密钥

如需使用HXMap JavaScript SDK,您必须在红星云控制台上创建您的应用项目,并添加可用的JavaScript SDK密钥。您需要的SDK密钥类型是JavaScript SDK密钥。

请注意

应用名称(appName)全平台唯一

红星云室内地图平台中的一个应用程序对应唯一一个HXMap JavaScript key

HXMap JavaScript SDK采用key密钥验证体系

HXMap JavaScript SDK 验证key和appName,保证当前web应用程序运行的域名在该key对应的白名单内,同时当前web应用程序名称和appName一致,且该web应用程序使用的HXMap地图为相应用户已发布的地图。

如何获取密钥(key)

根据如下步骤获取HXMap JavaScript SDK 密钥:

a、注册红星云账号。

b、登录红星云账号。

c、创建地图应用。

d、上传地图相关资料(如CAD、Excel地图数据)。

e、审核通过生成地图密钥。

如何填写白名单

白名单为单个或多个网址(如:www.hxmap.com),多网址之间用逗号隔开。

配置工程

开发者可通过Sublime Text、Eclipse、Visual Studio等html文本编辑器编写web程序和站点。在项目中添加HXMap JavaScript SDK文件,在页面代码中添加HXMap.min.js引用,结合HTML,JavaScript等前端技术即可实现对HXMap 地图web端的展示与应用等功能。

创建web站点

该站点需包含以下文件:

a、存放JavaScript SDK 库即HXMap.min.js的文件夹。

b、前端展示的html页面。

编写html页面代码

在html页面引入HXMap JavaScript SDK 库,并添加地图显示代码。可根据HXMap指导编写简单显示地图页面代码。

发布站点

页面完成后发布至tomcat服务器或IIS服务器,浏览器中输入正确的地址即可浏览页面。

创建地图

开发者可通过Sublime Text、Eclipse、Visual Studio等html文本编辑器编写web程序和站点。在项目中添加HXMap JavaScript SDK文件,在页面代码中添加HXMap.min.js引用,结合HTML,JavaScript等前端技术即可实现对HXMap 地图web端的展示与应用等功能。

地图显示

a、显示楼层,地图初始化时可配置显示楼层,地图数据的楼层ID从1开始依次向上加1,默认显示第一层的地图数据。

b、显示比例,HXMap JavaScript SDK新增比例尺级别显示。一种是HXMap JavaScript SDK内部创建的1-5级的比例尺级别设置。第二种是HXMap JavaScript SDK提供的供用户自定义比例尺级别设置,此比例尺级别设置优先级高于其他级别设置。您可以根据需求设置地图初始级别,以及地图能显示的最大和最小级别。

c、显示朝向,您可以自定义地图的初始朝向,如正南、正北或自定义角度等。

d、二三维状态,HXMap JavaScript SDK 支持初始化设置地图的显示模式,二维或三维模式。

地图主题

a、默认主题

b、配置初始化主题

c、切换主题

地图交互

地图控制

本模块将介绍各个初始化地图显示配置,如楼层显示、显示级别、地图朝向、二三维状态、指北针、点击高亮等操作说明。

a、楼层显示:

地图初始化时可配置显示楼层,地图数据的楼层ID从1开始依次向上加1,默认显示第一层的地图数据。

b、地图比例:

HXMap JavaScript SDK新增比例尺级别显示。一种是HXMap JavaScript SDK内部创建的1-5级的比例尺级别设置。第二种是HXMap JavaScript SDK提供的供用户自定义比例尺级别设置,此比例尺级别设置优先级高于其他级别设置。您可以根据需求设置地图初始级别,以及地图能显示的最大和最小级别。

c、地图朝向:

您可以自定义地图的初始朝向,如正南、正北或自定义角度等。

d、二三维状态:

HXMap JavaScript SDK 支持初始化设置地图的显示模式,二维或三维模式。

e、点击高亮:

HXMap JavaScript SDK 默认点击地图会高亮被选中的模型,如不需要点击地图时高亮模型,可修改配置即可达到目的。

地图控件

HXMap JavaScript SDK 提供多个控件。控件与地图之间存在交互。本模块将对控件交互部分提供说明介绍。

a、楼层控件:

HXMap JavaScript SDK提供楼层切换控件以及对应的地图交互与回调事件的接口。

b、缩放控件:

HXMap JavaScript SDK 提供放大、缩小控件,放大、缩小控件按钮点击时会根据比例尺级别放大和缩小地图,并提供回调方法。

c、2D/3D切换控件:

HXMap JavaScript SDK 提供2D、3D切换控件,通过控件可操作地图的2D或3D显示,并回调方法,返回当前控件类型和对应的操作值。

d、指北针控件:

HXMap JavaScript SDK 提供指北针控件,通过开关设置其显示或隐藏,默认隐藏,并监听指北针点击事件。

e、气泡消息框控件:

HXMap JavaScript SDK 提供气泡信息框功能,根据传入的地图坐标或屏幕坐标在地图相应位置添加气泡信息框,气泡信息框里的内容可自定义填充HTML元素。

f、地图编辑器:

HXMap JavaScript SDK 提供地图编辑器功能,根据传入的地图数据进行基础的操作,并回调方法,返回当前控件类型和对应的操作值。

事件与方法

HXMap JavaScript SDK 地图事件有地图加载完成事件、点击事件、缩放级别事件、地图状态更新事件等。

                          var map = new HXMap(options)
                        

a、地图加载渲染完成:

                          map.on('render',((event,result)=>{

                          }))
                        

地图在完成对HXMap地图文件的渲染后回调事件,该事件表示地图已渲染完成。注:地图渲染完成后调用地图方法获取或设置地图状态生效,若在之前改变地图的状态可能不生效。

b、选中事件:

                          map.on('selected',((event,result)=>{

                          }))
                        

地图点击事件会监听地图中所有地图元素,当点击某个地图元素的时候,会返回拾取到的地图元素对象。

c、缩放事件:

当缩放地图时,HXMap JavaScript SDK 提供监听缩放事件。

d、拖拽事件:

当拖拽地图时,HXMap JavaScript SDK 提供监听拖拽事件。

e、坐标转换:

地图点击事件会监听地图中所有地图元素,当点击地图某个区域的时候,会返回拾取到的地图坐标对象。

f、地图图元管理:

                          map.on('drawend',((event,result)=>{

                          }))
                        

提供地图图元的增删查改功能,方便对地图图元的变化进行即时更新,会返回对应操作的图元对象。

g、图标管理:

提供地图图标的新增、删除功能,方便对地图图标的变化进行即时更新,会返回对应操作的图标对象。

h、地图图元合并/拆分:

                          map.on("merge", shape => {
        
                          });
                          map.on("split", shape => {
                                  
                          });
                        

提供地图多图元合并与(单/多)图元拆分操作,方便对地图区域的变化进行即时更新,会返回操作的图元以及合并/拆分完成的图元对象。

i、地图绘制:

在地图中进行鼠标多次点击形成区域完成地图新增操作,会返回新增的图元对象。

数据检索

信息检索

HXMap JavaScript SDK支持对数据模型(Model)、公共设施(facility)、自定义标注(Marker)等地图元素的搜索分析。本模块是对查询地图元素的调用接口说明。

a、创建搜索分析对象

b、创建搜索请求体对象

c、查询分析

d、创建搜索分析对象

数据检索

HXMap JavaScript SDK支持自有数据的查询是您的业务数据。可通过地图数据内的某个字段与自有数据相关联,分两步查询:第一步先查询地图数据;第二步在根据地图数据关联业务数据字段查询对应自有数据。

a、创建搜索分析对象

b、创建搜索请求体对象

d、自由数据搜索分析

径规划与导航

路径规划

HXMap JavaScript SDK支持根据起点和终点坐标规划路线功能。

a、初始化路径分析对象

设置起、终点,在地图渲染回调后,初始化路径分析对象。

b、路径分析

根据设置的起、终点和起、终点楼层进行路径分析,分析成功,返回路径经过的坐标点集。

c、获取路径描述信息

根据设置的起、终点和起、终点楼层进行路径分析,分析成功后,返回路径经过的坐标点集。同时可根据结果集获取路径描述等信息。

定位导航

HXMap JavaScript SDK 结合定位技术,可实现真实的定位导航的功能。本单元将就结合模拟定位点进行路径分析并模拟导航功能展开说明。即导航类的使用说明。

a、初始化导航对象

设置起始模拟点,在地图渲染回调后,初始化路径分析对象。

b、绘制导航线。

模拟起始点,使用导航类绘制导航线。

c、获取导航描述信息。

完成路径分析后,可根据路径结果获取路径描述信息。

d、导航的开始与结束。

模拟导航有开始与结束。

e、定位坐标转换

在使用真实的定位系统时,如:WIFI定位,蓝牙定位等,就需要将定位系统所返回的定位坐标转化为HXMap地图坐标,这样就可以在HXMap地图中去根据真实的定位点去实时的改变地图中的Marker的位置。实现定位的功能。

HXMap JavaScript SDK中提供了一个专用于坐标转化的通用类。

HXMap:地图类

new HXMap(options):HXMap 实例化地图

参数名称类型描述
optionsObject名称类型描述
containerString加载地图html容器,必填

Members:

名称类型描述
selectedShapesArray选中的图元集合

Methods:

render(data):void 渲染地图

参数名称类型描述返回值
dataStringSVG字符串

chooseShapesByIds (ids):void 手动选中图元

参数名称类型描述返回值
idsArray需要选中的图元ID数组

use(plugin):void 插件安装

参数名称类型描述返回值
pluginObject包含install 方法的插件对象,如HXMap.use(HXMap.SelectShape)

transformPoint(pageX,pageY,shape?:ShapeGroup): Object坐标转换

参数名称类型描述返回值
pageXNumber|String页面X轴坐标,必须返回相对于shape对象坐标系的坐标点
pageYNumber|String页面Y轴坐标,必须
shapeShapeGroup参照物对象,用于参考哪个坐标系转换坐标,(默认为当前地图g元素)非必须

zoomIn():void 地图放大

zoomOut():void 地图缩小

getMapSVGHTML():String获取地图SVG字符串

destroy():void 地图销毁:重置地图状态,清空选中图元,销毁地图的绑定的事件等。

InsertImage(id,src,x,y,width,height,title):ShapeImage 插入图片/图表

参数名称类型描述返回值
idDOMString图标ID,必须图标对象
srcStringBase64,必须
xNumber|StringX轴坐标,必须
yNumber|StringY轴坐标,必须
widthNumber图标宽度,必须
heightNumber图标高度,必须
titleString图标文本

HXMap.MapMove:地图移动插件,用于鼠标UI事件交互

HXMap.use(HXMap.MapMove):安装插件

Methods

dispatch(‘tool:move’):void 派发地图移动事件

参数名称类型描述
'tool:move'String固定值,必须

HXMap.SelectShape:选中图元插件,用于鼠标UI事件交互

HXMap.use(HXMap.SelectShape):安装插件

Methods:

on('selected',callback?:Function):void 监听图元选中事件

参数名称类型描述返回值
selectedString固定值,必须event:事件对象;shapes:选中的图元,用回调函数callback接受
callbackFunction回调函数,非必须

dispatch(‘tool:select’):void 派发地图选中事件

参数名称类型描述
'tool:select'String固定值,必须

HXMap.DragShape:图元拖拽插件,用于鼠标UI事件交互

HXMap.use(HXMap.DragShape):安装插件

Methods:

on('dragend',callback?:Function):void 监听图元移动完成事件

参数名称类型描述返回值
dragendString固定值,必须event:事件对象;shape:拖拽的图元对象,用回调函数callback接受
callbackfunction回调函数,非必须

dispatch('tool:init'):void 派发初始事件,初始状态默认可以拖拽图元

参数名称类型描述
'tool:init'String固定值,必须

HXMap.RemoveShape:图元删除插件,用于鼠标UI事件交互

HXMap.use(HXMap.RemoveShape)

Methods:

on('removed',callback?:Function):void 监听删除完成事件

参数名称类型描述返回值
removedString固定值,必须event:事件对象;shape:删除的图元对象,用回调函数callback接受
callbackfunction回调函数,非必须

dispatch('tool:remove'):void 派发图元删除事件

参数名称类型描述
'tool:remove'String固定值,必须

HXMap.MergeShape:图元合并插件,用于鼠标UI事件交互

HXMap.use(HXMap. MergeShape)

Methods:

on('merge',callback?:Function):void 监听图元合并完成事件

参数名称类型描述返回值
mergeString固定值,必须event:事件对象; shape:合并的图元对象,用回调函数callback接受
callbackfunction回调函数,非必须

dispatch('tool:merge'):void 派发图元合并事件

参数名称类型描述
'tool:merge'String固定值,必须

HXMap.SplitShape:图元拆分插件,用于鼠标UI事件交互

HXMap.use(HXMap.SplitShape)

Methods:

on('split',callback?:Function):void 监听图元拆分完成事件

参数名称类型描述返回值
splitString固定值,必须event:事件对象; shape:拆分后的图元对象,用回调函数callback接受
callbackfunction回调函数,非必须

dispatch('tool:split'):void 派发图元切割事件

参数名称类型描述
'tool:split'String固定值,必须

HXMap.DrawShape:图元绘制插件,用于鼠标UI事件交互

HXMap.use(HXMap.DrawShape)

Methods:

on('drawend',callback?:Function):void 监听绘制完成事件

参数名称类型描述返回值
drawendString固定值,必须event:事件对象; shape:绘制的图元对象,用回调函数callback接受
callbackfunction回调函数,非必须

dispatch('tool:draw'):void 派发图元绘制事件

参数名称类型描述
'tool:draw'String固定值,必须

HXMap.MapDrawLine:路径绘制插件,用于鼠标UI事件交互

HXMap.use(HXMap.MapDrawLine)

Methods:

dispatch('tool:drawline'):void 派发路径点绘制事件

参数名称类型描述
'tool:drawline'String固定值,必须