vue3-baidu-map-gl

The BMap component manages the lifecycle of the Baidu Map GL SDK.

Important for WebGL users: When using WebGL rendering, it is critical to destroy the map instance to prevent 'too many WebGL context' warnings in the browser. The component automatically calls map.destroy() when the component is unmounted (onUnmounted).

Initialization Flow:

1. The component checks if it's running in a client environment (isClient).
2. It asynchronously loads the Baidu Map GL script via getScriptAsync using the provided ak or apiUrl.
3. Once the script is loaded, it initializes the BMapGL.Map instance.
4. It applies initial props (center, zoom, etc.) and binds events.
5. If plugins are provided, it initializes them and emits pluginReady.
6. Finally, it emits initd to signal the map is ready for use.

The library provides several utility types to handle Vue's reactivity system seamlessly in configuration objects:

• MaybeRef<T>: Accepts either a raw value T or a Vue Ref<T>.
• MaybeRefOrGetter<T>: Accepts a raw value, a Ref<T>, or a getter function () => T.
• DeepMaybeRef<T>: Recursively makes all nested properties of an object or array compatible with MaybeRef<T>. This is useful for passing complex configuration objects that might contain reactive properties.

type MaybeRef<T> = T | Ref<T>

type MaybeRefOrGetter<T> = MaybeRef<T> | (() => T)

type DeepMaybeRef<T> = T extends Ref<infer V>
  ? MaybeRef<V>
  : T extends Array<any> | object
  ? { [K in keyof T]: DeepMaybeRef<T[K]> }
  : MaybeRef<T>

The InfoWindow component (exported as BInfoWindow) is used to display information overlays on a Baidu Map GL instance. It allows you to pass custom HTML content via a default slot.

Note: The modelValue prop is deprecated. Use v-model:show for controlling visibility.

<template>
  <BMapGLMap>
    <BMapGLInfoWindow 
      v-model:show="isInfoWindowVisible"
      :position="{ lng: 116.404, lat: 39.915 }"
      title="Location Info"
    >
      <div>
        <h3>Custom Content</h3>
        <p>This is inside the info window.</p>
      </div>
    </BMapGLInfoWindow>
  </BMapGLMap>
</template>

<script setup>
import { ref } from 'vue'
const isInfoWindowVisible = ref(true)
</script>

To use vue3-baidu-map-gl in your Vue 3 project, use the install method (or the default export) to register all components and global properties. You can pass an optional configuration object to set the Baidu Map Access Key (ak), API URL, and custom plugins.

import { createApp } from 'vue'
import Vue3BaiduMapGl from 'vue3-baidu-map-gl'

const app = createApp(App)

app.use(Vue3BaiduMapGl, {
  ak: 'YOUR_BAIDU_MAP_AK',
  apiUrl: 'YOUR_API_URL',
  // plugins and pluginsSourceLink can also be configured here
})

app.mount('#app')

When installing the plugin, you can provide a Vue3BaiduMapGlOptions object to configure global settings. These options are attached to the Vue application's globalProperties.

export interface Vue3BaiduMapGlOptions {
  ak?: string           // Baidu Map Access Key
  apiUrl?: string       // Baidu Map API URL
  plugins?: UserPlugins // Custom user plugins
  pluginsSourceLink?: PluginsSourceLink // Link for plugin sources
}

When calling useViewAnimation, you can pass a UseViewAnimationOptions object to customize the animation behavior:

If you need to load a plugin from a specific URL instead of the default CDN, you can provide a customPluginSourceLink object to initPlugins. This object should be a partial mapping of plugin names to their source URLs.

import { initPlugins, PluginsSourceLink } from 'vue3-baidu-map-gl';

const customLinks: Partial<PluginsSourceLink> = {
  Mapvgl: 'https://my-private-cdn.com/mapvgl.min.js'
};

const plugins = await initPlugins(['Mapvgl'], customLinks);

When calling useTrackAnimation, you can provide a UseTrackAnimationOptions object to customize the animation behavior.

The BContextMenu component accepts the following props:

When calling useBrowserLocation, you can pass an options object to fine-tune the geolocation request behavior.

const options: UseBrowserLocationOptions = {
  enableSDKLocation: true,
  enableHighAccuracy: true,
  timeout: 10000,
  maximumAge: 60000,
};

The displayOptions prop (of type MapDisplayOptions) allows you to fine-tune which visual elements are rendered on the map.

Available options:

• poi: Show/hide POI markers.
• indoor: Show/hide indoor maps.
• poiText: Show/hide POI text labels.
• poiIcon: Show/hide POI icons.
• overlay: Show/hide overlays.
• layer: Show/hide overlay layers (not supported in Globe mode).
• building: Show/hide 3D buildings (WebGL only).
• street: Show/hide street networks (effective for Satellite and Globe modes).
• skyColors: An array of two strings [string, string] to set sky colors.

export interface MapDisplayOptions {
    poi?: boolean
    indoor?: boolean
    poiText?: boolean
    poiIcon?: boolean
    overlay?: boolean
    layer?: boolean
    building?: boolean
    street?: boolean
    skyColors?: [string, string]
}