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

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

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

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

## 选项

<table>
<thead>
  <tr>
    <th>
      选项
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      默认值
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        apiKey
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      您的 Google Maps API 密钥（必填）。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        libraries
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
    </td>
    
    <td>
      <code>
        ['places']
      </code>
    </td>
    
    <td>
      要加载的 Google Maps 库。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        language
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      控件和标签的语言（例如 <code>
        'en'
      </code>
      
      、<code>
        'ja'
      </code>
      
      ）。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        region
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      区域偏向（例如 <code>
        'US'
      </code>
      
      、<code>
        'JP'
      </code>
      
      ）。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        v
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      API 版本：<code>
        'weekly'
      </code>
      
      、<code>
        'quarterly'
      </code>
      
      、<code>
        'beta'
      </code>
      
       或 <code>
        'alpha'
      </code>
      
      。默认省略（Google 默认为 <code>
        'weekly'
      </code>
      
      ）。
    </td>
  </tr>
</tbody>
</table>

## 返回值

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

<tbody>
  <tr>
    <td>
      <code>
        onLoaded
      </code>
    </td>
    
    <td>
      <code>
        (fn) => void
      </code>
    </td>
    
    <td>
      加载器脚本完成后的回调。接收 <code>
        { maps: Promise<typeof google.maps> }
      </code>
      
      ；等待 <code>
        maps
      </code>
      
       以获取 API 回调。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        load
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes github-light github-light material-theme-palenight" language="ts" style="">
        <span class="sx-uw">
          ()
        </span>
        
        <span class="swqme">
          =>
        </span>
        
        <span class="s9nlO">
          Promise
        </span>
        
        <span class="sc1V3">
          <
        </span>
        
        <span class="sqjlB">
          GoogleMapsApi
        </span>
        
        <span class="sc1V3">
          >
        </span>
      </code>
    </td>
    
    <td>
      手动触发脚本加载。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      <code className="language-html shiki shiki-themes github-light github-light material-theme-palenight" language="html" style="">
        <span class="sqjlB">
          Ref
        </span>
        
        <span class="sx-uw">
          <
        </span>
        
        <span class="sFfpx">
          string
        </span>
        
        <span class="sx-uw">
          >
        </span>
      </code>
    </td>
    
    <td>
      当前加载状态（<code>
        'awaitingLoad'
      </code>
      
      、<code>
        'loading'
      </code>
      
      、<code>
        'loaded'
      </code>
      
      、<code>
        'error'
      </code>
      
       或 <code>
        'removed'
      </code>
      
      ）。
    </td>
  </tr>
</tbody>
</table>

## 示例

### 基础地图

加载 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>`](/scripts/google-maps/api/script-google-maps) 组件。它处理懒加载、占位图片，并提供声明式 API。当您需要直接访问 SDK 或构建自定义集成时，请使用 `useScriptGoogleMaps()`。

</callout>

<warning>

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

</warning>