7.3 船位展示服务

适用版本：船讯网海图 GIS 平台 ElaneMap H5 API 3.5
前置阅读：建议先阅读《7.1-快速入门：从注册到接入》《7.2-地图引擎基础：地图控制与业务绘制》，了解地图初始化、密钥（ak）配置及 Leaflet 基础操作后再阅读本篇。

1. 服务概述

1.1 什么是船位展示服务

船位展示服务是 ElaneMap H5 平台上用于在海图上绘制和交互海量船舶位置的核心服务。其入口为静态方法 ShipxyAPI.ShipService(map, options)，底层实现类为 CanvasShipService（船位展示服务实现类）。

与常见的"每艘船一个 DOM Marker"方案不同，CanvasShipService 使用 HTML5 Canvas 在画布上统一绘制船舶符号，因此在同一视野内绘制数万艘船舶时仍能保持流畅的缩放、拖动体验，适合"海量船位"场景。

该服务提供的能力包括：

船舶显示（区域船、船队船/关注船、D+船）

添加船舶、删除船舶、清空船舶

选中船舶、取消选中、选中事件监听

定位船舶（按 MMSI）

按条件筛选船舶（类型、航速、船长、国籍、IMO 合法性）

船舶标签（船名）样式定制

绘制层级（zIndex）控制、监控船（视频船）管理、特殊船置顶等

1.2 区域船、船队船（关注船）、D+船概念区分

概念	说明	开关参数（默认值）
区域船	地图当前可视范围（或由 `bounds` 指定范围）内的全部船舶。服务按地图视野自动向数据接口检索船位并定时自动刷新，是"看一片海域"的模式。	`enableAreaShip`，默认 `true`
船队船 / 关注船	用户自己维护的一批重点关注船舶（例如自己公司的船队），通过 `addFleetShips` 添加到地图上，无论是否在视野内都会置顶突出显示，并自动刷新。	`enableFleetShip`，默认 `true`
D+船	D+ 船位数据（一类补充船位数据源）展示的船舶，默认不开启，可通过 `setEnableDShip` 开启，颜色由 `dShipColor` 控制。	`enableDShip`，默认 `false`

三类船舶可以组合显示：例如只开区域船（enableAreaShip: true, enableFleetShip: false）用于全海域监控；只开船队船（enableAreaShip: false, enableFleetShip: true）用于自有船队监控。

1.3 创建方式

通过静态工厂方法创建，同时 map.shipsService 也会被自动实例化，两者指向同一个服务对象：

参数说明：

参数	类型	说明
map	Map	地图对象（`new ShipxyAPI.Map(...)` 的返回值）
options	Object	配置信息，见第 2 节

返回值：CanvasShipService 实例（同 map.shipsService）。

2. options 配置参数说明

以下配置项均来自 CanvasShipService 类文档（Properties）及官方示例，默认值以源资料为准。

2.1 数据与刷新

参数	类型	默认值	说明
isAutoUpdateSrvtime	Object	true	是否自动更新 srvtime
enableAreaShip	Object	true	是否自动刷新区域船
enableFleetShip	Object	true	是否自动刷新关注船（船队船）
enableDShip	Object	false	是否自动刷新 D+船
enableTracks	Object	true	是否显示近期轨迹
enableSelectedShip	Object	false	是否自动刷新选中船
delayTime	Object	-	刷新间隔时间，单位：毫秒
bounds	Object	地图可视范围	指定区域船的显示区域

2.2 缩放级别与抽稀

