02 船舶与轨迹绘制实践

目标：在私有化海图上，用 Canvas 复现在线平台船位展示服务（ShipxyAPI.ShipService / CanvasShipService）与历史轨迹服务（ShipxyAPI.TrackService / TrackServiceImpl）的业务绘制效果：海量船舶渲染、船型符号、选中交互、红色虚线轨迹、停/慢状态标记、起终点标记、轨迹回放播放器。数据全部来自客户内网自建接口。

效果图：

船舶分布绘制（本章第 2 节效果）：
02-船舶分布绘制.png

历史轨迹与回放（本章第 4 节效果）：
02-历史轨迹与回放.png

0. 官方在线效果对照（务必先读）

以下规则直接取自船讯网在线 demo（api.shipxy.com/h5s/api/3.5/demo/ 2.1/2.2/2.5/2.6 示例）的实际运行效果，私有化实现必须与之一致：

船舶颜色不按航速区分。默认配色只有两类：

区域船（shiptype=1）：统一默认黄色 #FFFF66，按航向定向的三角符号，无船名标注；

船队船（shiptype=2 且 istop=true）：按分组统一颜色（船队分组 group.colorhex，示例取绿色 #00CC00），整队同色、置于区域船之上（置顶），并带橙色标注框 #ED5835，框内白字 S + 船名；

选中船：金色高亮圈 #ffd700 + 船名/航速标签（setSelectedShip 效果）；

被删除标记的船用 dShipColor: #FF6437（deleteShipByShipID 过程色）。

官方提供 resetShipColorCallBack(ship) 钩子：绘制前按船逐个回调返回颜色，自定义配色（例如把客户自有船队刷成企业 VI 色）走这里，而不是按速度改色。

轨迹线：tomato 红色 2px 虚线（dash:true, dashArray:[5,5]），节点带时间标注，停泊点标红色「停」、低速点标绿色「慢」，起点绿圈 #06c84a、终点红圈 #f70006；回放开启时底部弹出深色播放器面板（显示字段复选框：船名/MMSI/船首向/航迹向/速度 + 时间轴）。

轨迹层 options（在线 demo 实测）：

{ lineColor:'tomato', lineWeight:2, dash:true, dashArray:[5,5], circleOverColor:'yellow', isDilute:true, isEnablePlayer:true }

。

1. 与官方数据契约对齐：CanvasShip

官方 7.3 中，区域船/船队船在内部统一为 CanvasShip 对象数组，关键字段（官方示例构造 new CanvasShip() 后逐个赋值）：

私有化要领：让内网船位接口直接返回这个结构的 JSON 数组，前端绘制代码就与在线平台的数据契约完全一致——将来若迁回在线平台（或使用船讯网离线数据包），业务代码零改动。addShips / addFleetShips 的必填字段为 shipid / mmsi / lat / lng，其余字段用于符号、tooltip、过滤。

官方 getAreaShipsCallBack 的定位就是"区域船数据由外部数据源提供"，私有化场景正是它的目标形态；我们自实现时把"外部数据源"落到本地接口即可。

2. Canvas 船舶层（复刻 CanvasShipService）

2.1 设计对照

官方能力	私有化实现
Canvas 海量绘制（数万级流畅）	单个全屏 Canvas + `requestAnimationFrame` 重绘
`enableAreaShip` 区域船自动刷新	地图 `moveend` + `delayTime` 定时器拉取可视范围船位
`delayTime: 5000` 刷新间隔	同名配置
`shipOptions` 船舶符号设置	符号大小随缩放级别调整
`tooltip_fields` 悬浮字段	鼠标命中检测后渲染 HTML tooltip
`addSelectedListener` 选中监听	Canvas 命中检测 + 选中高亮
`setFilter` 条件过滤	`filterFn` 谓词
`locationShip` 单船定位	`locate(mmsi)` 居中 + 高亮
`drawShipsEndCallBack` 绘制完成回调	`onDrawEnd({count})`

2.2 完整实现 `ShipCanvasLayer.js`

2.3 使用示例（完整页面骨架）

2.4 内网数据接口约定（服务端示例，Node Express）

官方 Getmanyship 接口的数据口径可作字段参考：lat/lon 为 ×10⁶ 定点数、hdg/cog 为 ×100 定点、width/length 为 ×10（分米）；自建接口建议直接返回浮点数（如上例），避免前端到处除系数。

3. 船舶符号与状态细则

船头向 hdg 与航迹向 cog：符号旋转优先用 hdg，缺失时回落 cog（在线平台同款回落逻辑）。hdg=511（不可用值）时也回落。

navistatus（AIS 航行状态）：0 在航（动力）、1 锚泊、5 系泊、8 捕鱼等；用于命中悬浮信息与过滤统计。注意颜色不随状态/速度变化——在线效果中所有区域船一律默认黄，仅船队船按分组着色、选中船加金色高亮圈。

船型 newtype：官方按 newtype 区分货船/油轮/渔船/客船等符号形状。自实现时至少分三类形状：尖头箭头（普通机动船）、双体矩形（拖带/工程船）、圆点（其他/未分类），渔船可加尾拖线标记。

性能红线：一次绘制 5 万艘以内直接全量重绘即可（Canvas 单帧毫秒级）；超过 10 万建议先做网格抽稀（每屏幕格子只留 N 艘），再进入绘制。

4. 历史轨迹绘制与回放（复刻 TrackService）

4.1 官方用法与数据契约

