7.6 航线绘制与区域回放服务

适用版本：ElaneMap H5 API 3.5
前置阅读：建议先阅读《7.1-快速入门：从注册到接入》与《7.2-地图引擎基础：地图控制与业务绘制》，掌握 API 引入、密钥（ak）配置、地图实例化（new ShipxyAPI.Map(...)）之后再阅读本篇。
本篇涉及服务的 API 引用方式：

本篇覆盖五组服务：

服务	入口	功能定位
航线绘制服务	`ShipxyAPI.trackDrawSymbol`	在地图上交互式绘制/编辑/展示/删除航线
船位回放服务	`ShipxyAPI.areaPlayService`	指定区域、指定时间段的船位回放
区域船舶轨迹回放服务	`ShipxyAPI.AreaTrackReplayService`	区域内船舶轨迹回放任务面板
船舶检索服务	`ShipxyAPI.seachShipService`	内置船舶检索输入框
历史航次服务	`ShipxyAPI.voyageService`	查询船舶当前/历史航次数据

1. 航线绘制服务 trackDrawSymbol

航线绘制服务提供显示航线、绘制航线、编辑航线、删除航线等功能。用户在地图上逐点单击形成航线节点，节点间自动连线并标注航向、航程等信息。

1.1 创建

参数	类型	说明
map	L.Map	地图对象
options	Object	设置信息
items	array	航线节点数组（非必填），见 1.3 节

返回值：L.TrackDrawSymbol 航线绘制对象。

1.2 options 参数表

参数	说明
callBack	绘制/编辑回调函数，`function (item) {}`，item 为当前航线节点数组数据
unit	航程单位，如 `"nm"`（海里）
symbol	航线标识前缀，如 `"ABC_"`（节点编号显示为 ABC_1、ABC_2 …）
lineColor	航线颜色，如 `"#E000BB"`

1.3 items 航线节点数组结构

字段	是否必填	说明
lat	必填	纬度
lng	必填	经度
id	非必填	节点 ID
name	非必填	节点名称
cog	非必填	航向

1.4 方法

方法	说明
drawTrack()	进入绘制模式，在地图上逐点单击绘制航线
editLine()	进入编辑模式，可拖动调整已有节点
showTrack()	只读模态展示当前航线（绘制"完成"态）
showTrack(items)	只读模态展示指定航线数据
removeTrack()	删除航线

演示页面 a1_4 中还提供了两个自定义节点文字的扩展方法（按需使用）：

方法	说明
setItemTextById({id, caText, pDistanceText, markerText})	修改单个轨迹点文字展示
setItemTextByTextItems([{id, caText, pDistanceText, markerText}, ...])	批量修改多个轨迹点文字展示

1.5 完整可运行示例（整理自 a1_4.htm）

1.6 效果示意（文字描述）

点击"绘制"后进入绘制模式：在地图上每单击一次生成一个航线节点，节点显示为带编号的小圆点（编号为 symbol 前缀加序号，如 ABC_1、ABC_2），相邻节点间自动连线，线上标注航向角与分段航程（单位由 unit 决定），同时实时显示累计航程。点击"编辑"后节点变为可拖动状态，拖动节点航线自动重算。点击"完成"后进入只读模态，节点不可再拖动。点击"删除"清除整条航线。点击"显示"可将 callBack 中保存的航线数据重新回显到地图上。

2. 船位回放服务 areaPlayService

船位回放服务提供指定区域、指定时间段的船位回放功能：按播放倍速逐秒推进时间轴，重现区域内各船舶在不同时刻的位置。

2.1 创建

返回值：L.AreaPlayService。

2.2 options 参数表

参数	默认值	说明
playSpeed	60	播放倍速，播放秒数 = 真实秒数（如 60 表示 1 秒播放 60 秒数据）
beginTime	0	开始位置（毫秒），0 表示从起始位置开始
playCallBack	null	播放时间后回调
minTime	0	开始时间，秒（Unix 时间戳）
maxTime	0	结束时间，秒（Unix 时间戳）
getDataByURL	""	数据获取 URL
area	""	区域，整数型经纬度逗号分割字符串
areaId	""	区域 ID

