---
title: "MaplibreBasemapControl"
description: "底图切换控件，与地图的 options.style 绑定同一个值，天地图与矢量样式统一切换。"
canonical_url: "https://maplibre.mhaibaraai.cn/docs/controls/basemap-control"
---
# MaplibreBasemapControl

> 底图切换控件，与地图的 options.style 绑定同一个值，天地图与矢量样式统一切换。

## 简介

`MaplibreBasemapControl` 是受控组件：它只负责选择，通过 `v-model` 发出选中项的 `style`，不直接调用 `setStyle`。把同一个值绑定到 `MaplibreMap` 的 `options.style`，由地图完成切换，并自动重建叠加的业务图层。样式只存在一处，不会出现控件与地图状态不一致。

天地图底图用 [`tiandituStyle()`](https://maplibre.mhaibaraai.cn/docs/extensions/tianditu) 生成完整样式，与 OpenFreeMap 等矢量样式放在同一个 `items` 列表里切换。

> [!TIP]
> 
> 切换底图后，
> 
> MaplibreLayerGroup
> 
>  的显隐与透明度（包括通过 
> 
> styleLayers
> 
>  认领的底图图层）会自动在新样式上恢复。

## 用法

```vue [BasemapControlExample.vue]
<script setup lang="ts">
import type { BasemapItem } from '#maplibre/types'
import { tiandituStyle } from '@movk/maplibre/utils/tianditu'

const items: BasemapItem[] = [
  { label: 'OpenFreeMap Liberty', style: 'https://tiles.openfreemap.org/styles/liberty' },
  { label: 'OpenFreeMap Dark', style: 'https://tiles.openfreemap.org/styles/dark' },
  { label: '天地图 影像', style: tiandituStyle('img', { annotation: true }) },
  { label: '天地图 矢量', style: tiandituStyle('vec', { annotation: true }) }
]

// 同一个值同时绑定底图控件与地图样式：控件只负责选择，地图负责切换
const style = shallowRef(items[0]!.style)
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :options="{ style, center: [116.397, 39.908], zoom: 11 }">
      <MaplibreBasemapControl v-model="style" :items="items" position="top-right" />
    </MaplibreMap>
  </div>
</template>
```

## API

### Props

```ts
/**
 * Props for the MaplibreBasemapControl component
 */
interface MaplibreBasemapControlProps {
  /**
   * 候选底图
   */
  items: BasemapItem[];
  /**
   * 控件停靠位置；省略用地图默认位置
   */
  position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | undefined;
  /**
   * 折叠按钮与选项组的无障碍标签
   * @default 'Basemap'
   */
  label?: string | undefined;
  /**
   * 当前底图样式，与 MaplibreMap 的 options.style 绑定同一个值；按引用或字符串相等判断选中项
   */
  modelValue?: string | StyleSpecification | undefined;
  /**
   * 面板是否展开
   * @default false
   */
  open?: boolean | undefined;
}
```

### Emits

```ts
/**
 * Emitted events for the MaplibreBasemapControl component
 */
interface MaplibreBasemapControlEmits {
  update:modelValue: (payload: [value: string | StyleSpecification | undefined]) => void;
  update:open: (payload: [value: boolean]) => void;
}
```

## Changelog

See commit history for [src/runtime/components/controls/BasemapControl.vue](https://github.com/mhaibaraai/movk-maplibre/commits/main/src/runtime/components/controls/BasemapControl.vue).


## Sitemap

See the full [sitemap](https://maplibre.mhaibaraai.cn/sitemap.md) for all pages.