7.2 地图引擎基础：地图控制与业务绘制

适用版本：船讯网海图GIS平台 H5 API 3.5
前置阅读：《7.1-快速入门：从注册到接入》。阅读本文前，请确认您已获得 API 密钥并能在页面上成功显示地图。
本文内容：地图初始化 options 全参数、地图操作方法、内置控件、图源切换、点/线/面标注绘制。

1. 地图初始化：Map(map, options)

地图插件是平台的入口，提供地图基本功能：地图初始化、图源切换、缩放、拖动、测距、鹰眼等。

参数	类型	说明
map	Object	HTML 容器对象（容器 id 字符串，如 `"map"`）
options	Object	配置信息，详见下文参数表

返回值：L.Map（Leaflet 原生地图对象）。返回值上既可调用 Leaflet 原生方法，也挂载了平台扩展的控件与服务（如 basemapsControl、PolylineMeasureControl、Draw 等）。

1.1 options 完整参数表

以下参数与官方示例完全一致，均为可选；实际使用时按需传入即可（ak 必填）。

参数	类型	默认值 / 示例	说明
ak	String	`""`	授权码（API 密钥），必填
attribution	Object	`{isShow: true, emptyString: '©2018 <a class="shipxy_small"></a> <a>Elane Inc.</a>'}`	公司版权信息（支持 html），默认显示 Elane Inc.
mapTypes	Array	`['MT_SEA', 'MT_GOOGLE', 'MT_SATELLITE']`	显示地图类型（图源切换控件中出现的图源列表）
defaultMapType	String	`'MT_SEA'`	默认展示的地图类型
gratings	Object	`{isShow: false, maxZoom: 9, type: "RASTER_WORLD"}`	光栅图：是否显示、最大显示级别，默认不显示
centerPoint	Array	`[32.1, 122.11]`	初始中心点坐标 `[纬度, 经度]`
zoom	Number	`4`	初始缩放级别
minZoom	Number	`2`	最小缩放级别
maxZoom	Number	`18`	最大缩放级别
measureCtrl	Object	`{isShow: true, position: 'topleft'}`	测量（测距）控件的显示隐藏，详见 3.3 节
mousePostionCtrl	Object	`{isShow: true, position: 'bottomright'}`	鼠标移动悬浮经纬度控件
zoomControlElane	Object	`{isShow: true, position: 'topright'}`	缩放控件的显示隐藏
zoomviewControl	Object	`{isShow: true, position: 'topleft'}`	缩放级别显示控件
basemapsControl	Object	`{isShow: true, position: 'topright'}`	地图切换（图源切换）控件的位置
mapReadyCallBack	Function	`function (map) {}`	地图初始化完成后的回调方法，参数为地图对象
scaleCtrl	Object	`{isShow: true, position: "bottomleft"}`	比例尺控件
addTileLayer	Array	`[]`	自定义图源（Leaflet TileLayer 对象数组）
cjhdTileLayer	Object	`{isShow: false}`	是否显示长江航道，默认：false
miniMapControl	Object	`{isShow: false, options: {}}`	鹰眼（小地图）控件
tileLayer	Object	见下方说明	默认图源设置（url、errorTileUrl），默认图源类型有：sea、google、satellite

其中 tileLayer 用于覆盖内置图源的瓦片地址，结构如下（一般无需修改）：

1.2 初始化示例（含自定义图源）

2. 常用地图操作方法

2.1 fitWorld()：全球视野

调整地图视野，使整张世界地图完整显示在容器中。适合作为未指定 centerPoint/zoom 时的默认视野。

2.2 setRasterShow(isShow)：光栅图显示/隐藏

手动控制光栅图的显示与隐藏（对应初始化参数 gratings）。

2.3 Leaflet 原生能力

ShipxyAPI.Map 的返回值就是 Leaflet 的 L.Map 对象，因此以下 Leaflet 原生能力 均可直接使用（详细用法可查阅 Leaflet 官方文档）：

方法	说明
`map.setView([lat, lng], zoom)`	设置中心点与缩放级别
`map.panTo([lat, lng])`	平移视野到指定坐标
`map.fitBounds(bounds)`	调整视野以完整包含指定范围（常与标注的 `getBounds()` 配合）
`map.getCenter()` / `map.getZoom()`	获取当前中心点 / 缩放级别
`map.on('click', fn)`	监听地图事件（click、mousemove、zoomend、moveend 等 Leaflet 原生事件）
`map.addLayer(layer)` / `map.removeLayer(layer)`	添加 / 移除图层
`ShipxyAPI.latLng(lat, lng)`	创建坐标对象（等同 Leaflet 的 `L.latLng`）