参数	类型	默认值	说明
zoomLevel_data	Object	9	zoom 小于等于该值时，不检索数据
zoomLevel_base	Object	9	zoom 大于该值时，用于船舶分组：baseShips
topLabelZoom	Object	1	顶层船从第几级开始显示标签
generalLabelZoom	Object	13	普通船从第几级开始显示标签
weixingLabelZoom	Object	1	卫星船从第几级开始显示标签
shipSizeZoom	Object	1	船舶缩放比例
drawBaseShipsGridZoom	Object	[]	级别，0.1° 网格显示船舶数量限制级别
drawBaseShipsGridMax	Object	[]	数量，0.1° 网格显示船舶数量限制数量，大于 0 生效
drawBaseShipsGridSize	Object	[]（默认 0.5）	缩放级别对应的网格大小
drawBaseShipsGridMaxCount	Object	0	绘制船大于该数量时，开启网格抽稀绘制，大于 0 生效
areaShipsDataGridSize	Object	0.05	网格化存储的网格大小

2.3 标签（船名）样式

参数	类型	默认值	说明
lableRotate	Object	undefined	标签旋转角度
lableTxtColor	Object	["#000","#fff"]	船舶名称文字颜色
lableFont	Object	["'600 12px Arial'", "'500 12px Arial'"]	船舶名称文字字体
lableLineColor	Object	["#000","#000"]	船舶名称文字线框颜色
lableTxtColorMapTypeDark	Object	["MT_SATELLITE", "MT_ESRI", "MT_WEIRUANWEIXING"]	深色瓦片下船舶名称文字颜色的适配定义
dShipColor	Object	#ff6347	D+船颜色

以下为官方区域船示例（b1_1.htm）中出现的扩展标签样式参数（示例用法见 3.1 节）：

参数	默认值（示例注释）	说明
lableLinefillColor	[null,null]	标签框内填充颜色
obliqueLineColor	[null,null]	船舶名称斜线颜色

2.4 回调与扩展

参数	类型	默认值	说明
getAreaShipsCallBack	Object	undefined	区域船外部数据回调，返回 CanvasShip 对象数组。设置后区域船数据可由外部数据源提供
drawShipsEndCallBack	Object	undefined	绘制区域船完成后回调，返回对象 `{count: number}`（本次绘制的船舶数量）
shipOptions	Object	-	船舶模型设置
tooltip_fields	Object	-	tooltip 显示字段设置
monitorShips	Object	-	安装有视频监控的船舶列表（MMSI 列表）

官方区域船示例中还演示了 resetShipColorCallBack 回调（示例中以注释形式给出）：resetShipColorCallBack: function (ship) { return "red"; }，用于按船自定义重设区域船颜色，返回的颜色值将作为该船的绘制颜色。

3. 核心场景与示例

以下示例均为完整可运行的 HTML 页面。使用前请将 您的密钥 替换为在船讯网申请的 API Key（ak）；示例中的 MMSI 均为示例 MMSI，请替换为您账号下有权限查询的船舶。

3.1 区域船展示

展示当前视野内的全部船舶，并在页面左上角实时显示绘制的船舶数量；同时演示手动添加两艘测试船、设置/取消选中船、按 shipid 删除船。

要点说明：

drawShipsEndCallBack 在每一帧区域船绘制完成后触发，data.count 为本次绘制的船舶数量。

手动 addShips 添加的船舶必须包含必填属性：shipid、mmsi、lat、lng。

setSelectedShip 接受 shipid 字符串或 {shipid: shipid} 对象。

3.2 船队船 / 多船展示（添加关注船）

关闭区域船、只开启船队船，从船队数据接口获取自有船队并绘制；同时演示按 MMSI 批量获取多船并绘制。这是实际接入中最重要的场景。

要点说明：

船舶数据结构必填字段：无论是 addShips 还是 addFleetShips，CanvasShip 船舶对象的必填属性均为 shipid、mmsi、lat、lng；缺少任一必填项，该船无法被正确绘制。

多船接口返回的 lat/lon 为 10⁶ 倍整数，hdg/cog 为 100 倍，width/length 为 10 倍，示例中已做换算，接入时请注意。

c_ship.shiptype = 2 表示按"船队船"类型绘制；c_ship.istop = true 表示置顶显示。

