# @dvt3d/maplibre-three-plugin 中文文档

规范地址：https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/

版本：1\.7\.1
npm 元数据更新时间：2026-07-26T15:16:03.988Z
中文译文更新时间：2026-11-13T01:12:45.452Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：49.8 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：three ^0\.178\.0
- 首次发布：2025-07-29T01:13:06.944Z
- 最新版本发布：2026-07-26T15:16:03.845Z
- 近 30 天下载量：14468（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 8 个）

## 中文简介

`maplibre-three-plugin` 是一个巧妙的桥接插件 连接 [MapLibre GL 联合来文](https://maplibre.org/maplibre-gl-js/docs/) 与 [3个J](https://threejs.org/),启用 在地图上执行3D渲染和动画.

## 安装

```sh
npm install @dvt3d/maplibre-three-plugin
```

也可以使用：`pnpm add @dvt3d/maplibre-three-plugin`、`yarn add @dvt3d/maplibre-three-plugin`、`bun add @dvt3d/maplibre-three-plugin`

## README

# 映射三插图

`maplibre-three-plugin` 是一个巧妙的桥接插件 连接 [MapLibre GL 联合来文](https://maplibre.org/maplibre-gl-js/docs/) 与 [3个J](https://threejs.org/),启用 在地图上执行3D渲染和动画.

## 安装

```shell
npm install @dvt3d/maplibre-three-plugin
----------------------------------------
yarn add @dvt3d/maplibre-three-plugin
```

## 快开始

`maplibre-three-plugin` 取决于3,请在使用前确定安装了3个.

```html

<div id="map-container"></div>
```

```javascript

import maplibregl from 'maplibre-gl'
import * as THREE from 'three'
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'
import * as MTP from '@dvt3d/maplibre-three-plugin'

const map = new maplibregl.Map({
  container: 'map-container', // container id
  style: 'https://api.maptiler.com/maps/basic-v2/style.json?key=get_access_key',
  zoom: 18,
  center: [148.9819, -35.3981],
  pitch: 60,
  canvasContextAttributes: { antialias: true },
  maxPitch: 85,
})

//init three scene
const mapScene = new MTP.MapScene(map)

//add light
mapScene.addLight(new THREE.AmbientLight())

// add model
const glTFLoader = new GLTFLoader()

glTFLoader.load('./assets/34M_17/34M_17.gltf', (gltf) => {
  let rtcGroup = MTP.Creator.createRTCGroup([148.9819, -35.39847])
  rtcGroup.add(gltf.scene)
  mapScene.addObject(rtcGroup)
})
```

## 实例

| ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/index.png) | ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/sun-light.png) | ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/point.png) | ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/point-collection.png) |  
QQ:------------------------------------------------------------------------- ----------- --- -- -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | [模式](https://dvt3d.github.io/maplibre-three-plugin/examples/index.html) | [日光灯](https://dvt3d.github.io/maplibre-three-plugin/examples/sun-light.html) | [点](https://dvt3d.github.io/maplibre-three-plugin/examples/point.html) | [点集](https://dvt3d.github.io/maplibre-three-plugin/examples/point-collection.html) | | ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/billboard.png) | ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/div-icon.png) | ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/3d-tiles.png) | ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/3d-tiles-osgb.png) |  
| [广告牌](https://dvt3d.github.io/maplibre-three-plugin/examples/billboard.html) | [divi- icon (英语)](https://dvt3d.github.io/maplibre-three-plugin/examples/div-icon.html) | [3d-平面图](https://dvt3d.github.io/maplibre-three-plugin/examples/3d-tiles.html) | [3d-平面图](https://dvt3d.github.io/maplibre-three-plugin/examples/3d-tiles-osgb.html) |  
| ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/3d-tiles-cesium-ion.png) | ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/3d-gs-cesium-ion.png) | ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/3d-gs-splat.png) | ![pic](https://npmcn.com/package/%40dvt3d/maplibre-three-plugin/examples/heat-map.png) | | [3d-平方厘米离子](https://dvt3d.github.io/maplibre-three-plugin/examples/3d-tiles-cesium-ion.html) | [3d-克-ce离子](https://dvt3d.github.io/maplibre-three-plugin/examples/3d-gs-cesium-ion.html) | [3d- gs- splate (3d- gs- splate) (英语)](https://dvt3d.github.io/maplibre-three-plugin/examples/3d-gs-splat.html) | [热映射](https://dvt3d.github.io/maplibre-three-plugin/examples/heat-map.html) |

## 文档

### 地图景

#### 实例

```js
const mapScene = new MapScene(map)
```

#### 创建

-   构造器( 映射, \[选项\])
    -   段落
        -   `{Map} map` : 映射实例
        -   `{Object} options` : 配置

```js
// config
Object({
  /**
   * Existing THREE.Scene instance.
   * If not provided, an internal default scene will be created.
   */
  scene: null,

  /**
   * Existing THREE.Camera instance.
   * If not provided, an internal default camera will be created.
   */
  camera: null,

  /**
   * Existing THREE.WebGLRenderer instance.
   * If not provided, an internal default renderer will be created.
   */
  renderer: null,

  /**
   * Whether to preserve the drawing buffer.
   * When enabled, the canvas content will be retained after rendering,
   * which is useful for screenshots or readPixels operations.
   * Note: Enabling this may have a performance impact.
   */
  preserveDrawingBuffer: false,

  /**
   * Whether to enable post-processing rendering.
   * When enabled, Three.js content will be rendered through
   * an offscreen render target before being composited onto the map.
   * When disabled, Three.js renders directly into the shared MapLibre canvas
   * for maximum performance and stability.
   */
  enablePostProcessing: false,

  /**
   * Custom frame render loop.
   *
   * This function will be called every frame.
   * If not provided, the internal default render loop will be used.
   *
   * ⚠️ Note:
   * Providing a custom renderLoop means you take full control
   * of the render lifecycle. The built-in rendering pipeline
   * will be bypassed.
   *
   * As a result, the following internal event hooks will
   * NOT be triggered automatically:
   *
   * - preReset
   * - postReset
   * - preRender
   * - postRender
   *
   * If needed, you must manually call the corresponding logic
   * inside your custom renderLoop.
   *
   * @param {MapScene} ins - The current MapScene instance
   */
  renderLoop: (ins) => {
  }
})
```

#### 事件钩子

这些钩子只在使用内部渲染回路时被触发.

-   `preReset` : 一个召唤的钩子 `renderer.resetState` 每个动画框之前
-   `postReset`: 一个召唤的钩子 `renderer.resetState` 每个动画框之后
-   `preRender`: 一个召唤的钩子 `renderer.render` 每个动画框之前
-   `postRender`: 一个召唤的钩子 `renderer.render` 每个动画框之后

#### 属性

-   `{maplibregl.Map} map` 数字 : `readonly`
-   `{HTMLCanvasElement} canvas` 数字 : `readonly`
-   `{THREE.Camera} camera` 数字 : `readonly`
-   `{THREE.Sence} scene` 数字 : `readonly`
-   `{THREE.Group} lights`数字 : `readonly`
-   `{THREE.Group} world` 数字 : `readonly`
-   `{THREE.WebGLRenderer} renderer` 数字 : `readonly`
-   `{EffectComposer} composer` 数字 : `readonly`
-   `{RenderPass} renderPass` 数字 : `readonly`
-   `{OutputPass} outputPass` 数字 : `readonly`

#### 方法

-   **_添加光( 光)_**
    
    在场景中添加光线,支持自定义光线对象,但自定义光线对象需要支持 `delegate` 财产,以及 `delegate` 类型是 `THREE.Object3D`
    
    -   段落
        -   `{THREE.Object3D | Sun | CustomLight } light`
    -   返回时
        -   `this`
-   **_删除光( 光)_**
    
    从现场取出光
    
    -   段落
        -   `{THREE.Object3D | Sun | CustomLight } light`
    -   返回时
        -   `this`
-   **_添加对象(对象)_**
    
    添加对象到世界,支持自定义对象,但自定义对象需要支持 `delegate` 财产,以及 `delegate` 类型是 `THREE.Object3D`
    
    -   段落
        -   `{THREE.Object3D | CustomObject} object`
    -   返回时
        -   `this`
-   **_删除对象(对象)_**
    
    从世界中删除对象
    
    -   段落
        -   `{THREE.Object3D | CustomObject} object`
    -   返回时
        -   `this`
-   **_flyto(目标,\[完成\],\[期限\])_**
    
    在一段时间内将地图飞到提供的目标,当飞行时将触发完成回调 完成后,目标需要控制 `position` 属性
    
    -   段落
        -   `{THREE.Object3D | CustomObject} target`
        -   `{Function} completed`
        -   `{Number} duration`
    -   返回时
        -   `this`
-   **_缩放为( 目标, \[完成\])_**
    
    将地图缩放到提供的目标
    
    -   段落
        -   `{Ojbect} target`
        -   `{Function} completed`
    -   返回时
        -   `this`
-   **_打开( 类型, 回调)_**
    
    注册指定事件类型的事件听众
    
    -   段落
        -   `{String} type`
        -   `{Function} callback`
    -   返回时
        -   `this`
-   **_关闭( 类型, 回调)_**
    
    删除先前为指定事件类型的已注册事件听众
    
    -   段落
        -   `{String} type`
        -   `{Function} callback`
    -   返回时
        -   `this`
-   **_层到( \[Id\] 之前)_**
    
    将 3 移动到不同的 Z- 位置, 如果省略前的 Id , 则图层将附加到图层的末尾 数组,并显示在地图上所有其他图层之上.
    
    -   段落
        -   `{String} beforeId`
    -   返回时
        -   `this`
-   **_添加Pass( 通过)_**
    
    向内部效应计算器添加处理后通行证。 通行证将在最后输出通过前插入 确保正确的渲染顺序.
    
    -   段落
        -   `{THREE.Pass} pass`
    -   返回时
        -   `this`
-   **_删除 Pass( 通过)_**
    
    从内部EffectComposer中删除先前添加的后处理通道.
    
    -   段落
        -   `{THREE.Pass} pass`
    -   返回时
        -   `this`

### 场景变形

#### 实例

```js
const scale = new SceneTransform.projectedUnitsPerMeter(24)
```

#### 静态方法

-   **_预测计算器单元PerMeter ()_**
    
    -   段落
    -   返回时
        -   `{Number} value`
-   **_预测的单位_**
    
    -   段落
        -   `{Number} lat`
    -   返回时
        -   `{Number} value`
-   **_ingLatToVector3 (lng, \[lat\], \[alt\]) (英语)_**
    
    -   段落
        -   `{Array | Number} lng`
        -   `{Number} lat`
        -   `{Number} alt`
    -   返回时
        -   `{THREE.Vector3} v`
-   **_向量 3ToLngLat( v)_**
    
    -   段落
        -   `{THREE.Vector3} v`
    -   返回时
        -   `{Array} value`

### 太阳

#### 实例

```js
const sun = new Sun()
```

#### 创建

-   构造器( )
    -   段落

#### 属性

-   `{THREE.Group} delegate` 数字 : `readonly`
-   `{Boolean} castShadow`
-   `{Date | String} currentTime`
-   `{THREE.DirectionalLight} sunLight` 数字 : `readonly`
-   `{THREE.HemisphereLight} hemiLight`数字 : `readonly`

#### 方法

-   **_更新(框架状态)_**
    -   段落
        -   `{Object} frameState`数字 :
    -   返回时
        -   `this`

### 创建者

#### 实例

```js
const rtcGroup = Creator.createRTCGroup([-1000, 0, 0])
```

#### 静态方法

-   **_创建RTC Group( 中心, \[旋转\], \[比例)_**
    
    -   段落
        -   `{Array} center`
        -   `{Array} rotation`: 默认值为 \[0, 0\]
        -   `{Array} scale`: 与当前纬度相对应的尺度
    -   返回时
        -   `{THREE.Group} group`
-   **_创建MercatorRTC Group( 中心, \[旋转\], \[比例\])_**
    
    -   段落
        -   `{Array} center`
        -   `{Array} rotation`: 默认值为 \[0, 0\]
        -   `{Array} scale`: 与当前纬度相对应的尺度
    -   返回时
        -   `{THREE.Group} group`
-   **_创建 ShadowGround( 中心, \[宽\], \[高\])_**
    
    -   段落
        -   `{THREE.Vector3} center`
        -   `{Number} width`: 默认值为 100
        -   `{Number} height` : 默认值为 100
    -   返回时
        -   `{THREE.Mesh} mesh`

## 常见问题

### @dvt3d/maplibre-three-plugin 是什么？

maplibre-three-plugin 是一个巧妙的桥接插件 连接 MapLibre GL 联合来文 与 3个J,启用 在地图上执行3D渲染和动画\.

### 如何安装 @dvt3d/maplibre-three-plugin？

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

### @dvt3d/maplibre-three-plugin 支持 TypeScript 吗？

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

### @dvt3d/maplibre-three-plugin 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dvt3d/maplibre-three-plugin 可以商用吗？

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

### @dvt3d/maplibre-three-plugin 的下载量有多少？

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

### @dvt3d/maplibre-three-plugin 还在维护吗？

最新版本 1\.7\.1 发布于 2026/07/26（3 个月前）；至今共发布 12 个版本，其中过去 12 个月发布了 8 个；首次发布于 2025/07/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。