---
title: "<ScriptMapLibreMap>"
description: "地图外观组件在 SSR 期间预留布局空间，在触发时加载 MapLibre，创建 Map，并将其提供给子组件。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/scripts/maplibre/api/script-maplibre-map"
last_updated: "2026-09-23T10:33:13.578Z"
---

地图外观组件在 SSR 期间预留布局空间，在触发时加载 MapLibre，创建 `Map`，并将其提供给子组件。

::script-types{script-key="maplibre" filter="ScriptMapLibreMap"}
::

`mapStyle`、`center`、`zoom`、`bearing` 和 `pitch` 是响应式的。

`center`、`zoom`、`bearing` 和 `pitch` 也支持 `v-model` 绑定。如果你还希望接收用户进行的相机更改，请使用它。

`bounds` 是单向响应式的。地图会适应新的区域，但不会将用户的平移或缩放操作反馈给你。

```vue
<ScriptMapLibreMap
  v-model:center="center"
  v-model:zoom="zoom"
  v-model:bearing="bearing"
  map-style="https://demotiles.maplibre.org/style.json"
  width="100%"
  height="28rem"
  @ready="({ map }) => console.log(map.value)"
>
  <template #description>
    一张街道地图，其中在选定的办公室处有一个标记。
  </template>
</ScriptMapLibreMap>
```

## 调整数据视图

设置 `bounds`，让初始相机适应某个区域。`bounds` 接受 `[[west, south], [east, north]]` 或 `[west, south, east, north]`。如果设置了 `bounds`，`center` 就是可选的。地图类型不允许地图既没有 `center`，也没有 `bounds`。

```vue
<ScriptMapLibreMap
  map-style="https://tiles.openfreemap.org/styles/liberty"
  :bounds="[[144.94, -37.83], [144.97, -37.81]]"
  :fit-bounds-options="{ padding: 48, maxZoom: 15 }"
  width="100%"
  :height="480"
/>
```

`fitBoundsOptions` 接受 MapLibre 的 [`FitBoundsOptions`](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/FitBoundsOptions/)。使用 `padding` 让要素远离边缘。使用 `maxZoom`，防止地图因单个点而放大过多。

### 优先级

- 如果同时设置了 `center` 和 `bounds`，`bounds` 会设置初始中心点和缩放级别。`center` 和 `zoom` 仅在之后发生变化时才会生效。
- 调整视图时会保留 `bearing` 属性。MapLibre 自带的适应功能会将方位角重置为 0。若要在调整视图时更改方位角，请在 `fitBoundsOptions` 中设置 `bearing`。
- `pitch` 按照常规方式生效。

### 后续更改

- 如果 `bounds` 坐标发生变化，地图会适应新的区域。视图会直接跳转，不带动画，与其他相机属性的行为相同。
- 如果 `bounds` 更新为坐标相同的新数组，相机会保持原位。父组件重新渲染不会撤销用户的平移或缩放操作。
- 仅更改 `fitBoundsOptions` 不会再次调整视图。下一次 `bounds` 发生变化时才会使用新的选项。
- 如果移除 `bounds`，相机会保持原位。如果之后再次设置相同的坐标，地图会再次适应这些坐标。

若要进行带动画的视图调整，请从 `ready` 载荷或模板引用中调用 `fitBounds`。

`placeholder`、`awaitingLoad`、`loading` 和 `error` 插槽可自定义各个加载状态。默认错误状态会显示出来，并通过 `role="alert"` 播报。

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.