addFleetShips 添加后，船队船会按 delayTime 间隔自动刷新船位。

3.3 单船搜索

结合 ShipxyAPI.seachShipService 内置船舶检索输入框，输入船名或 MMSI 检索船舶，点击结果后调用 locationShip 定位到该船。

3.4 单船定位 locationShip

locationShip(mmsi, isQueryURL) 根据 MMSI 查找船舶并在地图上定位，返回 CanvasShip 对象（查不到返回 null）。isQueryURL 表示缓存中查不到时是否继续查询数据接口，默认 true。

返回的 CanvasShip 对象常用字段（示例中用到）：name（船名）、callsign（呼号）、imo、mmsi、length（船长，米）、width（船宽，米）、draught（吃水，米）、sog（航速，节）、hdg（船首向，度）、cog（航迹向，度）、lat/lng（经纬度）、newtype（船舶类型编码）、navistatus（航行状态编码）、lastdyn（动态更新时间，Unix 秒）。

3.5 船舶选中事件 addSelectedListener

鼠标单击地图上的船舶时触发选中事件，回调参数为包含船舶标识的对象：

配套方法：setSelectedShip(shipid) 程序设置选中船、getSelectedShip() 获取当前选中船 ID、cancelSelectedShip() 取消选中。

3.6 船舶筛选 setFilter

setFilter(options) 可按船舶类型、航速、船长、国籍、IMO 合法性对显示船舶进行筛选；满足条件的船舶显示，否则不显示。

4. 方法速查表（CanvasShipService）

以下 34 个方法均可通过 ShipxyAPI.ShipService(...) 的返回值或 map.shipsService 调用。

方法名	功能	参数	返回值
addShips(ships)	添加船舶，更新缓存并绘制	ships：Array，船舶数组 [CanvasShip]，必填属性 shipid、mmsi、lat、lng	-
deleteShipByShipID(shipsid)	通过船舶 ID 删除船	shipsid：string 或 array，船舶 ID（字符串、逗号分割的字符串或数组）	-
removeAllShips()	删除所有船舶（清空画布、清空数据缓存）	无	-
addFleetShips(ships)	添加关注船	ships：Array，船舶数组 [CanvasShip]，必填属性 shipid、mmsi、lat、lng	-
deleteFleetShips(ships)	根据 MMSI 删除指定的关注船	ships：Array，船舶 MMSI 数组，为空则删除所有关注船	-
deleteAllFleetShips()	删除所有关注船船舶（清空画布、清空数据缓存）	无	-
deleteAllAreaShips()	删除所有区域船船舶（清空画布、清空数据缓存）	无	-
locationShip(mmsi, isQueryURL)	船舶定位，根据 MMSI 查找并在地图定位该船	mmsi：String；isQueryURL：缓存查不到是否查询数据接口，默认 true	CanvasShip 或 null
getShipByMmsi(mmsi, isQueryURL)	通过 MMSI 获取船舶信息	mmsi：String；isQueryURL：boolean，缓存查不到是否查询数据接口，默认 true	CanvasShip 或 null
getShipByShipid(shipid)	通过船舶 ID 获取船舶信息（只查缓存）	shipid：String，船舶 ID	CanvasShip 或 null
setFilter(options)	设置船舶筛选条件（类型、航速、船长、国籍、IMO 是否合法）	options：Object，满足条件的船舶显示，否则不显示	-
getFilter()	获取船舶过滤条件	无	Object
addSelectedListener(listener)	添加选中船舶事件，选中船舶时触发	listener：function，回调返回 `{"shipid":"船舶唯一标识","mmsi":"船舶的mmsi"}`	-
removeSelectedListener()	移除选中船舶监听器	无	-
addUnSelectedListener(listener)	未选中船舶事件，鼠标单击但未选中船舶时触发	listener：function，回调方法	-
removeUnSelectedListener()	移除未选中船舶事件	无	-
addSelectedShipUpdateListener(listener)	添加选中船数据刷新事件，选中船数据更新时触发	listener：function，回调返回 `{"shipid":"船舶唯一标识","mmsi":"船舶的mmsi"}`	-
removeSelectedShipUpdateListener()	取消选中船数据刷新事件	无	-
setEnableDShip(enableDShip)	开启或关闭 D+ 船位数据展示	enableDShip：boolean，是否开启 D+ 船	-
getAreaShipShowStatus()	获取区域船显示状态	无	true 或 false
setAreaShipShowStatus(isShow)	设置区域船显示状态，并执行重绘	isShow：Boolean，区域船是否可用	-
setNoSelShipIsShow(isShow, isRedrawShips)	设置非选中船是否显示，并执行重绘	isShow：boolean，是否显示；isRedrawShips：boolean，是否重绘区域船	-
setPointerEvents(isEvent)	设置是否响应鼠标事件	isEvent：boolean，true：响应，false：不响应	-
setSelectedShip(shipid)	设置选中船	shipid：Object，船舶 shipId 字符串或 `{shipid: shipid}` 对象	-
getSelectedShip()	获取选中船	无	船舶 ID 或 null
cancelSelectedShip()	取消选中船	无	-
getShipTypeOtherByArray(arr)	获取除参数指定之外的船舶类型数组（参数为空返回全部），AIS 船舶类型	arr：array，船舶类型，数组或逗号分割的字符串	array
setZIndex(zindex)	设置船舶绘制图层层级	zindex：number，层级	-
getZIndex()	获取船舶绘制图层层级（不存在返回 null）	无	层级或 null
restoreZIndex()	恢复默认船舶绘制图层层级（450）	无	-
updateMonitorShips(monitorShips, isAdd)	更新设置的监控船列表	monitorShips：监控船列表；isAdd：是否追加，默认不追加（清除原有设置）	Array，更新后的监控船舶列表
getMonitorShips()	获取设置的监控船舶列表	无	Array
addSpecialShips()	添加特殊船舶（置顶显示）	无	-
deleteSpecialShips(ships)	根据 MMSI 删除指定特殊船	ships：特殊船舶 MMSI	-