注意：标注类工厂方法平台以 ShipxyAPI 命名空间导出（ShipxyAPI.marker、ShipxyAPI.polyline、ShipxyAPI.polygon 等，底层即 Leaflet 对应类）；而图标、坐标参考系等仍使用 L 命名空间（L.icon、L.CRS.EPSG3857 等）。

3. 内置控件

所有内置控件都通过初始化 options 配置显示/隐藏与位置，且默认开启。position 可选值为 Leaflet 控件方位：'topleft'、'topright'、'bottomleft'、'bottomright'。

控件	options 参数	默认位置	功能
缩放控件	zoomControlElane	topright	放大 / 缩小按钮
缩放级别显示控件	zoomviewControl	topleft	实时显示当前缩放级别数字
图源切换控件	basemapsControl	topright	海图 / 地图 / 卫星图源切换（见第 4 节）
测距控件	measureCtrl	topleft	在地图上连续点击测量多点距离（见 3.3）
比例尺控件	scaleCtrl	bottomleft	左下角显示比例尺
鼠标坐标控件	mousePostionCtrl	bottomright	鼠标悬浮时实时显示所在经纬度
鹰眼控件	miniMapControl	默认关闭	右下角小地图（鹰眼），`{isShow: true, options: {}}` 开启
版权信息	attribution	左下角	平台版权文字，支持 html

3.1 控件完整示例（对应官方示例"1.1 地图控件"）

效果示意：地图右上角为缩放控件（+/-）与图源切换控件；左上角为缩放级别数字与测距控件按钮组；左下角为比例尺；右下角随鼠标移动实时刷新经纬度；左下角显示版权信息。页面左上方悬浮三个自定义按钮，可代码控制测距。

3.2 缩放控件、缩放级别显示、比例尺、鼠标坐标、鹰眼

这几个控件只需在 options 中配置，无需额外代码：

效果示意：开启鹰眼后，地图角落出现一个缩略小地图，小地图中以矩形框标出主图当前可视范围，拖动主图时矩形框同步移动。

3.3 测距控件（对应官方示例"1.2 测距控件"）

测距控件 measureCtrl 的子参数：

参数	默认值	说明
isShow	true	是否开启测距控件
showMeasurementsMeasureControl	true	是否显示测距按钮
showMeasurementsClearControl	true	是否显示删除按钮
showUnitControl	true	是否显示切换单位按钮
position	topleft	控件位置

除控件自带按钮外，还可以通过代码控制测距（示例见 3.1 节）：

方法	说明
`map.PolylineMeasureControl._toggleMeasure()`	开始 / 结束测距（切换测距状态）
`map.PolylineMeasureControl._changeUnit()`	切换测距单位（如公里 / 海里）
`map.PolylineMeasureControl._clearAllMeasurements()`	删除全部测距结果
`map.PolylineMeasureControl._measuring()`	查询当前是否正在测距

效果示意：点击"测距"后进入测距模式，在地图上依次点击多个点，点与点之间出现测距线段，每段及累计距离以文字标注在线上；点击"切换单位"距离数值在单位间切换；点击"删除测距"清空全部测距线段。

4. 图源切换（对应官方示例"1.3 图源切换控件"）

平台内置三种图源，通过 options 的 mapTypes 配置可选列表，defaultMapType 配置默认图源：

图源标识	说明
MT_SEA	电子海图（默认）
MT_GOOGLE	谷歌地图（陆地图）
MT_SATELLITE	卫星影像

开启 basemapsControl 后，地图右上角会出现图源切换控件，用户可点击切换。也可以通过代码切换：

完整示例

效果示意：点击"海图"按钮，底图变为以浅蓝海洋、岸线、水深注记为主的电子海图；点击"地图"按钮，底图变为以道路、行政区划为主的谷歌陆地地图；点击"卫星"按钮，底图变为真实卫星遥感影像。

5. 标注绘制（点 / 线 / 面）

平台底层为 Leaflet，标注绘制直接使用 Leaflet 原生绘制能力：平台以 ShipxyAPI 命名空间导出 latLng、marker、polyline、polygon 等工厂方法（对应 Leaflet 的 L.latLng、L.marker、L.polyline、L.polygon），创建后调用 .addTo(_map) 即可加到地图上。此外平台还封装了 _map.Draw 交互式绘制插件，支持用户在地图上手工绘制并编辑图形。

5.1 点标注 Marker（对应官方示例"1.5 标注-点"）

最基本的点标注只需两行：创建坐标、创建 marker 并加到地图。

参数说明：

接口	参数	说明
`ShipxyAPI.latLng(lat, lng)`	lat：纬度；lng：经度	创建坐标对象（等同 `L.latLng`）
`ShipxyAPI.marker(latlng, options)`	latlng：坐标；options：Leaflet marker 配置（如 `icon`）	创建点标注（等同 `L.marker`）
`marker.addTo(map)`	map：地图对象	把标注添加到地图
`marker.remove()`	无	从地图上删除该标注

