{"id":12403,"library":"vue-baidu-map","title":"Vue Baidu Map Components","description":"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.","status":"maintenance","version":"0.21.22","language":"javascript","source_language":"en","source_url":"https://github.com/Dafrok/vue-baidu-map","tags":["javascript","vue","baidu-map","bmap","vue-baidu-map","baidu","map"],"install":[{"cmd":"npm install vue-baidu-map","lang":"bash","label":"npm"},{"cmd":"yarn add vue-baidu-map","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-baidu-map","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for Vue 2.x application integration.","package":"vue","optional":false}],"imports":[{"note":"This is the main plugin object used with Vue.use(). Individual map components (e.g., , ) are registered globally via this plugin.","wrong":"const BaiduMap = require('vue-baidu-map')","symbol":"BaiduMap","correct":"import BaiduMap from 'vue-baidu-map'"},{"note":"The Baidu Map API Key (ak) is mandatory for initialization and typically passed during plugin registration. Omitting it will prevent maps from loading correctly.","wrong":"Vue.use(BaiduMap); // Missing AK","symbol":"Vue.use","correct":"import Vue from 'vue'; Vue.use(BaiduMap, { ak: 'YOUR_APP_KEY' })"},{"note":"After successful `Vue.use(BaiduMap, { ak: '...' })`, components like ``, ``, `` are globally available in Vue 2.x templates. No direct import is needed for individual components.","symbol":"Baidu Map Components (e.g., )","correct":""}],"quickstart":{"code":"import Vue from 'vue';\nimport BaiduMap from 'vue-baidu-map';\n\nVue.use(BaiduMap, {\n // Obtain your Baidu Map API Key from http://lbsyun.baidu.com/apiconsole/key\n ak: process.env.VUE_APP_BAIDUMAP_AK ?? 'YOUR_APP_KEY' // Replace with your actual key\n});\n\nnew Vue({\n el: '#app',\n template: `\n
\n

My Baidu Map

\n \n \n \n \n \n \n \n
\n `,\n methods: {\n zoom(levelChange) {\n // This method would typically interact with the map instance\n // For a full example, you'd need a ref to the bm-map component\n console.log('Zoom changed by', levelChange);\n }\n },\n components: { BaiduMap } // Not strictly needed for global plugin but good practice for clarity\n});\n\n// Basic CSS for the map container\nconst style = document.createElement('style');\nstyle.innerHTML = `\n .map-container {\n width: 100%;\n height: 400px;\n border: 1px solid #ccc;\n }\n`;\ndocument.head.appendChild(style);","lang":"javascript","description":"This quickstart demonstrates the installation, initialization with an API key, and basic usage of the `` component with a marker and zoom controls in a Vue 2 application. It highlights the essential setup and provides styling."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"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' })`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Add CSS rules for the map container class or ID, specifying `width` and `height` (e.g., `.map { width: 100%; height: 300px; }`).","message":"The map container element (e.g., ``) 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `ak` (API Key) parameter was not provided during the `Vue.use(BaiduMap, { ak: '...' })` initialization, or it was an empty string.","error":"BaiduMap: The Baidu Map API Key is required."},{"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.","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.","error":"ReferenceError: Vue is not defined"},{"fix":"Apply explicit `width` and `height` styles to the map container element, for example: ``.","cause":"The container element for the Baidu Map component (``) lacks defined CSS `width` and `height` properties, or its parent elements restrict its size.","error":"The map is not displayed, or it appears as a small grey box."},{"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`.","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.","error":"Uncaught TypeError: Cannot read properties of undefined (reading 'Map') (or similar errors related to BaiduMap JS API loading)"}],"ecosystem":"npm"}