官方 7.4：ShipxyAPI.TrackService(map) 后，map.trackService.addAndShow(trackId, tracks, options, ship) 绘制自有轨迹数据；tracks 为 Track 对象数组，必需字段 utc / sog / lng / lat：

addAndShowByUrl(mmsi, btime, etime, options) 是"自动拉数"版本（btime/etime 为秒级时间戳）——私有化把"自动拉数"指向内网接口即可，其余绘制逻辑相同。

4.2 私有化实现 `TrackLayer.js`（红色虚线 + 节点时间标注 + 停/慢标记 + 回放）

/* 时间格式化：MM-dd HH:mm（在线节点标注同款样式） */
function fmtTime(utc) {
var d = new Date(utc * 1000);
function p(n) { return (n < 10 ? "0" : "") + n; }
return p(d.getMonth() + 1) + "-" + p(d.getDate()) + " " +
p(d.getHours()) + ":" + p(d.getMinutes());
}


### 4.3 使用示例（含官方同款深色回放播放器 UI）

```html
<div id="map" class="my-map"></div>
<!-- 回放播放器（官方轨迹回放播放器等价 UI） -->
<div id="player" style="position:absolute;left:0;bottom:0;width:100%;z-index:999;
     background:#1d374c;color:#e6eef5;padding:8px 14px 10px;display:none;
     box-shadow:0 -2px 8px rgba(0,0,0,.35);font:12px/1.7 'Microsoft YaHei',sans-serif">
  <div>
    <b>显示字段：</b>
    <label><input type="checkbox" checked onchange="trackUI.f.name=this.checked"/>船名</label>
    <label><input type="checkbox" checked onchange="trackUI.f.mmsi=this.checked"/>MMSI</label>
    <label><input type="checkbox" checked onchange="trackUI.f.hdg=this.checked"/>船首向</label>
    <label><input type="checkbox" checked onchange="trackUI.f.cog=this.checked"/>航迹向</label>
    <label><input type="checkbox" checked onchange="trackUI.f.sog=this.checked"/>速度</label>
  </div>
  <div style="display:flex;align-items:center;gap:10px;margin-top:6px">
    <button onclick="trackUI.toggle()" style="width:30px;height:30px;border-radius:50%;
            border:none;background:#ff8573;color:#fff;cursor:pointer">⏸</button>
    <span id="curTime" style="font:12px Consolas,monospace;color:#fff"></span>
    <input type="range" min="0" max="1000" value="0" style="flex:1" oninput="trackUI.seek(this.value)"/>
    <span style="font-size:11px;color:#9fb8cd">起始 ～ 结束时间</span>
  </div>
</div>

<script>
  var track = new TrackLayer().addTo(_map);   // options 默认即官方效果：tomato 虚线 + 节点标注 + 停/慢
  track.onPlayerChange = function (st) {
    document.getElementById("pinfo").textContent =
      st.idx + " / " + st.total + (st.playing ? "  播放中" : "  已暂停");
  };

  // 从内网轨迹库拉取（对应 addAndShowByUrl 的私有化版）
  fetch("http://localhost:9000/api/track?mmsi=413555666&btime=1717200000&etime=1717804800")
    .then(function (r) { return r.json(); })
    .then(function (tracks) {           // Track 数组：utc(秒)/sog/lng/lat/cog
      track.addAndShow("trk-001", tracks, { mmsi: 413555666, length: 450, width: 100 });
      document.getElementById("player").style.display = "block";
      track.showTrackAnalysis("analysis");   // 航速曲线（对应 showTrackAnalysis）
    });
</script>

4.4 抽稀（对应 isDilute）

官方 isDilute: true 为抽稀显示。本地实现推荐 Douglas-Peucker：

注意：抽稀只用于显示，航速曲线分析与回放仍用全量点，否则速度峰值会被抹平。

5. 本章效果自查

区域船随地图拖动/缩放自动刷新（delayTime 间隔轮询），海量船舶 Canvas 绘制流畅；

船舶符号按航向定向：区域船一律默认黄 #FFFF66、船队船按分组统一色置顶并带 “S 船名” 标注框、选中船金色高亮圈（颜色与航速无关）；

悬浮显示 MMSI/呼号/航速/航向/时间；点击选中出现金色高亮圈与船名；

setFilter 生效（过滤后仅显示过滤集）；locationShip 可居中定位单船；

轨迹为 tomato 红色 2px 虚线，节点带时间标注与「停」「慢」状态标记，起点绿圈、终点红圈、悬浮信息齐备；

回放播放器可播放/暂停/停止/倍速，回放船标沿线移动；航速曲线弹框可展示。

至此业务船位/轨迹全部跑通，继续文档 03：气象图层。

02 船舶与轨迹绘制实践

0. 官方在线效果对照（务必先读）#

1. 与官方数据契约对齐：CanvasShip#

2. Canvas 船舶层（复刻 CanvasShipService）#

2.1 设计对照#

2.2 完整实现 ShipCanvasLayer.js#

2.3 使用示例（完整页面骨架）#

2.4 内网数据接口约定（服务端示例，Node Express）#

3. 船舶符号与状态细则#

4. 历史轨迹绘制与回放（复刻 TrackService）#

4.1 官方用法与数据契约#

4.2 私有化实现 TrackLayer.js（红色虚线 + 节点时间标注 + 停/慢标记 + 回放）#

4.4 抽稀（对应 isDilute）#

5. 本章效果自查#