Vue AMap Component Library

Common errors

• ReferenceError: Vue is not defined

  cause `Vue` object is not globally available or imported when `Vue.use(VueAMap)` is called.
  fix Ensure `import Vue from 'vue';` is present at the top of your script if you're using a module bundler, or that Vue is loaded via a script tag before your application code in a global context.

• ReferenceError: AMap is not defined

  cause The Gaode Map JavaScript API has not been loaded successfully, often because `VueAMap.initAMapApiLoader` was not called, called with an invalid key, or failed to load the external script.
  fix Verify that `VueAMap.initAMapApiLoader` is called exactly once before any map components are rendered, that `YOUR_GAODE_KEY_HERE` is a valid key, and check network requests for failures to load `https://webapi.amap.com/maps?v=...`.

• [Vue warn]: Unknown custom element: <el-amap> - did you register the component correctly?

  cause The `vue-amap` plugin was not registered with Vue, meaning `Vue.use(VueAMap)` was skipped or executed after the component was attempted to be used.
  fix Ensure `Vue.use(VueAMap);` is called at the very beginning of your application setup, before any Vue instances or components that use `vue-amap` components are created.

• TypeError: Cannot read properties of undefined (reading 'map')

  cause This often occurs when map data (e.g., `center`, `markers`, `paths`) is `undefined` or not in the expected format when a `vue-amap` component tries to render it.
  fix Double-check that all data bound to `vue-amap` components (e.g., `:center`, `:position`, `:path`) is correctly initialized with arrays or objects as expected by the component, and that it's reactive data.

Warnings

• breaking This package is abandoned. The last commit was in August 2021, and it specifically targets Vue 2, which reached End-of-Life (EOL) in December 2023. It is not compatible with Vue 3 or newer versions.
  Fix: For new projects or migrations, consider alternative map libraries that support Vue 3 (e.g., vue-google-maps, vue-leaflet) or directly integrate the Gaode Map JavaScript API without a specific Vue 2 wrapper if Gaode Maps is a hard requirement. If using Vue 2, proceed with caution and be prepared for potential unaddressed bugs or security issues.
• gotcha Requires a Gaode Map API key (`key` parameter in `initAMapApiLoader`). This key is essential for the map to load and function correctly. Gaode Maps (Amap) is primarily focused on the Chinese market, and keys might have geographical restrictions.
  Fix: Obtain a valid Gaode Map API key from the official Gaode developer platform. Ensure the key is correctly passed to `VueAMap.initAMapApiLoader`.
• gotcha The default Gaode SDK version specified is `1.4.4`. This version might be outdated, potentially lacking new features, performance improvements, or crucial security updates available in later SDK versions. It's unclear if the library is fully compatible with newer Gaode SDK versions.
  Fix: While `v: '1.4.4'` is the default, you can try specifying a newer version in `initAMapApiLoader` (e.g., `v: '2.0'` or `v: 'latest'`) but be aware of potential compatibility issues with the `vue-amap` wrapper itself.
• gotcha The library registers all its components globally when `Vue.use(VueAMap)` is called. This can lead to naming conflicts if other libraries use similar component names (e.g., `<el-amap>` and `<el-button>` from Element UI, though the prefix 'el-' here is for 'Element' and not 'Element UI').
  Fix: Ensure that your project's component naming conventions do not clash with `vue-amap`'s 'el-amap-' prefixed components. There's no built-in way to scope or selectively register components from this plugin.

Install

• npm install vue-amap npm
• yarn add vue-amap yarn
• pnpm add vue-amap pnpm

Imports

• VueAMap
  wrong:

  const VueAMap = require('vue-amap');

  correct:

  import VueAMap from 'vue-amap';

  While CommonJS `require` might work in some older Node environments, the library primarily encourages ES module `import` syntax for Vue CLI/Webpack setups. The library is abandoned and targets Vue 2, so CJS usage is less common in modern (even Vue 2) frontend builds.
• Vue.use(VueAMap)
  wrong:

  import { Amap } from 'vue-amap';

  correct:

  import VueAMap from 'vue-amap';
  import Vue from 'vue';
  Vue.use(VueAMap);

  Vue AMap is a Vue plugin and registers all its components globally. Individual components like `el-amap` are not directly imported as named exports; they become available after `Vue.use()`.
• VueAMap.initAMapApiLoader
  wrong:

  Vue.initAMapApiLoader({});

  correct:

  VueAMap.initAMapApiLoader({
    key: 'YOUR_GAODE_KEY',
    plugin: ['AMap.Autocomplete'],
    v: '1.4.4'
  });

  The `initAMapApiLoader` function is a static method of the `VueAMap` object, responsible for loading the Gaode Map JavaScript API and its specified plugins. It must be called before map components are rendered.

Quickstart

This quickstart demonstrates how to install, initialize, and integrate vue-amap into a Vue 2 application. It shows global registration, loading the AMap API with a key and plugins, and rendering a basic map with a marker.

import Vue from 'vue';
import VueAMap from 'vue-amap';

Vue.use(VueAMap);

// Initialize vue-amap, load the Gaode Map SDK
VueAMap.initAMapApiLoader({
  key: 'YOUR_GAODE_KEY_HERE', // Replace with your actual Gaode Map key
  plugin: ['AMap.Autocomplete', 'AMap.PlaceSearch', 'AMap.Scale', 'AMap.ToolBar'],
  v: '1.4.4' // Specify Gaode SDK version
});

new Vue({
  el: '#app',
  data() {
    return {
      zoom: 12,
      center: [116.397428, 39.90923],
      markers: [{ position: [116.397428, 39.90923] }]
    };
  },
  template: `
    <div style="width: 800px; height: 600px;">
      <el-amap :zoom="zoom" :center="center">
        <el-amap-marker v-for="(marker, index) in markers" :key="index" :position="marker.position"></el-amap-marker>
      </el-amap>
    </div>
  `
});