2.3 area 参数格式说明

area 为整数型经纬度逗号分割字符串，即经纬度乘以 10 的 6 次方取整后，按 经度,纬度 成对排列、逗号连接，依次给出区域多边形的各顶点。例如：

"121534582,31361372,121630627,31361372,121630627,31416852,121534582,31416852"

表示一个矩形区域的四个顶点：(121.534582, 31.361372)、(121.630627, 31.361372)、(121.630627, 31.416852)、(121.534582, 31.416852)。

2.4 完整示例

3. 区域船舶轨迹回放服务 AreaTrackReplayService

区域船舶轨迹回放服务提供"新建回放任务"面板：在地图上圈选区域、选择时间段后，回放该区域内所有船舶的运动轨迹，支持播放控制、船舶列表、全屏等。

3.1 创建

返回值：ShipxyAPI.AreaReplayService。初始化后通过 map.areaTrackReplayService 访问。

3.2 options 参数表

主文档列出的核心参数：

参数	默认值	说明
defaultPlay	—	是否默认播放（示例为 false）
isVisiableWithNoSignal	false	设置船舶无信号是否可见，默认：不可见
isVisiableOutOfBounds	false	设置船舶超过视图范围是否可见，默认：不可见
isVisiableShipTrack	false	设置轨迹是否可见，默认：不可见

演示页面 b1_7 中实际使用的扩展参数与回调：

参数	说明
areaStyle	区域样式，如 `{color: "red", fillColor: "rgba(255,0,0,0.2)", weight: 1}`，支持 dashArray
maxSupplementPointInterval	最大补点间隔，单位 s（示例 1800）
shipTrackMaxInterval	轨迹最大显示间隔时间，单位 s（示例 1800）
shipTemplaterZoom	船舶缩放比例（示例 1.0）
openCallback	打开任务面板回调
closeCallback	关闭任务面板回调
afterInitReplayData(hasData)	数据加载完成后回调，hasData 表示是否有数据
startReplayCallback	开始回放回调
closeReplayCallback	关闭回放回调
fullScreenReplayCallback	全屏按钮回调
shipListClickCallback(mmsi)	船舶列表点击回调，返回 mmsi
isCallDrawFeature	是否调用绘制功能（示例 false）

3.3 方法

方法	说明
openCreateTaskLayer()	打开"新建回放任务"面板，用户在地图上圈选区域并设置时间段

3.4 完整示例（整理自 b1_7.htm）

4. 船舶检索服务 seachShipService

船舶检索服务提供内置的船舶检索输入框：在指定 div 容器中渲染搜索框，用户输入船名/MMSI 关键字后展示候选列表，点击结果项通过回调返回该船 mmsi。

4.1 创建

参数	类型	说明
map	Map	地图对象
divid	string	div 容器 ID（检索输入框渲染到该容器内）
options	Object	配置信息

options 参数表：

参数	说明
itemClickCallBack	点击结果回调函数，返回：mmsi

4.2 完整示例

效果示意：容器中出现一个搜索输入框，输入"新洋山"等关键字后下方弹出候选船舶列表（船名 + MMSI），点击某一条目后触发 itemClickCallBack 并返回该船 MMSI。

5. 历史航次服务 voyageService

历史航次服务提供两类查询：查询船舶当前航次数据、查询船舶指定时间段的历史航次数据。

5.1 创建

初始化后通过 map.voyageService 访问。

5.2 方法

方法	说明
getCurrentByUrl(mmsi, callback)	查询当前航次数据；`mmsi` 为船舶 MMSI，`callback(result)` 接收查询结果
getHisByUrl(mmsi, btime, etime, callback)	查询历史航次数据；`btime`/`etime` 为起止时间，`callback(result)` 接收查询结果

5.3 完整示例

6. 注意事项与 FAQ

6.1 注意事项

