轨迹回放播放器
CesiumTrackPlayer 是一个功能强大且轻量的 Cesium 轨迹回放封装类。它能将带时间戳的坐标数组转换为 Cesium 的动态属性,并自动托管时钟、相机、时间轴以及内置 UI 面板,实现丝滑的轨迹回放效果。
1. 引入文件
- 第一步:引入框架地图关键文件
- https://mhc.ixiera.com/mhc/main_min.js
- https://mhc.ixiera.com/mhc/Cesium-1.120/Build/Cesium/Cesium.js
- https://mhc.ixiera.com/mhc/Cesium3DTile.js
- 第二步:引入轨迹回放播放器文件
- https://mhc.ixiera.com/mhc/mchmap/TrackPlayer/js/CesiumTrackPlayer.min.js
2. 数据格式要求
load(data) 方法的 data 参数必须是一个数组,且至少包含两组数据。类内部会自动按时间进行升序排序。
时间字段 (time) 支持以下格式:
- ISO 8601 字符串:"2024-01-01T12:00:00Z" (推荐)
- 13位时间戳:1704100000000
- 相对秒数:0, 10, 20 (配合 options.startTime 使用)
- JS Date 对象:new Date()
位置字段 支持以下多种写法(任选其一):
// 写法 1:扁平经纬度 (最常见)
{ time: '...', lon: 116.39, lat: 39.90, height: 100 }
// 写法 2:嵌套 position 对象
{ time: '...', position: { lon: 116.39, lat: 39.90, alt: 100 } }
// 写法 3:数组格式
{ time: '...', position: [116.39, 39.90, 100] }
// 写法 4:Cesium 原生 Cartesian3 对象
{ time: '...', position: new Cesium.Cartesian3(x, y, z) }
3. 配置项 (options)
在实例化 new CesiumTrackPlayer(viewer, options) 时传入:
| 配置项 | 数据类型 | 默认值 | 说明 |
| 呈现形态 | |||
| modelUrl | String | null | 3D模型地址 (.glb/.gltf),优先级最高 |
| modelScale | Number | 1 | 模型缩放比例 |
| iconUrl | String | null | 2D图标地址,若未设模型则显示图标 |
| pointColor | Color | YELLOW | 若未设模型和图标,显示的圆点颜色 |
| 轨迹线 | |||
| showPath | Boolean | true | 是否显示轨迹线 |
| pathWidth | Number | 3 | 轨迹线宽度 |
| pathMaterial | Color | CYAN | 轨迹线颜色 |
| pathLeadTime | Number | undefined | 往后预测显示的秒数 (例如:5表示显示未来5秒的轨迹) |
| pathTrailTime | Number | undefined | 往后拖尾显示的秒数 (例如:10表示保留过去10秒的轨迹) |
| 时钟与播放 | |||
| speed | Number | 1 | 初始播放倍速 |
| loop | Boolean | true | true为循环播放,false为播放完停在终点 |
| shouldAnimate | Boolean | true | 加载后是否自动开始播放 |
| follow | Boolean | true | 相机是否锁定跟随模型 |
| flyTo | Boolean | true | 若未开启跟随,加载后是否自动飞向轨迹范围 |
| 插值算法 | |||
| interpolation | String | 'Lagrange' | 'Lagrange' 或 'Hermite' |
| interpolationDegree | Number | 1 | 阶数越高越平滑,但过高会在急转弯处产生“鼓包” |
| 模型朝向 | |||
| modelHeadingOffset | Number | 0 | 模型自身航向角修正(例如模型车头朝左,可填入 90 修正) |
| orientationStopThreshold | Number | 0.1 | 速度低于此值(m/s)视为静止,保持静止朝向防抖动 |
| orientationMaxPitch | Number | null | 俯仰角限幅(度),防止高度突变时模型翻跟头 |
| 外部时间 | |||
| startTime | String/Date | null | 强制指定起点时间 |
| stopTime | String/Date | null | 强制指定终点时间 |
| 回调钩子 | |||
| onTick | Function | null | 每帧触发 (time, entity, self) |
| onPlay | Function | null | 播放时触发 |
| onPause | Function | null | 暂停时触发 |
| onStop | Function | null | 停止时触发 |
4. API 方法
通过 player.xxx() 来动态控制:
player.load(data)
加载轨迹数据,返回创建的Cesium.Entity实例。会自动销毁旧轨迹。player.play()
开始/继续播放。如果当前已经处于终点,会自动重置到起点并重新播放。player.pause()
暂停播放,模型停在当前位置。player.stop()
停止播放,并将时钟强制重置到起点。player.seek(time)
跳转到指定时间(支持传入与数据格式相同的time值)。player.setSpeed(multiplier)
动态设置倍速(例如player.setSpeed(10))。player.setFollow(follow)
动态设置相机是否跟随实体(传入true/false)。player.destroy()
销毁轨迹实体并解除所有事件监听。player.isPlaying()
返回当前是否处于播放状态 (Boolean)。player.enableUI(uiOptions)
开启悬浮 UI 控制面板。uiOptions.container: 挂载的 DOM 节点,默认是viewer.container。uiOptions.onReload: 点击 UI 上的“重新加载”或拖拽参数变更后触发的回调,需要在该回调中重新调用player.load(data)。
5. 完整代码实例
// 1. 初始化地图Viewer
const viewer = new Cesium.Viewer('cesiumContainer');
// 2. 准备轨迹数据(支持多种格式,下面是最基础的一种)
const trackData = [
{ time: '2024-01-01T00:00:00Z', lon: 116.391, lat: 39.907, height: 100 },
{ time: '2024-01-01T00:00:10Z', lon: 116.401, lat: 39.917, height: 200 },
{ time: '2024-01-01T00:00:20Z', lon: 116.411, lat: 39.927, height: 300 },
];
// 3. 实例化播放器
const player = new CesiumTrackPlayer(viewer, {
modelUrl: 'path/to/your/model.glb', // 传入模型地址
showPath: true, // 显示轨迹线
speed: 5, // 5倍速
loop: false, // 不循环,播完停在终点
});
// 4. 加载数据并开启内置 UI 面板
player.load(trackData);
player.enableUI({
// 如果用户在 UI 上修改了朝向或插值阶数,点击重新加载时触发此回调
onReload: (playerInstance) => {
playerInstance.load(trackData); // 重新灌入数据即可自动重载
}
});
6. 效果展示

Demo地址:https://mhc.ixiera.com/mhc/mchmap/TrackPlayer/index.html
扫一扫