🛣️ Leaflet.TrackMarker

A lightweight Leaflet plugin for animated markers that move along a path with automatic rotation.
让你的 Marker 沿路线自动移动，并智能旋转方向！

✨ 特性

• ✅ 沿路径自动移动（支持 GeoJSON LineString、坐标数组）
• ✅ 自动旋转：方向始终与路径方向一致（如车辆转向）
• ✅ 流畅动画：基于时间与速度的平滑移动
• ✅ 精确控制：支持 play(), pause(), seek(0.5), reset()
• ✅ 轻量依赖：仅依赖 Leaflet 和 Turf.js（可选打包）
• ✅ TypeScript 支持：完整类型定义
• ✅ 多格式输出：支持 ESM、CJS、UMD

📦 安装

npm / yarn / pnpm（推荐）

npm install leaflet.trackmarker @turf/turf

⚠️ 注意：@turf/turf 是运行时依赖，用于路径计算。

CDN（直接在浏览器使用）

<!-- 必须先加载 Leaflet -->
<script src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>
<script src="https://unpkg.com/@turf/[email protected]/turf.min.js"></script>

<!-- 加载 TrackMarker 插件 -->
<script src="https://unpkg.com/leaflet.trackmarker@latest/dist/index.umd.js"></script>

🚀 快速使用

1. 模块化项目（ESM / TypeScript）

import L from 'leaflet';  
import 'leaflet/dist/leaflet.css';
import 'leaflet.trackmarker';

// 定义路径（经纬度数组）
const route = [
  [116.4, 39.9],  // 北京
  [116.5, 39.95],
  [116.6, 39.92],
  [116.7, 39.98]
];

let line = L.polyline(route, {
  color: "red",
  weight: 5,
  opacity: 0.5,
});
line.addTo(map);
// 创建可移动的 Marker
const marker = L.trackMarker(line, {
  speed: 0.005,           // 速度：5 米/秒
  rotation: true,         // 启用自动旋转
  autoPlay: true,         // 自动开始
  rotationOffset: -90,      // 图标方向修正（例如：图标默认朝右）
}).addTo(map);

// 控制播放
marker.play();
marker.pause();
marker.seek(0.75); // 跳转到 75% 处
marker.reset();    // 重置到起点

2. 浏览器直接引入（UMD）

<script>
  const route = [
    [116.4, 39.9],
    [116.5, 39.95],
    [116.6, 39.92]
  ];
  let line = L.polyline(route, {
    color: "red",
    weight: 5,
    opacity: 0.5,
  });
  line.addTo(map);
  const marker = L.trackMarker(line, {
    speed: 0.005,
    rotation: true
  }).addTo(map);

  marker.play();
</script>

🛠️ API

trackMarker(line: L.Polyline, options?: TrackMarkerOptions)

创建一个可移动的 TrackMarker。

参数

| 参数 | 类型 | 说明 | |------|------|------| | line | L.Polyline | 路径图层 | | options | TrackMarkerOptions | 配置选项（见下表） |

TrackMarkerOptions

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | speed | number | 0.1 | 移动速度（km/s） | | autoPlay | boolean | true | 是否自动开始播放 | | rotation | boolean | true | 是否启用自动旋转 | | rotationOffset | number | 0 | 旋转偏移角度 | | onPause| () => void | - |暂停时的回调 | | onReset | () => void | - |重置到起点时的回调 | | onFinish | () => void| - |到达终点时的回调 | | onProgress |() => void | - |播放过程中持续触发的回调| | onBeforePlay |() => void | - |播放前触发的回调| | onPlay |() => void | - |播放时触发的回调|

方法

| 方法 | 说明 | |------|------| | .play() | 开始或继续播放 | | .pause() | 暂停播放 | | .reset() | 重置到路径起点 | | .seek(percent) | 跳转到路径的百分比位置（0-1） | | .setSpeed(speed) | 动态设置新速度 | | .getTraveled()| 获取已 traveled 的距离 | | .getTotalDistance() | 获取路径的总距离 |

🧪 示例

我们提供了一个完整的示例页面，请查看：

👉 example/index.html

或在线预览（发布后可部署到 GitHub Pages）。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

git clone https://github.com/ngd-b/leaflet.trackmarker.git
cd leaflet.trackmarker
pnpm install
pnpm dev

• src/：源码
• example/：示例页面
• dist/：构建输出

📄 许可证

MIT License

🚀 致谢

• Leaflet - 优秀的地图库
• Turf.js - 强大的地理计算工具

📌 让地图上的标记“活”起来！
Built with ❤️ for GIS developers.