7.4 历史轨迹服务
适用版本：船讯网海图 GIS 平台 ElaneMap H5 API 3.5 前置阅读：建议先阅读《7.1-快速入门：从注册到接入》《7.2-地图引擎基础：地图控制与业务绘制》《7.3-船位展示服务》，了解地图初始化、密钥（ak）配置与船位服务后再阅读本篇。
1. 服务概述
1.1 什么是轨迹服务
addAndShowByUrl）add / addAndShow）showTrackAnalysis）isEnablePlayer）items 中，元素结构为 {trackId: trackId, data: tracks, symbol: null, options: options, ship: ship}。1.2 创建方式
| 参数 | 类型 | 说明 |
|---|---|---|
| map | L.Map | 地图对象 |
| options | Object | 设置信息（可选） |
map.trackService 被实例化为 TrackServiceImpl 对象，下文所有方法均通过它调用。2. 轨迹查询与展示
2.1 完整示例（轨迹查询）
addAndShowByUrl 自动从数据接口拉取轨迹数据并绘制。addAndShowByUrl(mmsi, btime, etime, options, callBack, tp, vy, auto_viewzoom)：btime/etime 为秒级 Unix 时间戳；tp 为轨迹数据类型（0：普通，1：抽稀，2：完整，默认 0）；vy 为航程（0：无，1：有，默认 0）；auto_viewzoom 是否自适应展示，默认 true。removeAll() 一次清除全部轨迹。2.2 轨迹 options 参数表
add / addAndShow / addAndShowByUrl 的 options，以主文档第 5 节（轨迹服务）与 TrackServiceImpl 类文档为准。| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| lineColor | 颜色 | - | 轨迹线颜色 |
| lineWeight | number | 1 | 线粗细 |
| circleOverColor | 颜色 | - | 拐点（轨迹点）鼠标滑过时的颜色 |
| dash | boolean | false（实线） | 是否为虚线，true：虚线，false：实线（注：主文档第 5 节注释表述为"true：实线"，与类文档及官方示例相反，以 TrackServiceImpl 类文档与示例用法为准） |
| dashArray | Array | [5,5] | 虚线参数（虚线段间隔） |
| startShow | boolean | true | 是否显示"起点"图标 |
| endShow | boolean | true | 是否显示"终点"图标 |
| directionShow | boolean | false | 轨迹方向三角是否展示 |
| isDilute | boolean | true | 是否抽稀 |
| isEnablePlayer | boolean | false | 是否需要播放轨迹（为 true 时显示轨迹回放播放器） |
| isShowLable | boolean | true | 是否显示 lable（轨迹点信息标签） |
| lableMap | Object | null | 自定义附加 lable 显示，如 {"time": "xxxxx"} |
| lableFields | Array | ["name", "mmsi", "sog", "cog", "utc", "kn"] | lable 显示的字段，可选 key：["name","mmsi","sog","cog","utc","kn","ed","md","draught","dest","eta","navistatus","rot","hdg"] |
| tipHideTimeOut | number | 8000 | 轨迹/航线 tip 超时关闭时间设置（毫秒） |
| startCircleType | number | 1 | 起始圆圈样式类型，0：不显示，1：同心圆，2：普通圆圈（与拐点相同） |
| endCircleType | number | 1 | 结束圆圈样式类型，取值同 startCircleType |
| startCircleColor | 颜色 | '#06c84a' | 起始圆圈填充色 |
| endCircleColor | 颜色 | '#f70006' | 结束圆圈填充色 |
| shipColor | 颜色 | - | 船舶颜色（配合 addAndShowByUrl 使用） |
| shipLineColor | 颜色 | - | 船舶边框颜色（配合 addAndShowByUrl 使用） |
lableFields 各字段含义与展示格式：| 字段 | 含义 | 展示格式 |
|---|---|---|
| name | 船名 | 船名：{1} |
| mmsi | MMSI | MMSI：{1} |
| sog | 速度 | 速度：{1}节 |
| cog | 航迹向 | 航迹向：{1}度 |
| utc | 时间 | 时间：{1} |
| kn | 距起点距离 | 距起点距离：{1}海里 |
| ed | 距终点距离 | 距终点距离：{1}海里 |
| md | 下一段航程 | 下一段航程：{1}海里 |
| draught | 吃水 | - |
| dest | 目的地 | - |
| eta | 预到时间 | - |
| navistatus | 航行状态 | - |
| rot | 旋转角速度 | - |
| hdg | 船首向 | - |
2.3 addAndShow 参数说明
addAndShow(trackId, tracks, options, ship, auto_viewzoom) 将已有轨迹数据添加到地图并展示，如果 options 中设置了 isEnablePlayer: true，会同时显示播放器。| 参数 | 类型 | 说明 |
|---|---|---|
| trackId | String | 轨迹 ID，轨迹在轨迹容器中的唯一标识 |
| tracks | Array | Track 对象集合，每个轨迹点必填 utc（时间，秒）、sog（航速）、lng（经 度）、lat（纬度），可选 hdg（船首向）、from（数据来源）等 |
| options | Object | 设置信息，见 2.2 参数表 |
| ship | CanvasShip | 船舶静态数据 {name: 船名, mmsi: MMSI, from: 数据来源, navistatus: 航行状态, draught: 吃水}；回放时可含 length（船长）、width（船宽）用于绘制回放船型 |
| auto_viewzoom | boolean | 是否自适应展示（地图视野自动包含整条轨迹），默认 true |
{trackId: trackId, data: [], symbol: {}, options: {}, ship: ship}。3. 自定义轨迹
addAndShow 绘制。utc（秒级时间戳）、sog（航速）、lng、lat。trackId（示例中 "truck_id_001"）自行指定，后续 show/hide/remove/has/get 均通过该 ID 操作。4. 轨迹航速曲线
showTrackAnalysis 在地图上弹出航速曲线分析弹框：横轴为时间，纵轴为航速，直观展示该时间段内船舶的加减速过程。关闭弹框使用 _closeAllTrackAnalysisPopups()。showTrackAnalysis(mmsi, btime, etime, going, tp, vy, popupOptions)：前 6 个参数与 getTrackInfoByUrl 相同（going 是否连续查询、tp 数据类型、vy 航程），最后一个是弹框配置 {width, height, offset}，offset 为 [上、右、下、左] 四向偏移。offset 数组中不需要的方向可置 null。5. 轨迹回放
isEnablePlayer: true，轨迹绘制完成后会自动弹出轨迹回放播放器：船舶符号沿轨迹线逐点移动，播放器提供播放/暂停、进度拖动、倍速等控制，并随播放位置刷新当前轨迹点的速度、时间等信息。isEnablePlayer: true（默认 false）。addAndShow 与 addAndShowByUrl 均支持；主文档第 5 节注明："添加轨迹并显示，如果设置了需要播放，会显示播放器"。ship 参数提供船舶静态数据（name、mmsi、length、width 等），用于回放时绘制船名与按真实船长船宽比例绘制的船型；shipColor、shipLineColor 控制回放船的颜色与边框颜色。remove(trackId) 删除指定轨迹或 removeAll() 清空全部轨迹后，对应播放器随之消失。6. TrackServiceImpl 方法速查表
| 成员 | 类型 | 说明 |
|---|---|---|
| items | Object | 轨迹容器，所有轨迹图形对象，元素结构 {trackId: trackId, data: tracks, symbol: null, options: options, ship: ship} |
| 方法名 | 功能 | 参数 | 返回值 |
|---|---|---|---|
| add(trackId, tracks, options, ship) | 增加轨迹（ 不自动定位视野） | trackId：String，轨迹 ID；tracks：Array，Track 对象集合；options：Object，设置信息；ship：CanvasShip，船舶静态数据 {name, mmsi, from, navistatus, draught} | Object，{trackId, data, symbol, options, ship} |
| addAndShow(trackId, tracks, options, ship, auto_viewzoom) | 增加轨迹并展示 | 同 add；auto_viewzoom：boolean，是否自适应展示，默认 true | Object，结构同上 |
| addAndShowByUrl(mmsi, btime, etime, options, callBack, tp, vy, auto_viewzoom) | 根据参数自动获取轨迹数据并添加展示 | mmsi：string；btime/etime：number，起止时间戳（秒）；options：Object；callBack：function；tp：number，轨迹数据类型 0 普通/1 抽稀/2 完整，默认 0；vy：number，航程 0 无/1 有，默认 0；auto_viewzoom：默认 true | - |
| show(trackId, auto_viewzoom) | 显示指定轨迹 | trackId：String；auto_viewzoom：boolean，是否自适应展示，默认 true | - |
| _viewAllTrackInMap(trackId) | 可视范围显示指定或所有轨迹 | trackId：string，轨迹 ID，可为空，为空则适应所有轨迹 | - |
| hide(trackId) | 隐藏指定轨迹（并刷新区域船层级） | trackId：String | boolean |
| hideAll() | 隐藏全部轨迹（并刷新区域船层级） | 无 | - |
| remove(trackId) | 删除指定轨迹（并刷新区域船层级） | trackId：String | - |
| removeAll() | 删除所有轨迹 | 无 | - |
| getItems() | 获取轨迹对象集合 | 无 | Object |
| getLength() | 获取轨迹数量 | 无 | number |
| getValues() | 获取所有轨迹集合 | 无 | Array |
| getKeys() | 获取所有轨迹 ID 集合 | 无 | Array |
| getTrackInfoByUrl(mmsi, btime, etime, going, tp, vy) | 查询轨迹数据 | mmsi：string；btime/etime：number，起止时间戳（秒）；going：boolean，是否连续查询，默认 false；tp：number，0 普通/1 抽稀/2 完整，默认 0；vy：number，0 无/1 有，默认 0 | Array |
| has(trackId) | 是否包含指定轨迹 | trackId：String | boolean |
| hasTrackIsShow() | 是否有轨迹显示 | 无 | boolean |
| get(trackId) | 获取指定轨迹 | trackId：String | 轨迹对象 |
| showTrackAnalysis(mmsi, btime, etime, going, tp, vy, popupOptions) | 弹出轨迹航速曲线分析弹框（官方示例 b1_5_2 提供） | mmsi、btime、etime、going、tp、vy 同 getTrackInfoByUrl；popupOptions：{width, height, offset:[上,右,下,左]} 弹框位置配置 | - |
| _closeAllTrackAnalysisPopups() | 关闭全部航速曲线分析弹框（官方示例 b1_5_2 提供） | 无 | - |
7. 效果示意（文字描述）
8. 注意事项
1.
btime/etime/track.utc 均为秒级 Unix 时间戳，使用 JavaScript Date.parse(...) 或 getTime() 得到的是毫秒，务必除以 1000。2.
dash: true // 是否为虚线 使用，请以"true 为虚线、false 为实线（默认）"为准。3.
tp: 1（抽稀）降低数据量；需要完整轨迹点（如精确里程统计）时传 tp: 2。4.
5.
addAndShow/addAndShowByUrl/show 默认 auto_viewzoom: true，会强制改变地图视野；多条轨迹对比展示时，后续添加建议传 false，或用 _viewAllTrackInMap() 统一适应所有轨迹。6.
trackId 是轨迹在容器中的唯一键，重复添加同一 ID 会覆盖/冲突，添加前可用 has(trackId) 判断，或先 remove(trackId)。7.
isShowLable 默认 true，lableFields 控制轨迹点悬浮标签显示的字段；tipHideTimeOut（默认 8000 毫秒）控制 tip 自动关闭时间。8.
getTrackInfoByUrl/showTrackAnalysis 的 going 参数用于连续查询场景（分段拉取长时间范围数据），默认 false。9.
9. FAQ
ShipxyAPI.TrackService(map) 与 map.trackService 是什么关系？A：调用
ShipxyAPI.TrackService(map) 开启轨迹服务后，map.trackService 被实例化为 TrackServiceImpl 对象，后续所有轨迹操作都通过它完成。A：不需要。构造 Track 对象数组（必填 utc/sog/lng/lat）后直接调用
addAndShow(trackId, tracks, options, ship) 即可，见"自定义轨迹"示例。A：为每条轨迹指定不同的
trackId 添加；用 hide(trackId) 隐藏、show(trackId) 重新显示、hasTrackIsShow() 判断当前是否有轨迹显示，最后用 _viewAllTrackInMap() 让视野适应全部轨迹。A：
dash: false（默认即实线）；需要虚线时设 dash: true 并用 dashArray: [5, 5] 调整虚线间隔。A：
startShow/endShow 控制起终点图标显示；startCircleType/endCircleType 取 0（不显示）、1（同心圆，默认）、2（普通圆圈）；填充色用 startCircleColor（默认 #06c84a）、endCircleColor（默认 #f70006）。A：使用
getTrackInfoByUrl(mmsi, btime, etime, going, tp, vy)，返回轨迹数据数组（Array），不经过地图绘制；也可用 addAndShowByUrl 的 callBack 回调在数据加载后处理。A：确认 options 中
isEnablePlayer: true（默认 false），且轨迹数据按时间顺序包含有效的 utc、lat、lng；播放器随轨迹删除（remove/removeAll）而消失。A：通过
showTrackAnalysis 最后一个参数调整：{width: '500px', height: '350px', offset: [上, 右, 下, 左]}，不需要的偏移方向传 null；统一关闭用 _closeAllTrackAnalysisPopups()。