# @googlemaps/three 中文文档

规范地址：https://npmcn.com/package/%40googlemaps/three/

版本：4\.0\.13
npm 元数据更新时间：2026-05-14T23:26:38.114Z
中文译文更新时间：2026-11-16T20:10:11.415Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40googlemaps/three
原文对照：https://npmcn.com/package/%40googlemaps/three/?lang=original
项目主页：https://github.com/googlemaps/js-three
源码仓库：https://github.com/googlemaps/js-three

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：778 kB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：three \*
- 首次发布：2021-06-02T17:13:38.771Z
- 最新版本发布：2024-04-26T20:34:07.319Z
- 近 30 天下载量：39951（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 0 个）

## 中文简介

[![npm](https://img.shields.io/npm/v/@googlemaps/three)](https://www.npmjs.com/package/@googlemaps/three) ![Build](https://github.com/googlemaps/js-three/workflows/Test/badge.svg) \[释 (出[https://github.com/googlemaps/js-3/workflows/Release/badge.s. 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/googlemaps/js-three/workflows/Release/badge.s)

## 安装

```sh
npm install @googlemaps/three
```

也可以使用：`pnpm add @googlemaps/three`、`yarn add @googlemaps/three`、`bun add @googlemaps/three`

## README

# 谷歌地图 三JS 重叠视图和公用事业

[![npm](https://img.shields.io/npm/v/@googlemaps/three)](https://www.npmjs.com/package/@googlemaps/three) ![Build](https://github.com/googlemaps/js-three/workflows/Test/badge.svg) ![Release](https://github.com/googlemaps/js-three/workflows/Release/badge.svg) [![codecov](https://codecov.io/gh/googlemaps/js-three/branch/main/graph/badge.svg)](https://codecov.io/gh/googlemaps/js-three) ![GitHub contributors](https://img.shields.io/github/contributors/googlemaps/js-three?color=green) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) [![](https://github.com/jpoehnelt/in-solidarity-bot/raw/main/static//badge-flat.png)](https://github.com/apps/in-solidarity) [![Discord](https://img.shields.io/discord/676948200904589322?color=6A7EC2&logo=discord&logoColor=ffffff)](https://discord.gg/jRteCzP)

## 说明

添加 [3个j](https://threejs.org/) google地图平台JS的天体。 这个 图书馆提供 a `ThreeJSOverlayView` 扩展类 `google.maps.WebGLOverlayView` 和将地理坐标(纬度/经度)转换为 3.js使用的坐标系统中的矢量.

## 安装

通过 npm 作为软件包可用 [@googlemaps/ 三页](https://www.npmjs.com/package/@googlemaps/three)。 。 。 .

```
npm i @googlemaps/three
```

或者您可以使用 : unpkg 或其他 CDN 类。 在这种情况下,在装入前确保装入3.js 此库 :

```
<script src="https://unpkg.com/three/build/three.min.js"></script>
<script src="https://unpkg.com/@googlemaps/three/dist/index.min.js"></script>
```

在通过 unpkg 添加时,该软件包可按 `google.maps.plugins.three`。可以通过使用 `https://unpkg.com/@googlemaps/three@VERSION/dist/...`。 。 。 .

第三个选择是通过ES-Module的进口,类似于 三.j. 实例有效。 为此,您首先需要指定 [导入图](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) (例如使用unpkg.com,但它与任何其他CDN一样有效) 或自寄文件 :

```html
<script type="importmap">
  {
    "imports": {
      "three": "https://unpkg.com/three/build/three.module.js",
      "@googlemaps/three": "https://unpkg.com/@googlemaps/three/dist/index.esm.js"
    }
  }
</script>
```

为了支持尚未执行导入图的浏览器,您可以 使用该 [s-moule-shims 软件包](https://github.com/guybedford/es-module-shims)。 。 。 .

之后,你可以使用 三.js 和 三JS OverlayView 像你什么时候会 使用捆绑机.

```html
<script type="module">
  import * as THREE from "three";
  import { ThreeJSOverlayView } from "@googlemaps/three";

  // ...
</script>
```

## 文档

检查引用 [文档](https://googlemaps.github.io/js-three/index.html)。 。 。 .

### 坐标、投影和锁定点

三.js场景中的坐标系统(所谓的"世界") 坐标')是z-up方向的一个右手坐标系统. Y轴正指正向北,x轴正指正向东. 这个 单位为米. 所以重点 `new Vector3(0, 50, 10)` 为 10 公尺 在地面上,在指定锚地以东50米处.

这个锚点和取向可以在构造器中设定,或者通过使用 `setAnchor()` 财务报告和审定财务报表 `setUpAxis()`\-方法(注意所有物体位置在 您的场景取决于锚点和方向, 所以他们必须是 当其中任何一个被修改时重算:

```typescript
import { ThreeJSOverlayView } from "@googlemaps/three";

const overlay = new ThreeJSOverlayView({
  anchor: { lat: 37.7793, lng: -122.4192, altitude: 0 },
  upAxis: "Y",
});

overlay.setAnchor({ lat: 35.680432, lng: 139.769013, altitude: 0 });
overlay.setUpAxis("Z");
// can also be specified as Vector3:
overlay.setUpAxis(new Vector3(0, 0, 1));
```

> 本库使用的默认上轴为z轴(+x为东) +y为北),这与通常的y-up方向不同 以三为用.

GPU上所有与位置相关的计算都使用浮点32数字, 将可能的精确度限制在小数点后七点左右。 因为 我们无法使用全球参考系统 精确显示米至厘米范围内的细节.

锚点在这里很重要。 锚指定 地球空间起源地地理坐标(纬度/升/海平面) 坐标系统是,你总是应该定义它接近 物体被放置在现场 - 当然,除非您只与 在全球分布的大型(城市大小)物体.

将锚放近现场物体的另一个原因 一般来说,这是一个好主意: 在谷歌地图中使用的商机地图投影中, 测量表的缩放只有在靠近赤道的区域才准确。 这个 可以通过适用一个取决于 锚的纬度。 这个比例系数计入坐标 在WebGlOverlayView中根据锚的纬度进行计算.

#### 转换坐标

当你需要的不仅仅是你场景中的 单一地理参照物时, 您需要计算这些坐标的世界空间位置。 这个 ThreeJSOverlayView 类为此转换提供了辅助函数 取当前 `anchor` 财务报告和审定财务报表 `upAxis` 考虑到:

```typescript
const coordinates = { lat: 12.34, lng: 56.78 };
const position: Vector3 = overlay.latLngAltitudeToVector3(coordinates);

// alternative: pass the Vector3 to write the position
// to as the second parameter, so to set the position of a mesh:
overlay.latLngAltitudeToVector3(coordinates, mesh.position);
```

### 广播和互动

如果您想要在任何 3.j 内容中添加交互性, 通常您会 必须实施线播音。 我们帮你搞定了 ThreeJS OverlayView 提供了一个方法 `overlay.raycast()` 为了这个 来做 使用它,您首先必须跟踪地图上的鼠标移动情况 :

```js
import { Vector2 } from "three";

// ...

const mapDiv = map.getDiv();
const mousePosition = new Vector2();

map.addListener("mousemove", (ev) => {
  const { domEvent } = ev;
  const { left, top, width, height } = mapDiv.getBoundingClientRect();

  const x = domEvent.clientX - left;
  const y = domEvent.clientY - top;

  mousePosition.x = 2 * (x / width) - 1;
  mousePosition.y = 1 - 2 * (y / height);

  // since the actual raycasting is performed when the next frame is
  // rendered, we have to make sure that it will be called for the next frame.
  overlay.requestRedraw();
});
```

随着鼠标位置一直更新,您可以使用 `raycast()` 函数 `onBeforeDraw` 调用. 在这个例子中,我们更改光标下对象的颜色:

```js
const DEFAULT_COLOR = 0xffffff;
const HIGHLIGHT_COLOR = 0xff0000;

let highlightedObject = null;

overlay.onBeforeDraw = () => {
  const intersections = overlay.raycast(mousePosition);
  if (highlightedObject) {
    highlightedObject.material.color.setHex(DEFAULT_COLOR);
  }

  if (intersections.length === 0) return;

  highlightedObject = intersections[0].object;
  highlightedObject.material.color.setHex(HIGHLIGHT_COLOR);
};
```

完整的例子可见于 [`./examples/raycasting.ts`](https://npmcn.com/package/%40googlemaps/three/examples/raycasting.ts)。 。 。 .

## 示例

下面的例子提供了一个骨架,用来用这个库将对象添加到地图上.

```js
import * as THREE from "three";
import { ThreeJSOverlayView, latLngToVector3 } from "@googlemaps/three";

// when loading via UMD, remove the imports and use this instead:
// const { ThreeJSOverlayView, latLngToVector3 } = google.maps.plugins.three;

const map = new google.maps.Map(document.getElementById("map"), mapOptions);
const overlay = new ThreeJSOverlayView({
  map,
  upAxis: "Y",
  anchor: mapOptions.center,
});

// create a box mesh
const box = new THREE.Mesh(
  new THREE.BoxGeometry(10, 50, 10),
  new THREE.MeshMatcapMaterial()
);
// move the box up so the origin of the box is at the bottom
box.geometry.translateY(25);

// set position at center of map
box.position.copy(overlay.latLngAltitudeToVector3(mapOptions.center));

// add box mesh to the scene
overlay.scene.add(box);

// rotate the box using requestAnimationFrame
const animate = () => {
  box.rotateY(THREE.MathUtils.degToRad(0.1));

  requestAnimationFrame(animate);
};

// start animation loop
requestAnimationFrame(animate);
```

这在地图上增加了一个框.

![threejs box on map](https://storage.googleapis.com/geo-devrel-public-buckets/box.png)

## 演示文稿

在操作中查看软件包 :

-   [基本示例](https://googlemaps.github.io/js-three/public/basic/)
-   [锁定示例](https://googlemaps.github.io/js-three/public/anchor/)
-   [方向示例](https://googlemaps.github.io/js-three/public/orientation/)

## 常见问题

### @googlemaps/three 是什么？

\[释 \(出https://github\.com/googlemaps/js-3/workflows/Release/badge\.s\. 互联网档案馆的存檔,存档日期2013-12-22

### 如何安装 @googlemaps/three？

在项目目录运行 npm install @googlemaps/three，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：three（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @googlemaps/three 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @googlemaps/three 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @googlemaps/three 可以商用吗？

@googlemaps/three 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @googlemaps/three 的下载量有多少？

根据 npm 官方下载统计，@googlemaps/three 在 2026/10/17 – 2026/11/15 这 30 天内被下载 39,951 次，日均约 1,332 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @googlemaps/three 还在维护吗？

最新版本 4\.0\.13 发布于 2024/04/27（2 年前）；至今共发布 53 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/06/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