效果示意：地图加载完成后，在东海海域（北纬 32.1 度、东经 122.11 度附近）出现一枚默认样式的蓝色图钉标记。

5.2 点标注进阶：自定义图标、事件与 Popup（对应官方示例"1.5.1 标注-点(图标/事件)"）

通过 L.icon 可以自定义标注图标；通过 bindPopup / bindTooltip 可以绑定弹窗与悬浮提示；通过 marker.on(...) 可以监听 click、mouseover、mouseout 等鼠标事件。

参数说明：

接口	关键参数	说明
`L.icon(options)`	iconUrl：图标图片地址；iconAnchor：图标锚点 `[x, y]`（图标上哪个像素对准坐标点）；iconSize：图标大小 `[宽, 高]`（可选）	自定义标注图标（Leaflet 原生）
`ShipxyAPI.marker([lat, lng], {icon})`	icon：上面创建的图标对象	创建使用自定义图标的点标注
`marker.bindPopup(content, options)`	content：HTML 字符串或返回 HTML 的函数；options.className：弹窗样式类名（示例用 `shipxy_popup`）；options.closeButton：是否显示关闭按钮	绑定点击弹窗
`marker.openPopup()`	无	立即打开弹窗
`marker.bindTooltip(content)`	content：提示文字	绑定鼠标悬浮提示
`marker.on(event, fn)`	event：`'click'`、`'mouseover'`、`'mouseout'` 等	监听鼠标事件，`e.target` 为 marker 本身
`marker.setIcon(icon)`	icon：图标对象	动态更换标注图标

效果示意：地图中心附近出现一枚自定义小图标，标注旁边默认打开着一个白色弹窗（Popup），弹窗标题为"这里是Popup"，内有若干行说明文字，右上角有关闭按钮；鼠标划过图标时图标切换为另一张图片并浮现 Tooltip 文字"这里是Tooltip，相应鼠标划过事件！"，鼠标移开后图标恢复原样。

5.3 交互式绘制点（_map.Draw，可选）

平台封装了 _map.Draw 绘制插件，让用户在地图上手工绘制图形。点绘制的核心流程（完整代码见官方示例 a1_5.htm）：

接口	说明
`_map.Draw.begin({shape})`	开始交互绘制，shape：`'Marker'` 点 / `'Line'` 线 / `'Poly'` 面，返回 shape 对象
`_map.Draw.end(shape)`	结束绘制
`_map.Draw.getLayer(shape)`	根据 shape 取得绘制出的 Leaflet 图层
`_map.Draw.edit(layer, flag)`	进入编辑模式（可拖动顶点修改图形）
`_map.Draw.cancelEdit(layer)`	退出编辑模式
`map.on("pm:create", fn)`	绘制完成事件
`layer.on("pm:edit", fn)`	图形被编辑后的事件

5.4 线标注 Polyline（对应官方示例"1.6 标注-线"）

参数说明（ShipxyAPI.polyline(latlngs, options)，样式项为 Leaflet 原生 Path 配置）：

参数	示例值	说明
latlngs	`[[45.51, 122.68], [37.77, 122.43], [34.04, 118.2]]`	折线顶点数组，元素为 `[纬度, 经度]`
color	`'red'`	折线颜色
weight	`3`	折线宽度（像素）
opacity	`1`	折线透明度，范围 `[0,1]`
dashArray	`[5,10]`	虚线配置 `[线段长度、间隙长度、线段长度、间隙长度...]`，不传则为实线

相关方法：polyline.getBounds() 取得折线外包矩形，配合 _map.fitBounds(...) 让视野刚好包含整条线；polyline.getLatLngs() 取得点集；polyline.remove() 删除。

效果示意：地图视野自动调整到中国东部沿海至渤海湾范围，海上出现一条由三段组成的红色虚线（线宽 3 像素），自北向南依次连接三个顶点。

5.5 面标注 Polygon（对应官方示例"1.7 标注-面"）

参数说明（ShipxyAPI.polygon(latlngs, options)，样式项为 Leaflet 原生 Path 配置）：

参数	示例值	说明
latlngs	`[[45.51, 122.68], ...]`	多边形顶点数组，元素为 `[纬度, 经度]`
stroke	`true`	是否显示边框
color	`"red"`	边框颜色
weight	`3`	边框宽度（像素）
opacity	`1`	边框透明度，范围 `[0,1]`
dashArray	`[5,10]`	边框虚线配置 `[线段长度、间隙长度...]`
fill	`true`	是否填充
fillColor	`"red"`	填充颜色，缺省时使用 color 值
fillOpacity	`0.2`	填充透明度，范围 `[0,1]`

