Vue项目实战：基于AMapUI组件库与amap-jsapi-loader构建动态轨迹地图应用

最新推荐文章于 2026-04-18 05:12:29 发布

原创

最新推荐文章于 2026-04-18 05:12:29 发布 · 741 阅读

1. 项目初始化与环境准备

大家好，我是老张，一个在前后端摸爬滚打了十来年的老码农。最近在做一个智慧物流的Vue项目，里面有个核心需求，就是要在网页上实时展示车辆的动态行驶轨迹，并且能在地图上打上我们自己的品牌图标。这活儿听起来挺酷，但一开始也让我挠头，毕竟地图开发水挺深。不过，折腾了一圈下来，我发现用高德地图的JS API，配合它的官方UI组件库AMapUI，在Vue项目里实现这个功能，其实比想象中要简单和优雅。

简单来说，我们今天要聊的就是怎么在Vue项目里，用amap-jsapi-loader这个官方推荐的加载器，把高德地图的JS API给“请”进来，然后重点玩转AMapUI组件库里的两个宝贝：PathSimplifier（轨迹展示与简化）和SimpleMarker（自定义标记）。最终目标是做出一个能展示多条动态轨迹、车辆图标能自定义、还能控制轨迹巡航播放的酷炫地图应用。整个过程我会掰开揉碎了讲，保证你跟着做就能复现出来。

首先，咱们得把舞台搭好。我假设你已经有一个现成的Vue 2或Vue 3项目了（我用的是Vue 3 + Composition API，但原理通用）。如果没有，用Vue CLI或者Vite快速创建一个就行。接下来，就是安装我们今天的主角依赖包。

打开你的终端，在项目根目录下执行：

npm install @amap/amap-jsapi-loader --save

这个@amap/amap-jsapi-loader包是高德官方出的，专门用来异步加载JS API。为什么要用加载器，而不是直接在index.html里写<script>标签引入呢？原因有几个：一是可以更好地管理依赖和版本；二是能配合现代前端工程的模块化；三是可以实现按需加载，比如等用户真的需要用到地图时再加载，提升首屏速度。

光有加载器还不够，我们还需要AMapUI组件库。但是注意了，AMapUI不需要通过npm安装。它是高德地图JS API的一部分，我们只需要在加载JS API的时候，通过配置项声明需要它，并且指定我们要用到的具体UI组件模块就行了。这个我们后面配置加载器的时候会详细说。

环境准备好之后，我建议在项目的src目录下，新建一个utils或libs文件夹，里面创建一个amap.js文件。这样做的好处是把地图初始化的逻辑集中管理，以后哪个页面或组件要用地图，直接引入这个初始化方法就行，代码干净又复用性强。当然，你也可以把初始化逻辑直接写在需要地图的Vue组件里，但对于稍复杂的项目，独立出来会更清晰。

2. 核心：异步加载高德地图JS API与AMapUI

舞台搭好，演员该上场了。这一步是整个应用的地基，如果加载出了问题，后面所有酷炫的功能都无从谈起。我刚开始用的时候，也在这里踩过坑，比如版本不匹配、插件没声明等等。咱们一步步来，把这些坑都绕过去。

首先，打开刚才创建的amap.js文件（或者你的Vue组件）。我们先来写一个初始化地图的函数。这里的关键是使用AMapLoader.load()方法。

// utils/amap.js
import AMapLoader from '@amap/amap-jsapi-loader';

// 出于安全考虑，建议将Key存储在环境变量中，这里仅为示例
const AMAP_KEY = '你申请的高德地图Web端开发者Key';

export function initAMap(containerId) {
  return AMapLoader.load({
    key: AMAP_KEY, // 必填，你的高德地图应用Key
    version: '2.0', // 指定JS API版本，推荐用最新的2.0，功能更全
    plugins: [
      'AMap.Scale', // 比例尺控件
      'AMap.ToolBar', // 缩放平移工具栏
      'AMap.Geocoder', // 地理编码与逆地理编码服务（地址解析）
      'AMap.PlaceSearch', // 地点搜索服务
      'AMap.Driving' // 驾车路线规划服务（如果你需要算路的话）
    ],
    Loca: { // 如果需要使用Loca数据可视化库（比如热力图、飞线），可以在这里声明
      version: '2.0.0'
    },
    AMapUI: { // 核心！声明我们要使用AMapUI组件库
      version: '1.1', // 使用1.1版本，更稳定
      plugins: ['misc/PathSimplifier', 'overlay/SimpleMarker'] // 按需加载我们需要的UI组件
    }
  }).then((AMap) => {
    // 加载成功，AMap是全局的AMap对象
    // 创建地图实例
    const map = new AMap.Map(containerId, {
      zoom: 11, // 初始缩放级别
      center: [116.397428, 39.90923], // 初始中心点坐标（北京天安门）
      mapStyle: 'amap://styles/light', // 地图样式，可选‘normal’，‘dark’，‘light’等
      viewMode: '2D' // 注意：AMapUI的PathSimplifier目前只支持2D模式
    });

    // 把加载好的AMap对象和创建好的地图实例返回出去，方便后续使用
    return { AMap, map };
  }).catch((e) => {
    console.error('高德地图加载失败:', e);
    throw e; // 将错误向上抛出，方便组件层处理
  });
}

我来解释一下几个容易出错的点。首先是key，你得去高德开放平台注册账号，创建一个Web端的应用，才能拿到这个Key。没有它，地图是加载不出来的。其次是version，我强烈建议使用2.0，因为1.x的版本有些新功能不支持。然后是AMapUI的配置，plugins数组里写的'misc/PathSimplifier'和'overlay/SimpleMarker'，就是告诉加载器：“嘿，请把轨迹组件和标记组件也一起给我下载下来。”这种按需加载的方式非常高效。

这里有个大坑要特别注意：AMapUI的PathSimplifier组件不支持3D地图模式（即viewMode: '3D'）。如果你设置了3D，轨迹线可能会显示异常或者根本出不来。所以创建Map实例时，viewMode要么不写（默认是2D），要么显式地写成'2D'。

在Vue组件中，我们通常会在mounted生命周期钩子（Vue 2）或onMounted（Vue 3 + Composition API）里调用这个初始化函数，并传入一个DOM元素的ID（比如container）。

<template>
  <div id="map-container" style="width: 100%; height: 600px;"></div>
</template>

<script setup>
import { onMounted } from 'vue';
import { initAMap } from '@/utils/amap';

onMounted(async () => {
  try {
    const { AMap, map } = await

标签