amap-trace-player

一个面向高德地图场景的轨迹回放包。当前版本提供这些核心能力：

• play / pause / resume / reset / stop
• 按进度或按毫秒跳转
• 动态倍速调整，支持 0.25x 和 0.5x
• 循环播放
• marker 朝向控制与地图跟随
• 经过轨迹点时触发 point 事件
• 在 AMap 适配层中可选渲染“已播放 / 未播放”轨迹

安装

npm install amap-trace-player

如果是从源码运行：

npm install
npm run build

示例

先根据 .env.example 创建 .env，并填入你的高德 JSAPI Key：

Copy-Item .env.example .env

POSIX shell 写法：

cp .env.example .env

然后运行：

npm run example:env

示例通过本地 Node 服务把 AMAP_JSAPI_KEY 注入到浏览器中的 /env.js，页面再用普通 <script> 方式加载高德 2.0。示例面板包含实时事件日志，地图上也会分别展示已播放与未播放轨迹，并且提供“按距离”和“按时长”两种回放示例可切换。

基本用法

import { AMapTracePlayer } from "amap-trace-player";

const player = new AMapTracePlayer({
  marker,
  map,
  follow: true,
  passedPolyline,
  remainingPolyline,
  mode: "distance",
  durationMs: 60000,
  playbackRate: 0.5,
  points: [
    [116.397428, 39.90923],
    [116.398428, 39.91023],
    [116.399428, 39.91123]
  ]
});

player.on("point", ({ index, snapshot }) => {
  console.log("经过点位:", index, snapshot.lng, snapshot.lat);
});

player.play();
player.setPlaybackRate(0.25);
player.seek(0.5);
player.reset();

durationMs 和 singleDuration 是什么意思

durationMs 表示总播放时长，单位毫秒。 singleDuration 表示时间模式下每一段的默认时长，单位毫秒。

它们的规则是：

• 在 mode: "distance" 下，仍然沿用旧逻辑，只使用 durationMs 作为整条轨迹总时长
• 在 mode: "time" 下，每段时长优先级是： 点自身 duration > 外层 singleDuration > 相邻点 time 差值 > 外层 durationMs 兜底

例如：

new AMapTracePlayer({
  points: [
    { lng: 116.397428, lat: 39.90923, duration: 1000 },
    { lng: 116.398428, lat: 39.91023 },
    { lng: 116.399428, lat: 39.91123, duration: 2000 }
  ],
  mode: "time",
  singleDuration: 500
});

这时每段时长会优先看点自身的 duration，没有再回退到 singleDuration。

配置项文档

完整配置说明见 docs/options.md。

事件文档

完整事件说明见 docs/events.md。

快速概览：

• play：进入 playing
• pause：进入 paused
• resume：从 paused 恢复
• reset：回到起点并变为 idle
• stop：停止并回到起点
• seek：调用 seek() / seekTo() 后触发
• tick：逐帧进度更新，seek 和 reset 后也会触发
• point：正常播放过程中经过轨迹点时触发
• finish：非循环模式下到达终点时触发
• error：预留给未来运行时错误派发

方法文档

完整方法说明见 docs/methods.md。

快速概览：

• play()：开始播放
• pause()：暂停播放
• resume()：从暂停恢复
• stop()：停止并回到起点
• reset()：立即恢复到初始状态
• seek(progress)：按 0 ~ 1 进度跳转
• seekTo(elapsedMs)：按毫秒跳转
• setPlaybackRate(rate)：修改倍速
• getPlaybackRate()：读取当前倍速
• getDuration()：读取总时长
• getState()：读取当前状态
• getSnapshot()：读取当前播放快照
• destroy()：销毁实例