面的交互式绘制与点、线一致，_map.Draw.begin({shape: 'Poly'})；多边形编辑后通过 draw_layer.getLatLngs()[0] 取得顶点集合。除多边形外，Leaflet 原生还提供 L.circle（圆形）、L.rectangle（矩形）等面状图形，创建后同样 .addTo(_map) 即可使用。

效果示意：地图视野调整到中国东部近海，海面上出现一个红色虚线边框的三角形区域，内部以 20% 透明度的红色填充，透过填充仍能看到下方的海图。

6. 注意事项与 FAQ

注意事项

坐标顺序是 [纬度, 经度]：Leaflet 体系下所有坐标（centerPoint、latLng、点集数组）都是纬度在前、经度在后，与部分"经度在前"的地图 API 相反，传反会导致标注跑到地球另一端。

命名空间的分工：创建图形用 ShipxyAPI.marker / polyline / polygon（或等价的 L.marker 等），图标与坐标参考系用 L.icon、L.CRS.EPSG3857，两者都来自同一个 Leaflet 引擎，混用没有问题。

删除图形用图层自身的 remove()：如 mm.remove()、draw_layer.remove()；编辑状态要先 cancelEdit 再删除。

悬浮在地图上的自定义按钮需要设置 z-index（官方示例用 888）并在点击事件中调用 e.stopPropagation()，避免点击穿透到地图触发地图事件。

控件 position 只支持 'topleft'、'topright'、'bottomleft'、'bottomright' 四个方位；同一位置放多个控件时会自动堆叠。

FAQ

Q1：调用 _map.basemapsControl.changeMap(...) 报错或没反应？
确认初始化 options 中 basemapsControl 的 isShow 为 true（默认开启）；切换的目标图源标识必须在 mapTypes 列表中，自定义图源则需在 addTileLayer 中注册过。

Q2：设置了 centerPoint 和 zoom，但初始视野不对？
检查坐标顺序是否为 [纬度, 经度]；zoom 需在 minZoom 与 maxZoom 之间，超出范围会被限制。

Q3：marker / polyline 创建后地图上看不到？

确认调用了 .addTo(_map)；2) 确认坐标在当前视野内，可用 _map.fitBounds(layer.getBounds()) 或 _map.setView(...) 把视野移过去；3) 自定义图标的 iconUrl 图片地址需可访问，否则图标显示为空。

Q4：_map.Draw.begin 绘制时没有任何提示，如何知道绘制完成？
监听地图的 pm:create 事件，绘制完成会触发；编辑顶点会触发图层的 pm:edit 事件，在回调里用 getLatLng() / getLatLngs() 取最新坐标。

Q5：测距单位如何切换、结果如何清除？
通过 _map.PolylineMeasureControl._changeUnit() 切换单位，_clearAllMeasurements() 清除全部测距，清除后建议再调用一次 _toggleMeasure() 更新控件状态。

Q6：想在地图初始化完成后立刻执行自己的逻辑（如添加标注），应该写在哪里？
使用 options 的 mapReadyCallBack: function (map) { ... } 回调，地图初始化完成后会调用并传入地图对象；在简单场景下，直接在 new ShipxyAPI.Map(...) 之后的代码中操作通常也可以（官方示例即如此）。

Q7：Leaflet 原生文档里的方法都能用吗？
返回值是原生 L.Map，Leaflet 的视图控制（setView/panTo/fitBounds）、事件（on/off）、图层管理（addLayer/removeLayer）等原生能力都可直接使用；平台未封装的 Leaflet 插件（如 circle、rectangle、GeoJSON 等）同样可以自行引入使用。

7.2 地图引擎基础：地图控制与业务绘制

1. 地图初始化：Map(map, options)#

1.1 options 完整参数表#

1.2 初始化示例（含自定义图源）#

2. 常用地图操作方法#

2.1 fitWorld()：全球视野#

2.2 setRasterShow(isShow)：光栅图显示/隐藏#

2.3 Leaflet 原生能力#

3. 内置控件#

3.1 控件完整示例（对应官方示例"1.1 地图控件"）#

3.2 缩放控件、缩放级别显示、比例尺、鼠标坐标、鹰眼#

3.3 测距控件（对应官方示例"1.2 测距控件"）#

4. 图源切换（对应官方示例"1.3 图源切换控件"）#

完整示例#

5. 标注绘制（点 / 线 / 面）#

5.1 点标注 Marker（对应官方示例"1.5 标注-点"）#

5.2 点标注进阶：自定义图标、事件与 Popup（对应官方示例"1.5.1 标注-点(图标/事件)"）#

5.3 交互式绘制点（_map.Draw，可选）#

5.4 线标注 Polyline（对应官方示例"1.6 标注-线"）#

5.5 面标注 Polygon（对应官方示例"1.7 标注-面"）#

6. 注意事项与 FAQ#