---
title: "<ScriptGoogleMaps>"
description: "延迟加载交互式 Google 地图，并通过声明式子组件组合地图。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/scripts/google-maps/api/script-google-maps"
last_updated: "2026-08-11T09:33:14.531Z"
---

[`<ScriptGoogleMaps>`](/scripts/google-maps) 通过延迟加载和声明式组件 API 封装了 [`useScriptGoogleMaps()`](/scripts/google-maps/api/use-script-google-maps)。

<script-types filter="ScriptGoogleMaps" script-key="google-maps">



</script-types>

[元素事件触发器](/docs/guides/script-triggers#element-event-triggers)会在组件上配置的事件发生之前延迟加载 Google 地图。

`#placeholder` 插槽默认是空的。在其中使用 [`<ScriptGoogleMapsStaticMap>`](/scripts/google-maps/api/static-map) 可以在交互式地图加载时显示静态地图图像。

默认事件为 `mouseenter`、`mouseover` 和 `mousedown`。

查看 [Facade 组件 API](/docs/guides/facade-components#facade-components-api) 了解所有属性、事件和插槽。

## 模板引用 API

通过模板引用访问基础的 Google 地图实例。暴露的对象包含：

<table>
<thead>
  <tr>
    <th>
      属性
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        mapsApi
      </code>
    </td>
    
    <td>
      <code className="language-html shiki shiki-themes github-light github-light material-theme-palenight" language="html" style="">
        <span class="sqjlB">
          typeof google.maps | undefined
        </span>
      </code>
    </td>
    
    <td>
      核心地图 API 命名空间（<code>
        google.maps
      </code>
      
      ）。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        map
      </code>
    </td>
    
    <td>
      <code className="language-html shiki shiki-themes github-light github-light material-theme-palenight" language="html" style="">
        <span class="sqjlB">
          google.maps.Map | undefined
        </span>
      </code>
    </td>
    
    <td>
      地图实例。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        resolveQueryToLatLng
      </code>
    </td>
    
    <td>
      <code className="language-html shiki shiki-themes github-light github-light material-theme-palenight" language="html" style="">
        <span class="sqjlB">
          (query) => Promise
        </span>
        
        <span class="sx-uw">
          <
        </span>
        
        <span class="sFfpx">
          google.maps.LatLng
        </span>
        
        <span class="sg-iE">
          |
        </span>
        
        <span class="sg-iE">
          google.maps.LatLngLiteral
        </span>
        
        <span class="sg-iE">
          |
        </span>
        
        <span class="sg-iE">
          undefined
        </span>
        
        <span class="sx-uw">
          >
        </span>
      </code>
    </td>
    
    <td>
      将地址进行地理编码以获取坐标。当 Google 未返回位置或请求失败时，Promise 将被拒绝。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        importLibrary
      </code>
    </td>
    
    <td>
      <code className="language-html shiki shiki-themes github-light github-light material-theme-palenight" language="html" style="">
        <span class="sqjlB">
          (name) => Promise
        </span>
        
        <span class="sx-uw">
          <
        </span>
        
        <span class="sFfpx">
          Library
        </span>
        
        <span class="sx-uw">
          >
        </span>
      </code>
    </td>
    
    <td>
      在运行时加载其他 Google 地图库。
    </td>
  </tr>
</tbody>
</table>

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

async function flyToSydney() {
  const coords = await mapRef.value?.resolveQueryToLatLng('Sydney, Australia')
  if (coords)
    mapRef.value?.map?.panTo(coords)
}
</script>

<template>
  <ScriptGoogleMaps ref="mapRef" api-key="your-api-key" />
  <button @click="flyToSydney">
    前往悉尼
  </button>
</template>
```

如上例所示，当你通过组件模板引用访问暴露的引用时，Vue 会自动解包这些引用。`@ready` 事件的负载使用原始的暴露对象，因此其 `mapsApi` 和 `map` 属性是 `ShallowRef`。

## 地图事件

使用组件的 `@ready` 事件在初始化后附加 Google 地图监听器。回调接收原始暴露对象。

```vue
<script setup lang="ts">
function handleReady({ map }: { map: ShallowRef<google.maps.Map | undefined> }) {
  watch(map, (m) => {
    if (!m)
      return
    m.addListener('center_changed', () => {
      console.log('Center changed', m.getCenter())
    })
  }, { immediate: true })
}
</script>

<template>
  <ScriptGoogleMaps @ready="handleReady" />
</template>
```

## 插槽

使用插槽在地图加载之前、加载期间和加载之后添加内容。

**default**

默认插槽会在地图根元素内部渲染。更改地图 ID 或配色方案会导致该插槽与地图的其他声明式子元素一起短暂卸载并重新挂载。

```vue
<template>
  <ScriptGoogleMaps>
    <div class="absolute top-0 left-0 right-0 p-5 bg-white text-black">
      <h1 class="text-xl font-bold">
        我的自定义地图
      </h1>
    </div>
  </ScriptGoogleMaps>
</template>
```

**awaitingLoad**

在用户触发地图加载之前显示（例如，在悬停/点击之前）。使用此插槽在静态占位图上显示行动号召覆盖层。

```vue
<template>
  <ScriptGoogleMaps>
    <template #awaitingLoad>
      <div class="bg-blue-500 text-white p-5">
        点击加载地图！
      </div>
    </template>
  </ScriptGoogleMaps>
</template>
```

**loading**

在用户触发加载之后、地图可交互之前显示（正在获取/初始化脚本）。

默认情况下会显示一个无障碍加载指示器。提供此插槽会替换默认指示器，因此请在自定义内容中包含等效的加载提示。

<warning>

当前组件还会在脚本状态为 `error` 时渲染 `loading` 插槽。如果同时提供了 `loading` 和 `error`，加载失败后两者都可能显示。

</warning>

```vue
<template>
  <ScriptGoogleMaps>
    <template #loading>
      <div class="bg-blue-500 text-white p-5">
        加载中...
      </div>
    </template>
  </ScriptGoogleMaps>
</template>
```

**placeholder**

`placeholder` 插槽默认为空。使用 [`<ScriptGoogleMapsStaticMap>`](/scripts/google-maps/api/static-map) 可以在交互式地图加载时显示静态地图预览。

```vue
<template>
  <ScriptGoogleMaps
    :map-options="{
      center,
      zoom: 7,
    }"
  >
    <template #placeholder>
      <ScriptGoogleMapsStaticMap
        :center="center"
        :zoom="7"
        loading="eager"
      />
    </template>
  </ScriptGoogleMaps>
</template>
```