5. 效果示意（文字描述）

区域船展示：海图上以船型符号绘制视野内全部船舶，船头方向随船首向/航迹向旋转；达到一定缩放级别后船旁显示船名标签；左上角"当前船舶数"随每次绘制完成实时刷新；单击某艘船，该船高亮选中并输出其 MMSI；手动添加的"测试船-1"先呈选中态，2 秒后取消选中，"测试船-2"在 3 秒后从图上消失。

船队船展示：海域普通船不显示，只有自有船队的船舶以分组颜色置顶显示，并伴随一条近期轨迹尾线；单击船只弹出信息框展示船名、呼号、MMSI、IMO、船型、航行状态、船长船宽吃水、经纬度、航速航向、目的地、预到时间、更新时间等。

单船搜索：左上角检索框输入船名/MMSI 后下拉显示候选船列表，点击某条结果，地图自动平移缩放到该船位置并选中该船。

单船定位：点击页面上的 MMSI 条目，地图飞到该船位置并弹出信息框展示船舶静态与动态数据；查不到时提示"没有找到！"。

船舶筛选：设置筛选条件后，不满足条件的船舶符号立即从画布上消失，仅保留符合条件的船舶。

6. 注意事项与性能建议

检索级别限制：当地图 zoom 小于等于 zoomLevel_data（默认 9）时，服务不检索区域船数据，海上可能看不到区域船。若需在低级别显示船位概览，请配合网格抽稀参数（drawBaseShipsGridZoom、drawBaseShipsGridMax、drawBaseShipsGridSize、drawBaseShipsGridMaxCount）或调整 zoomLevel_data。

