---
title: "useMapSync"
description: "多地图相机联动，任一地图移动时同步其余地图的中心、缩放、方位与倾角。"
canonical_url: "https://maplibre.mhaibaraai.cn/docs/composables/use-map-sync"
---
# useMapSync

> 多地图相机联动，任一地图移动时同步其余地图的中心、缩放、方位与倾角。

## 简介

`useMapSync` 让多张地图的相机保持一致：任一地图移动时，把 `center`、`zoom`、`bearing`、`pitch` 同步到其余地图。全部地图实例就绪后才生效，生效时以列表中第一张地图的相机对齐其余地图；随调用方作用域销毁自动解绑。

> [!NOTE]
> 
> 按 id 引用时需为对应 
> 
> MaplibreMap
> 
>  设置 
> 
> map-id
> 
> ；地图晚于调用挂载也能生效。两张独立地图并排对照时使用本函数；同一视野内的卷帘对比使用 
> 
> MaplibreSwipe
> 
> ，它作为主图的子组件单向跟随，无需手动联动。

## 用法

左右两张地图联动，开关可随时暂停：

```vue [UseMapSyncExample.vue]
<script setup lang="ts">
const enabled = ref(true)

useMapSync(['sync-demo-left', 'sync-demo-right'], { enabled })
</script>

<template>
  <div class="relative grid h-115 w-full grid-cols-2 gap-px overflow-hidden rounded-(--ui-radius) border border-default bg-(--ui-border)">
    <MaplibreMap map-id="sync-demo-left" :options="{ style: 'https://tiles.openfreemap.org/styles/liberty', center: [116.397, 39.908], zoom: 11 }" />
    <MaplibreMap map-id="sync-demo-right" :options="{ center: [116.397, 39.908], zoom: 11 }">
      <MaplibreTiandituLayer layer="img" annotation />
    </MaplibreMap>
    <div class="absolute left-2 top-2 z-10 rounded-md bg-default/90 px-2 py-1 ring ring-default">
      <USwitch v-model="enabled" label="联动" size="sm" />
    </div>
  </div>
</template>
```

## 示例

### 按钮开启联动

两种做法都能交给按钮控制：

- `enabled` 绑定按钮状态：地图常驻，开关只绑定或解绑相机同步。
- 第二张地图用 `v-if` 按需出现：按 `map-id` 引用，地图挂载后自动开始联动，卸载后自动解绑。

两种做法在开始联动时都以列表中**第一张地图**的相机对齐其余地图，因此把主图放在首位：

```vue
<script setup lang="ts">
const showSide = ref(false)

useMapSync(['main-map', 'side-map'])
</script>

<template>
  <UButton @click="showSide = !showSide">
    对照视图
  </UButton>
  <div class="grid h-115" :class="showSide ? 'grid-cols-2' : 'grid-cols-1'">
    <MaplibreMap map-id="main-map" :options="{ style: 'https://tiles.openfreemap.org/styles/liberty' }" />
    <MaplibreMap v-if="showSide" map-id="side-map" :options="{ style: 'https://tiles.openfreemap.org/styles/dark' }" />
  </div>
</template>
```

## API

### `useMapSync()`

**maps** (`MaybeRefOrGetter<MapSyncTarget[]>`) *required*: 参与联动的地图：map-id 字符串或地图上下文（如 useMap() 的返回值）；列表变化时重新绑定。

**options.enabled** (`MaybeRefOrGetter<boolean>`): 是否启用联动，默认 true；置 false 解绑，恢复时以首图相机重新对齐。

## Changelog

See commit history for [src/runtime/composables/useMapSync.ts](https://github.com/mhaibaraai/movk-maplibre/commits/main/src/runtime/composables/useMapSync.ts).


## Sitemap

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