Vue Baidu Map Components

0.21.22 · maintenance · verified Sun Apr 19

Vue Baidu Map is a component library providing Baidu Map integration for Vue.js 2.x applications. It allows developers to easily embed interactive Baidu Maps and leverage various features like markers, overlays, and controls within their Vue projects. The current stable version is 0.21.22. While it has seen recent updates (as of September 2023), its explicit focus on Vue 2.x places it in a maintenance state, especially given Vue 2's End of Life in December 2023. Key differentiators include its tight integration with Baidu's localized mapping services, which are critical for applications targeting users in mainland China, where other global map providers may have limited or no service.

Common errors

```
BaiduMap: The Baidu Map API Key is required.
```
cause The `ak` (API Key) parameter was not provided during the `Vue.use(BaiduMap, { ak: '...' })` initialization, or it was an empty string.

fix Obtain a valid Baidu Map API Key from the Baidu LBS Cloud platform (http://lbsyun.baidu.com/apiconsole/key) and pass it as the `ak` option during plugin registration.
```
ReferenceError: Vue is not defined
```
cause Vue is not globally available or not imported when attempting to `import BaiduMap from 'vue-baidu-map'` and `Vue.use()`, or when using Vue components without a build step.

fix Ensure `Vue` is imported (`import Vue from 'vue'`) and available in the scope where `BaiduMap` is initialized, especially in non-SFC setups. For CDN usage, ensure Vue's script tag is loaded before this library's script.
```
The map is not displayed, or it appears as a small grey box.
```
cause The container element for the Baidu Map component (`<baidu-map>`) lacks defined CSS `width` and `height` properties, or its parent elements restrict its size.

fix Apply explicit `width` and `height` styles to the map container element, for example: `<style>.map { width: 100%; height: 400px; }</style>`.
```
Uncaught TypeError: Cannot read properties of undefined (reading 'Map') (or similar errors related to BaiduMap JS API loading)
```
cause The Baidu Map JavaScript API script failed to load, potentially due to network issues, incorrect API key, or blocking by content security policies. This library internally loads the script.

fix Check your network connection, verify the `ak` provided is correct and valid, and ensure no Content Security Policy (CSP) rules are blocking `http://api.map.baidu.com/api` or `https://api.map.baidu.com/api`.

Warnings

breaking This package is explicitly designed for Vue 2.x. Vue 2 reached End of Life (EOL) on December 31, 2023. Using this library in new projects or projects migrating to Vue 3.x is not recommended and will likely lead to compatibility issues or require significant re-architecture. Consider `vue-baidu-map-3x` or `vue3-baidu-map-gl` for Vue 3.x support.
Fix: For Vue 3 projects, migrate to an actively maintained Vue 3 compatible Baidu Map library like `vue-baidu-map-3x` or `vue3-baidu-map-gl`.
gotcha The Baidu Map API Key (ak) is mandatory and must be correctly configured during plugin initialization. An invalid or missing `ak` will prevent the map from loading and displaying, often with errors appearing in the browser console.
Fix: Ensure you have obtained a valid 'Browser' API Key from the Baidu LBS Cloud platform (http://lbsyun.baidu.com/apiconsole/key) and provide it to the `ak` option during `Vue.use(BaiduMap, { ak: 'YOUR_KEY' })`.
gotcha The map container element (e.g., `<baidu-map>`) requires explicit CSS `width` and `height` properties to render correctly. If these are not set, the map may not appear, or it may collapse to zero dimensions.
Fix: Add CSS rules for the map container class or ID, specifying `width` and `height` (e.g., `.map { width: 100%; height: 300px; }`).
gotcha Baidu Maps' API and services are primarily optimized and targeted for usage within mainland China. Developers targeting international audiences might find other map providers more suitable due to feature availability, data accuracy outside China, and API documentation language support.
Fix: Evaluate your target audience. If international reach is critical and Baidu-specific features are not required, consider alternatives like Google Maps or OpenStreetMap-based solutions. If targeting China, ensure adherence to Baidu's specific development guidelines and local regulations.
gotcha Baidu Map API keys can have specific restrictions (e.g., IP address, domain name, type of application like browser/server/mobile). If the key's restrictions do not match your deployment environment, the map will fail to load, often with an 'ak error' message.
Fix: Verify that your Baidu Map API key's settings on the Baidu LBS Cloud console match the environment where your application is running (e.g., ensure your domain is whitelisted for browser applications). Different key types might be needed for different use cases.

Install

npm install vue-baidu-map npm
yarn add vue-baidu-map yarn
pnpm add vue-baidu-map pnpm

Imports

BaiduMap
wrong:
```
const BaiduMap = require('vue-baidu-map')
```
correct:
```
import BaiduMap from 'vue-baidu-map'
```
This is the main plugin object used with Vue.use(). Individual map components (e.g., <baidu-map>, <bm-marker>) are registered globally via this plugin.
Vue.use
wrong:
```
Vue.use(BaiduMap); // Missing AK
```
correct:
```
import Vue from 'vue'; Vue.use(BaiduMap, { ak: 'YOUR_APP_KEY' })
```
The Baidu Map API Key (ak) is mandatory for initialization and typically passed during plugin registration. Omitting it will prevent maps from loading correctly.
Baidu Map Components (e.g., <baidu-map>)
```
<template><baidu-map class="map"></baidu-map></template>
```
After successful `Vue.use(BaiduMap, { ak: '...' })`, components like `<baidu-map>`, `<bm-view>`, `<bm-marker>` are globally available in Vue 2.x templates. No direct import is needed for individual components.

Quickstart

This quickstart demonstrates the installation, initialization with an API key, and basic usage of the `<baidu-map>` component with a marker and zoom controls in a Vue 2 application. It highlights the essential setup and provides styling.

import Vue from 'vue';
import BaiduMap from 'vue-baidu-map';

Vue.use(BaiduMap, {
  // Obtain your Baidu Map API Key from http://lbsyun.baidu.com/apiconsole/key
  ak: process.env.VUE_APP_BAIDUMAP_AK ?? 'YOUR_APP_KEY' // Replace with your actual key
});

new Vue({
  el: '#app',
  template: `
    <div id="app">
      <h1>My Baidu Map</h1>
      <baidu-map class="map-container" :center="{lng: 116.404, lat: 39.915}" :zoom="15">
        <bm-marker :position="{lng: 116.404, lat: 39.915}" :dragging="true" animation="BMAP_ANIMATION_BOUNCE"></bm-marker>
        <bm-control anchor="BMAP_ANCHOR_TOP_LEFT">
          <button @click="zoom(3)">Increase Zoom</button>
          <button @click="zoom(-3)">Decrease Zoom</button>
        </bm-control>
      </baidu-map>
    </div>
  `,
  methods: {
    zoom(levelChange) {
      // This method would typically interact with the map instance
      // For a full example, you'd need a ref to the bm-map component
      console.log('Zoom changed by', levelChange);
    }
  },
  components: { BaiduMap } // Not strictly needed for global plugin but good practice for clarity
});

// Basic CSS for the map container
const style = document.createElement('style');
style.innerHTML = `
  .map-container {
    width: 100%;
    height: 400px;
    border: 1px solid #ccc;
  }
`;
document.head.appendChild(style);

view raw JSON →