刷新间隔：delayTime 为船位自动刷新间隔（毫秒）。间隔越小数据越实时，但请求频率与绘制开销越大；一般监控场景建议 5000 毫秒及以上，不要设置得过小。

海量船位性能：Canvas 绘制本身可承载海量船位，但仍建议：只开需要的船源（如只看自有船队时关闭 enableAreaShip）；船多时使用 drawBaseShipsGridMaxCount 开启网格抽稀绘制；areaShipsDataGridSize（默认 0.05）控制网格化存储的网格大小，可按数据密度调整。

标签性能：普通船标签默认 13 级才显示（generalLabelZoom），顶层船和卫星船默认 1 级起显示；在低级别强行显示全部船名会明显影响性能，不建议调低。

必填字段：addShips/addFleetShips 的船舶对象必须包含 shipid、mmsi、lat、lng，否则该船不会被绘制。

自动刷新选中船：enableSelectedShip 默认 false，如需选中船的船位单独高频刷新，可设为 true，并配合 addSelectedShipUpdateListener 更新页面信息。

D+ 船：默认关闭（enableDShip: false），可运行时用 setEnableDShip(true) 开启，颜色由 dShipColor（默认 #ff6347）控制。

鼠标事件：setPointerEvents(false) 可让船位画布不响应鼠标事件（例如叠加在只读大屏上时）。

外部数据源：设置 getAreaShipsCallBack 后，区域船可由您的自有数据源提供（回调返回 CanvasShip 对象数组），便于接入私有化船位数据。

7. FAQ

Q1：ShipxyAPI.ShipService(map, options) 和 map.shipsService 是什么关系？
A：同一个对象。调用 ShipxyAPI.ShipService 创建服务时，map.shipsService 会被同时实例化，两种方式拿到的都是 CanvasShipService 实例，可混用。

Q2：地图缩到很小时为什么看不到区域船？
A：默认 zoom ≤ zoomLevel_data（9）时不检索数据。请放大到 10 级及以上，或根据业务调整该参数与网格抽稀配置。

Q3：如何只显示我自己的船队，不显示区域船？
A：初始化时设置 enableAreaShip: false, enableFleetShip: true，然后通过 addFleetShips 添加船队船（务必保证 shipid/mmsi/lat/lng 齐全）。

Q4：如何知道每次实际绘制了多少艘船？
A：使用 drawShipsEndCallBack: function (data) { console.log(data.count); }。

Q5：选中船后如何持续更新它的信息面板？
A：开启 enableSelectedShip: true，并注册 addSelectedShipUpdateListener，回调会返回 {"shipid": ..., "mmsi": ...}，再据此刷新面板数据。

Q6：如何临时隐藏未选中的其它船，只突出显示选中的船？
A：调用 setNoSelShipIsShow(false, true)；恢复时调用 setNoSelShipIsShow(true, true)。

Q7：如何关闭船舶的点击交互（做只读大屏）？
A：调用 setPointerEvents(false)；恢复交互调用 setPointerEvents(true)。

Q8：船位图层被其它图层盖住了怎么办？
A：用 setZIndex(zindex) 调整船舶绘制图层层级，getZIndex() 查询当前层级，restoreZIndex() 恢复默认层级（450）。

7.3 船位展示服务

1. 服务概述#

1.1 什么是船位展示服务#

1.2 区域船、船队船（关注船）、D+船概念区分#

1.3 创建方式#

2. options 配置参数说明#

2.1 数据与刷新#

2.2 缩放级别与抽稀#

2.3 标签（船名）样式#

2.4 回调与扩展#

3. 核心场景与示例#

3.1 区域船展示#

3.2 船队船 / 多船展示（添加关注船）#

3.3 单船搜索#

3.4 单船定位 locationShip#

3.5 船舶选中事件 addSelectedListener#

3.6 船舶筛选 setFilter#

4. 方法速查表（CanvasShipService）#

5. 效果示意（文字描述）#

6. 注意事项与性能建议#

7. FAQ#