xt-track-map
v1.0.2
Published
## 1、概述
Downloads
15
Readme
xt-track-map 地图组件库使用手册
1、概述
xt-track-map 是一个基于 Vue 3 + 高德地图开发的地图工具组件库，包含轨迹回放和地图选点（电子围栏）两个核心组件，支持在项目中快速集成车辆轨迹播放、地点搜索选点、围栏绘制等功能。
2、主要功能
| 组件 | 功能 | 说明 | |------|------|------| | XTTrackMap | 轨迹回放 | 支持车辆轨迹动画播放、多倍速、进度拖拽 | | XTTrackMap | 播放控制 | 播放/暂停/重播/重置，进度条点击和拖拽跳转 | | XTTrackMap | 倍速播放 | 支持 1x、8x、16x、32x、64x、128x、256x | | XTTrackMap | 自定义样式 | 车辆图标、轨迹颜色、线宽均可配置 | | XTTrackMap | 信息面板 | 右侧展示车辆信息、轨迹统计 | | XTPointSelectMap | 地图选点 | 点击地图任意位置选取坐标点 | | XTPointSelectMap | 地点搜索 | 输入关键字搜索地点并定位 | | XTPointSelectMap | 电子围栏 | 以选取的点为中心绘制圆形围栏 | | XTPointSelectMap | 多模式 | 支持新增、编辑、查看三种模式 |
3、安装与注册
3.1 安装
npm install xt-track-map或本地开发使用 npm link：
# 在组件库目录
nvm use v16.20.0
npm run lib
npm link
# 在使用项目目录
npm link xt-track-map3.2 全局注册
// main.js
import { createApp } from 'vue'
import App from './App.vue'
import XTTrackMap from 'xt-track-map/packages'
import 'xt-track-map/dist/xt-track-map.css'
const app = createApp(App)
app.use(XTTrackMap)
app.mount('#app')4、XTTrackMap 轨迹回放组件
4.1 Props 属性
| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | trackData | Object | null | 轨迹数据（见下方格式） | | carIcon | String | 内置SVG | 车辆图标（支持URL、base64、import图片） | | carIconSize | Number | 32 | 车辆图标尺寸（px），范围 16~100 | | passedTrackColor | String | '#1677ff' | 已行驶轨迹颜色 | | fullTrackColor | String | '#aaaaaa' | 完整轨迹颜色（虚线） | | passedTrackWidth | Number | 5 | 已行驶轨迹线宽，范围 1~20 | | fullTrackWidth | Number | 4 | 完整轨迹线宽，范围 1~20 | | infoTitle | String | '基本信息' | 右侧面板自定义信息区标题 | | infoList | Array | null | 右侧面板自定义信息列表 |
4.2 trackData 数据结构
{
plateNo: '京A12345', // 车牌号（必填）
routeMil: 120.5, // 行驶里程，单位km
trackArray: [ // 轨迹点数组（必填）
{
lat: '39.90923', // 纬度（字符串）
lon: '116.397428', // 经度（字符串）
utc: '1700000000', // UTC时间戳（秒，字符串）
spd: '60', // 速度（km/h，字符串）
drc: '90', // 方向角（度，字符串）
mil: '0' // 累计里程（字符串）
}
]
}注意：trackData 变化时，组件会自动重置播放状态并重新绑制轨迹。适用于切换车辆或刷新轨迹数据的场景。
4.3 infoList 数据结构
[
{ label: '司机', value: '张三', highlight: false },
{ label: '车辆类型', value: '重型货车', highlight: true }
]4.4 播放控制说明
| 操作 | 说明 | |------|------| | 播放/暂停 | 点击播放按钮或底部 ▶/⏸ 切换 | | 重播 | 播放完毕后点击重播按钮，从起点开始 | | 重置 | 回到起点，停止播放 | | 倍速切换 | 点击倍速按钮组切换，播放中切换立即生效 | | 进度跳转 | 点击进度条任意位置跳转，支持拖拽 |
4.5 倍速实现原理
采用 跳帧 + 固定帧率 方案：
- 1x：每帧移动1个点
- 8x：每帧移动2个点
- 32x：每帧移动8个点
- 128x：每帧移动32个点
- 256x：每帧移动64个点
高倍速时帧间隔同步缩短，确保播放流畅且速度差异明显。
4.6 使用示例
<template>
<div style="height: 100vh;">
<XTTrackMap
:trackData="trackData"
:carIcon="carIcon"
:carIconSize="36"
passedTrackColor="#ff4d4f"
fullTrackColor="#bfbfbf"
:passedTrackWidth="6"
infoTitle="车辆详情"
:infoList="vehicleInfo"
/>
</div>
</template>
<script setup>
import { ref, onMounted } from 'vue'
import carIcon from '@/assets/logistics_car.png'
const trackData = ref(null)
const vehicleInfo = ref([
{ label: '司机', value: '张三' },
{ label: '车型', value: '重型货车', highlight: true }
])
onMounted(async () => {
const res = await fetch('/api/track?vehicleId=123')
trackData.value = await res.json()
})
</script>4.7 页面布局说明
┌─────────────────────────────────────────────────────┐
│ │
│ 地图区域 │ 右侧面板
│ │ ┌────────┐
│ 起点●━━━━━━━━━●终点 │ │ 车辆信息 │
│ 🚛 │ │ 轨迹统计 │
│ │ │ 当前速度 │
│ │ │ 播放进度 │
├─────────────────────────────────────────────────────┤ └────────┘
│ ⏱时间 ═══════════●═══════════ 时间 │
│ ▶ 倍速 [1x][8x][16x][32x][64x][128x][256x] 时长 │
└─────────────────────────────────────────────────────┘5、XTPointSelectMap 地图选点组件
5.1 Props 属性
| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | mode | String | 'add' | 模式：'add'（新增）、'edit'（编辑）、'view'（查看） | | initData | Object | null | 初始围栏数据（编辑/查看模式使用） | | minRadius | Number | 50 | 围栏半径最小值（米） | | maxRadius | Number | 50000 | 围栏半径最大值（米） |
5.2 Events 事件
| 事件名 | 参数 | 说明 |
|--------|------|------|
| point-selected | { lng, lat, name } 或 null | 选点状态变化时触发 |
| point-updated | { point: { lng, lat, name }, radius } | 点位或半径更新时触发 |
| save | { name, lng, lat, radius } | 保存围栏时触发 |
| clear | 无 | 删除围栏时触发 |
5.3 Expose 暴露方法
通过 ref 获取组件实例后可调用：
| 方法/属性 | 类型 | 说明 |
|-----------|------|------|
| selectedPoint | Ref | 当前选中的点 { lng, lat, name } |
| radius | Ref | 当前围栏半径 |
| savedFence | Ref | 已保存的围栏数据 |
| canSave | Computed | 是否可以保存 |
| setPoint(lng, lat, name) | Function | 手动设置点位 |
| clearPoint() | Function | 清除选点 |
| setRadius(number) | Function | 设置围栏半径 |
| updatePointName(name) | Function | 实时更新点位名称 |
| saveFence() | Function | 保存围栏 |
| editFence(data?) | Function | 进入编辑模式 |
| deleteFence() | Function | 删除围栏 |
| showSavedFence(lng, lat, name, r) | Function | 显示已保存的围栏 |
5.4 initData 数据结构
{
lng: 116.397428, // 经度（必填）
lat: 39.90923, // 纬度（必填）
name: '天安门', // 名称（可选）
radius: 1000 // 围栏半径，单位米（可选，默认500）
}5.5 模式说明
| 模式 | 地图点击 | 搜索框 | 可编辑 | 说明 | |------|----------|--------|--------|------| | add | ✓ | ✓ | ✓ | 新增围栏，点击地图选点 | | edit | ✓ | ✓ | ✓ | 编辑已有围栏，自动加载initData | | view | ✗ | ✗ | ✗ | 仅展示围栏，不可操作 |
5.6 操作说明
| 操作 | 说明 | |------|------| | 点击地图 | 在地图空白位置点击，添加选点 | | 搜索选点 | 输入关键字搜索地点，点击结果定位 | | 修改名称 | 父组件调用 updatePointName() 实时修改 | | 设置半径 | 父组件调用 setRadius() 更新围栏范围 | | 重新选点 | 调用 clearPoint() 清除当前选点 | | 保存围栏 | 调用 saveFence() 保存并触发 save 事件 | | 删除围栏 | 调用 deleteFence() 删除并触发 clear 事件 |
5.7 使用示例
<template>
<div style="display: flex; height: 600px;">
<!-- 地图组件 -->
<XTPointSelectMap
ref="mapRef"
mode="add"
@point-selected="onPointSelected"
@point-updated="onPointUpdated"
@save="onSave"
style="flex: 1;"
/>
<!-- 自定义右侧面板 -->
<div class="panel" style="width: 280px; padding: 16px;">
<div v-if="selectedPoint">
<input
:value="selectedPoint.name"
placeholder="输入位置名称"
@input="e => mapRef.updatePointName(e.target.value)"
/>
<p>经度：{{ selectedPoint.lng?.toFixed(6) }}</p>
<p>纬度：{{ selectedPoint.lat?.toFixed(6) }}</p>
<input
type="number"
:value="currentRadius"
@input="e => mapRef.setRadius(Number(e.target.value))"
/>
<button @click="mapRef.saveFence()">保存围栏</button>
<button @click="mapRef.clearPoint()">重新选点</button>
</div>
<div v-else>
<p>请在地图上点击选点</p>
</div>
</div>
</div>
</template>
<script setup>
import { ref } from 'vue'
const mapRef = ref(null)
const selectedPoint = ref(null)
const currentRadius = ref(500)
function onPointSelected(point) {
selectedPoint.value = point
}
function onPointUpdated({ point, radius }) {
selectedPoint.value = point
currentRadius.value = radius
}
function onSave(fence) {
console.log('围栏已保存：', fence)
// fence = { name, lng, lat, radius }
}
</script>5.8 页面布局说明
┌───────────────────────────────────────┬──────────────┐
│ 🔍 搜索框 │ │
│ │ 自定义面板 │
│ 地图区域 │ │
│ │ 名称输入框 │
│ 📍 选点标记 │ 经纬度显示 │
│ ╭─────────╮ │ 半径设置 │
│ │ 围栏圆 │ │ 保存按钮 │
│ ╰─────────╯ │ │
│ │ │
│ [ 点击地图任意位置选点 ] │ │
└───────────────────────────────────────┴──────────────┘6、注意事项
组件依赖高德地图 JS API 2.0，需要配置安全密钥（已内置）。
轨迹数据中的经纬度字段：
lon为经度，lat为纬度，均为字符串格式。XTTrackMap 的
trackData变化时会自动重置播放并重新绑定地图，无需手动调用重置方法。XTPointSelectMap 的右侧面板需要使用方自行实现，组件仅提供地图和选点逻辑。
在 Vite 项目中使用 npm link 时，需确保
dist/xt-track-map.css文件存在。构建组件库需要使用 Node.js v16.20.0 版本。