---
title: "useScriptGoogleMaps()"
description: "加载 Google 地图 SDK，并直接从组合式函数访问其 API。"
canonical_url: "https://nuxt-scripts.zhcndoc.com/scripts/google-maps/api/use-script-google-maps"
last_updated: "2026-09-23T10:33:12.297Z"
---

使用 [`useScriptGoogleMaps()`{lang="ts"}](/scripts/google-maps/api/use-script-google-maps){lang="ts"} 加载 SDK，并直接使用 Maps API。

```ts
export function useScriptGoogleMaps<T extends GoogleMapsApi>(_options?: GoogleMapsInput) {}
```

有关触发器和其他脚本选项，请参阅[注册表脚本](/docs/guides/registry-scripts)。

## 选项

| 选项          | 类型         | 默认值          | 描述                                                                                |
| ----------- | ---------- | ------------ | --------------------------------------------------------------------------------- |
| `apiKey`    | `string`   | -            | 您的 Google Maps API 密钥（必填）。                                                        |
| `libraries` | `string[]` | `['places']` | 要加载的 Google Maps 库。                                                               |
| `language`  | `string`   | -            | 控件和标签的语言（例如 `'en'`、`'ja'`）。                                                       |
| `region`    | `string`   | -            | 区域偏向（例如 `'US'`、`'JP'`）。                                                           |
| `v`         | `string`   | -            | API 版本：`'weekly'`、`'quarterly'`、`'beta'` 或 `'alpha'`。默认省略（Google 默认为 `'weekly'`）。 |

## 返回值

| 属性         | 类型                                        | 描述                                                                           |
| ---------- | ----------------------------------------- | ---------------------------------------------------------------------------- |
| `onLoaded` | `(fn) => void`                            | 加载器脚本完成后的回调。接收 `{ maps: Promise<typeof google.maps> }`；等待 `maps` 以获取 API 回调。 |
| `load`     | `() => Promise<GoogleMapsApi>`{lang="ts"} | 手动触发脚本加载。                                                                    |
| `status`   | `Ref<string>`{lang="html"}                | 当前加载状态（`'awaitingLoad'`、`'loading'`、`'loaded'`、`'error'` 或 `'removed'`）。     |

## 示例

### 基础地图

加载 Google Maps SDK 并以编程方式创建地图。

```vue
<script setup lang="ts">
/// <reference types="google.maps" />
const { onLoaded } = useScriptGoogleMaps({
  apiKey: 'key',
})
const mapEl = ref()
onMounted(() => {
  onLoaded(async (instance) => {
    const maps = await instance.maps
    new maps.Map(mapEl.value, {
      center: { lat: -34.397, lng: 150.644 },
      zoom: 8,
    })
  })
})
</script>

<template>
  <div ref="mapEl" style="width: 100%; height: 400px;" />
</template>
```

### 地理编码

使用此组合式函数访问地理编码器 API。

```vue
<script setup lang="ts">
const { onLoaded } = useScriptGoogleMaps({
  apiKey: 'key',
})

async function geocodeAddress(address: string) {
  onLoaded(async (instance) => {
    const maps = await instance.maps
    const geocoder = new maps.Geocoder()
    const result = await geocoder.geocode({ address })
    console.log(result.results[0]?.geometry.location.toJSON())
  })
}
</script>
```

### 导入其他库

在运行时加载其他库。注册表默认已请求 `places`，因此本示例导入 `geometry`：

```vue
<script setup lang="ts">
const { onLoaded } = useScriptGoogleMaps({
  apiKey: 'key',
})

onMounted(() => {
  onLoaded(async (instance) => {
    const maps = await instance.maps
    const geometry = await maps.importLibrary('geometry')
    console.log(geometry.spherical)
  })
})
</script>
```

::callout
在大多数情况下，优先使用 [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) 组件。它处理懒加载、占位图片，并提供声明式 API。当您需要直接访问 SDK 或构建自定义集成时，请使用 `useScriptGoogleMaps()`{lang="ts"}。
::

::warning
Google 于 2026 年 5 月从 Maps JavaScript API 3.65 中移除了绘图库和热力图图层。尽管当前项目类型仍提及 `drawing` 和 `visualization`，但不要将它们用于新的集成。请参阅 Google 的[已完成弃用项](https://developers.google.com/maps/deprecations#completed-deprecations)。
::

## Sitemap

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