所有服务均需在 new ShipxyAPI.Map("map", {ak: "您的密钥"}) 创建地图之后初始化；密钥占位符 您的密钥 需替换为实际申请的 ak。

trackDrawSymbol 与 seachShipService 的方法名为小写开头（与官方文档保持一致，注意拼写：seachShipService 中的 "seach" 为官方命名，并非笔误）。

航线绘制：drawTrack() 之前必须先创建 ShipxyAPI.trackDrawSymbol(_map, options) 对象；showTrack(items) 用于数据回显时，items 中 lat/lng 为必填字段，缺失会导致节点无法绘制。

航线数据持久化：通过 options 的 callBack 拿到节点数组后自行存储（如提交到后端），需要回显时再调用 showTrack(items)。

areaPlayService 的 area 参数是整数型经纬度（度 × 10^6 取整），不是浮点经纬度；minTime/maxTime 单位为秒，而 beginTime 单位为毫秒，注意区分。

areaPlayService 需要配套的数据接口（getDataByURL），示例中的内网地址 //192.168.1.22:8083/AreaPlay/GetData 仅为演示，需替换为实际部署的数据服务。

AreaTrackReplayService 初始化后不会自动弹出任务面板，需调用 map.areaTrackReplayService.openCreateTaskLayer() 打开。

船舶检索服务的容器 div 需自行设置定位样式（如 position: relative; z-index: 888），否则可能被地图遮挡。

历史航次服务为异步查询，结果通过 callback 返回，需考虑网络异常时的提示处理。

6.2 FAQ

Q：航线绘制完成后如何拿到航线数据？
A：在 options 的 callBack: function (item) {} 中接收，item 即航线节点数组（含 lat/lng/cog 等字段），可保存后在需要时用 showTrack(items) 回显。

Q：如何让航线节点显示自定义文字（如转向点说明）？
A：使用演示示例中的 setItemTextById（单个）或 setItemTextByTextItems（批量）方法，传入 {id, caText, pDistanceText, markerText}。

Q：区域回放打开面板后没有数据？
A：通过 afterInitReplayData(hasData) 回调判断是否加载到数据；若 hasData 为 false，检查圈选区域与时间段内是否确有船舶、以及密钥是否具备区域回放权限。

Q：船位回放 areaPlayService 与区域船舶轨迹回放 AreaTrackReplayService 有什么区别？
A：areaPlayService 面向"已有数据接口 + 固定区域/时间段"的轻量船位重现，参数全部在代码中给定；AreaTrackReplayService 提供完整的任务面板交互（圈选区域、选择时间、播放控制、船舶列表），适合直接交付终端用户使用。

Q：seachShipService 回调只返回 mmsi，如何获取船名等更多信息？
A：该服务回调仅返回 mmsi（官方文档定义）。拿到 mmsi 后可联动船位展示/轨迹查询等其他服务获取并展示详细信息。

Q：getHisByUrl 的 btime/etime 是什么格式？
A：为起止时间参数，与查询接口约定的时间字符串一致（示例采用 "yyyy-MM-dd HH:mm:ss" 格式），具体以服务端接口要求为准。

7.6 航线绘制与区域回放服务

1. 航线绘制服务 trackDrawSymbol#

1.1 创建#

1.2 options 参数表#

1.3 items 航线节点数组结构#

1.4 方法#

1.5 完整可运行示例（整理自 a1_4.htm）#

1.6 效果示意（文字描述）#

2. 船位回放服务 areaPlayService#

2.1 创建#

2.2 options 参数表#

2.3 area 参数格式说明#

2.4 完整示例#

3. 区域船舶轨迹回放服务 AreaTrackReplayService#

3.1 创建#

3.2 options 参数表#

3.3 方法#

3.4 完整示例（整理自 b1_7.htm）#

4. 船舶检索服务 seachShipService#

4.1 创建#

4.2 完整示例#

5. 历史航次服务 voyageService#

5.1 创建#

5.2 方法#

5.3 完整示例#

6. 注意事项与 FAQ#

6.1 注意事项#

6.2 FAQ#