# @geoql/v-maplibre 中文文档

规范地址：https://npmcn.com/package/%40geoql/v-maplibre/

版本：3\.1\.2
npm 元数据更新时间：2026-11-07T21:07:46.202Z
中文译文更新时间：2026-11-16T04:45:04.403Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.6 MB，137 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：vue ^3\.5\.0，three \>=0\.186\.0，zarrita ^0\.7\.0，apache-arrow ^17\.0\.0，@deck\.gl/core ^9\.3\.0，@deck\.gl/layers ^9\.3\.0，@deck\.gl/mapbox ^9\.3\.0，maplibre-gl-wind ^0\.2\.0，3d-tiles-renderer ^0\.5\.0，@sparkjsdev/spark ^2\.3\.0，maplibre-gl-lidar ^0\.21\.0，@deck\.gl/geo-layers ^9\.3\.0，gaussian-splat-lite ^1\.0\.0，@deck\.gl/mesh-layers ^9\.3\.0，@developmentseed/proj ^0\.7\.0 \|\| ^0\.8\.0 \|\| ^0\.9\.0，@developmentseed/geotiff ^0\.7\.0 \|\| ^0\.8\.0 \|\| ^0\.9\.0，@deck\.gl/aggregation-layers ^9\.3\.0，@dvt3d/maplibre-three-plugin ^1\.7\.0，@geoql/maplibre-gl-starfield ^0\.1\.0，@developmentseed/deck\.gl-zarr ^0\.7\.0 \|\| ^0\.8\.0 \|\| ^0\.9\.0，3d-tiles-rendererjs-3dgs-plugin ^0\.3\.0，@developmentseed/deck\.gl-raster ^0\.7\.0 \|\| ^0\.8\.0 \|\| ^0\.9\.0，@developmentseed/deck\.gl-geotiff ^0\.7\.0 \|\| ^0\.8\.0 \|\| ^0\.9\.0
- 首次发布：2025-11-25T06:32:31.936Z
- 最新版本发布：2026-11-07T21:07:45.873Z
- 近 30 天下载量：13071（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

MapLibre GL 的 Vue 3 组件 - 有完整类型脚本支持的被动映射组件

## 安装

```sh
npm install @geoql/v-maplibre
```

也可以使用：`pnpm add @geoql/v-maplibre`、`yarn add @geoql/v-maplibre`、`bun add @geoql/v-maplibre`

## README

# 翻译:

> MapLibre GL 的 Vue 3 组件 - 构建美丽,反应性的地图应用程序

[![npm version](https://badge.fury.io/js/%40geoql%2Fv-maplibre.svg)](https://www.npmjs.com/package/@geoql/v-maplibre) [![JSR](https://jsr.io/badges/@geoql/v-maplibre)](https://jsr.io/@geoql/v-maplibre) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **用"阴影"吗?** 检查出来 [映射图](https://mapcn-vue.geoql.in/) 用于使用 Tailwind CSS 样式的复制版地图组件.

## 特征

-   🗺️ **完整的地图Libre GL 支持** - 围绕MapLibre GL JS完成包装
-   🔥 **Vue 3 组成 API** - 以现代Vue 3模式建造
-   📦 **类型脚本第一** - 在出色的IDE支持下完全输入
-   🎨 **反应组件** - 反应和可堆肥的地图组件
-   🚀 **Nuxt 4 准备** - 与Nuxt 4和SSR无缝合作
-   🎯 **PMTiles 内建** - 原生支持PMTiles协议
-   🌐 **deck.gl 整合** - 高性能的WebGL可视化层
-   🛰️ **COG/GeoTIFF支助处** - GPU-加速云-平分地层
-   📡 **LiDAR 查看器** - LAS/LAZ/COPC点云可视化并有流线

## 安装

图书馆有 **二个必要的依赖关系**。其他的都是每个特性的选择.

```bash
# pnpm (recommended)
pnpm add @geoql/v-maplibre maplibre-gl

# npm
npm install @geoql/v-maplibre maplibre-gl

# yarn
yarn add @geoql/v-maplibre maplibre-gl
```

盖了 `VMap`, (中文(简体) ), `VMarker`, (中文(简体) ), `VPopup`,所有控件(`VControl*`),以及每个映射Libre-内层(`VLayerMaplibre*`) (中文(简体) ).

### 可选的同伴依赖关系

添加这些 **仅限** 对于你实际使用的地层——选择你需要的东西,保持你的捆绑的收缩. 自兹 **页:1**,每个组都从专用子路径导入(`@geoql/v-maplibre/deck.gl`, (中文(简体) ), `/geotiff`, (中文(简体) ), `/wind`, (中文(简体) ), `/lidar`, (中文(简体) ), `/starfield`(原始内容存档于2018-03-27) (英语). so the core enter never reference deck.gl——见: [迁移到 v2. 0.0](https://npmcn.com/package/%40geoql/v-maplibre/#readme-migrating-to-v200)。 。 。 .

```bash
# deck.gl base — import from '@geoql/v-maplibre/deck.gl'
# VLayerDeckgl, VLayerDeckglScatterplot, VLayerDeckglArc,
# VLayerDeckglLine, VLayerDeckglPath, VLayerDeckglPolygon, VLayerDeckglSolidPolygon,
# VLayerDeckglGeojson, VLayerDeckglIcon, VLayerDeckglText, VLayerDeckglColumn,
# VLayerDeckglBitmap, VLayerDeckglPointCloud
pnpm add @deck.gl/core @deck.gl/layers @deck.gl/mapbox

# Aggregation — VLayerDeckglHeatmap, VLayerDeckglHexagon, VLayerDeckglGrid,
# VLayerDeckglGridCell, VLayerDeckglContour, VLayerDeckglScreenGrid
pnpm add @deck.gl/aggregation-layers

# Geo / tiles — VLayerDeckglTrips, VLayerDeckglMVT, VLayerDeckglTile,
# VLayerDeckglTile3D, VLayerDeckglTerrain, VLayerDeckglH3Hexagon,
# VLayerDeckglH3Cluster, VLayerDeckglS2, VLayerDeckglGeohash,
# VLayerDeckglQuadkey, VLayerDeckglGreatCircle, VLayerDeckglWMS
pnpm add @deck.gl/geo-layers

# 3D mesh — VLayerDeckglSimpleMesh, VLayerDeckglScenegraph
pnpm add @deck.gl/mesh-layers

# Cloud-Optimized GeoTIFF — import from '@geoql/v-maplibre/geotiff'
# VLayerCog, VLayerMultiCog, VLayerMosaic
pnpm add @developmentseed/deck.gl-geotiff @developmentseed/deck.gl-raster @developmentseed/geotiff @developmentseed/proj

# Zarr — import from '@geoql/v-maplibre/geotiff'
# VLayerZarr
pnpm add @developmentseed/deck.gl-zarr zarrita

# GeoArrow — import from '@geoql/v-maplibre/deck.gl'
# VLayerDeckglGeoArrowScatterplot, VLayerDeckglGeoArrowPath,
# VLayerDeckglGeoArrowPolygon, VLayerDeckglGeoArrowSolidPolygon,
# VLayerDeckglGeoArrowText, VLayerDeckglGeoArrowTrips
# (Trips additionally needs @deck.gl/geo-layers — already covered by the
#  deck.gl tile/route line above.)
pnpm add apache-arrow

# Wind particles — import from '@geoql/v-maplibre/wind'
# VLayerWindParticle
# (Wind-data helpers — createWindDataFromOpenWeatherMap, generateWindTexture,
# WindParticleLayer — must be imported directly from 'maplibre-gl-wind'.)
pnpm add maplibre-gl-wind

# LiDAR point cloud viewer — import from '@geoql/v-maplibre/lidar'
# VControlLidar
pnpm add maplibre-gl-lidar

# Three.js starfield skybox for globe projections — import from '@geoql/v-maplibre/starfield'
# VLayerStarfield
pnpm add @geoql/maplibre-gl-starfield three
```

如果您在未安装端点后导入层, 捆绑器将浮出一个 `Cannot find module '...'` 出错 – 从上表中安装缺失的软件包来解决.

## MapLibre GL v6 工人

MapLibre GL v6 以运行时构建的 URL 解决工人的问题, URL 由 lobster 组合 无法看到 —— 请求404 除非工人的 URL 被手接 (单位:千美元)[#160号](https://github.com/geoql/v-maplibre/issues/160)) (中文(简体) ). `VMap` 处理它为 您:它把MapLibre指向一个自成一体的工人,他与图书馆同船, 使用标准 `new URL('./maplibre-worker.js', import.meta.url)` 模式 - Vite( dev + building)和webpack 5都将文件作为资产释放出. 无设置 需要帮助.

更喜欢用你自己建造的工人 `maplibre-gl` 版本吗? 摆在前面 第一个 `VMap` 挂载 — 库保存已有的 URL :

```ts
// app/plugins/maplibre-worker.client.ts (Nuxt) or main.ts (Vite)
import { setWorkerUrl } from 'maplibre-gl';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';

setWorkerUrl(workerUrl);
```

`?worker&url` 是 Vite 特定的。 在其他捆绑者身上,有运送的工人——没有 需要覆盖 .

## 迁移到 v2. 0.0

v2. 0.0 将可选对等层从根条目移到专用子路径上, 所以只安装一个核心的安装不再中转引用 deck.gl / lidar / wind (fixes) [114号](https://github.com/geoql/v-maplibre/issues/114)) (中文(简体) ). 核心组件不变——继续导入 `VMap`, (中文(简体) ), `VMarker`, (中文(简体) ), `VPopup`,每个 `VControl*` (除外) `VControlLidar`和每个 `VLayerMaplibre*` (除外) `VLayerStarfield`从 `@geoql/v-maplibre`。只更新可选对等组件 :

| 构成部分 | 新导入 |
| --- | --- |
| 全体 `VLayerDeckgl*` (基,集合,地,网,地箭) | `@geoql/v-maplibre/deck.gl` |
| `VLayerCog`编号 :`MultiCog`编号 :`Mosaic`编号 :`Zarr` | `@geoql/v-maplibre/geotiff` |
| `VLayerWindParticle` | `@geoql/v-maplibre/wind` |
| `VLayerStarfield` | `@geoql/v-maplibre/starfield` |
| `VControlLidar` | `@geoql/v-maplibre/lidar` |

```diff
- import { VMap, VLayerDeckglScatterplot } from '@geoql/v-maplibre';
+ import { VMap } from '@geoql/v-maplibre';
+ import { VLayerDeckglScatterplot } from '@geoql/v-maplibre/deck.gl';
```

特定组件类型Script类型(例如:. `MosaicSource`, (中文(简体) ), `WindDataPoint`, (中文(简体) ), `LidarControlOptions`移动到与其组件相同的子路径.

## 快速启动

```vue
<script setup lang="ts">
  import { VMap, VMarker } from '@geoql/v-maplibre';
  import 'maplibre-gl/dist/maplibre-gl.css';
  import '@geoql/v-maplibre/dist/v-maplibre.css';

  const mapOptions = {
    style: 'https://demotiles.maplibre.org/style.json',
    center: [-74.5, 40],
    zoom: 9,
  };
</script>

<template>
  <VMap :options="mapOptions" style="height: 500px">
    <VMarker :coordinates="[-74.5, 40]"></VMarker>
  </VMap>
</template>
```

## 构成部分

### 核心组成部分

-   **`VMap`** - 主要地图部分
-   **`VMarker`** - 互动标记
-   **`VPopup`** - 弹出和工具提示

### 映射层组件

-   **`VLayerMaplibreGeojson`** - GeoJSON地层
-   **`VLayerMaplibreVector`** - 矢量地砖层
-   **`VLayerMaplibreRaster`** - 灰瓦层
-   **`VLayerMaplibreImage`** - 图像层
-   **`VLayerMaplibreVideo`** - 视频层
-   **`VLayerMaplibreCanvas`** - 帆布层
-   **`VLayerMaplibreCluster`** - 集群点层
-   **`VLayerMaplibrePmtile`** - 金属层
-   **`VLayerMaplibreHillshade`** - 山荫从光栅下流出
-   **`VTerrain`** - 当地地图Libre3D地形(`map.setTerrain`(中文(简体) )
-   **`VSky`** - 投放三维视图的天空、地平线和雾(`map.setSky`(中文(简体) )
-   **`VLayerMaplibreRoute`** - 路线/交付跟踪可视化
-   **`VLayerStarfield`** - 用于地球预测的 " 三.j " 星野 " 天盒 " (需要 `@geoql/maplibre-gl-starfield`, (中文(简体) ), `three`(中文(简体) )

### deck.gl 层组件

由甲板提供动力的高性能WebGL可视化层. gl:

**核心层**

-   `VLayerDeckglScatterplot` - 圆/点
-   `VLayerDeckglArc` - 起源地弧
-   `VLayerDeckglLine` - 平线
-   `VLayerDeckglPath` - 多线/路线
-   `VLayerDeckglPolygon` - 填充的多边形
-   `VLayerDeckglGeojson` - GeoJSON特征
-   `VLayerDeckglIcon` - 自定义标记
-   `VLayerDeckglText` - 文本标签
-   `VLayerDeckglColumn` - 三维栏
-   `VLayerDeckglBitmap` - 地理参考图像

**聚合层**

-   `VLayerDeckglHeatmap` - 密度热图
-   `VLayerDeckglHexagon` - 六边形正箱
-   `VLayerDeckglGrid` - 平方网格聚合
-   `VLayerDeckglContour` - 轮廓/同位素
-   `VLayerDeckglScreenGrid` - 屏幕空间网格

**地层**

-   `VLayerDeckglTrips` - 动画路径
-   `VLayerDeckglMVT` - 地图箱矢量平面
-   `VLayerDeckglTile` - 普通瓷砖
-   `VLayerDeckglTile3D` - 三维平面 (铯)
-   `VLayerDeckglTerrain` - 地面网点
-   `VLayerDeckglH3Hexagon` - H3 六边形
-   `VLayerDeckglH3Cluster` - H3六角星区
-   `VLayerDeckglGreatCircle` - 伟大的圆弧
-   `VLayerDeckglWMS` - 网络地图服务瓦

**平板系统层**

-   `VLayerDeckglS2` - Google S2几何单元格
-   `VLayerDeckglGeohash` - 地理空间指数化
-   `VLayerDeckglQuadkey` - 平面图 四方牌
-   `VLayerDeckglGridCell` - 预汇总网格细胞

**网格层**

-   `VLayerDeckglSimpleMesh` - 3D胶片
-   `VLayerDeckglScenegraph` - glTF/GLB模型

**点云层**

-   `VLayerDeckglPointCloud` - LiDAR/相片点云
-   `VLayerDeckglSolidPolygon` - 三维外推固态多边形

**稀释层** (所需经费) `@developmentseed/deck.gl-raster` 财务报告和审定财务报表 `@developmentseed/deck.gl-geotiff`(中文(简体) )

-   `VLayerCog` - 云-平面化的地表-地表视化(GPU-加速,自动再预测)
-   `VLayerMosaic` - STAC项目的客户方COG镶嵌(要求) `flatbush`, (中文(简体) ), `proj4`(中文(简体) )

**地线层** (所需经费) `@deck.gl/layers` + 键 `apache-arrow`; 旅行也需要 `@deck.gl/geo-layers`(中文(简体) )

渲染Apache 箭头 `Table` 编号 : `RecordBatch` 直接使用 GeoArrow 扩展类型的数据——无 GeoJSON 解析。 GeoParquet / Arrow IPC源和非常大点/多角数据集的理想. 包装器在 Vue 包装器内提取出 GeoArrow 几何相柱, 并将平缓缓冲属性输入 stock deck.gl 层- no `@geoarrow/deck.gl-geoarrow` 运行时间依赖.

-   `VLayerDeckglGeoArrowScatterplot` - 从地理箭头点/多点列取出点
-   `VLayerDeckglGeoArrowPath` - 来自地箭线/多行串列的多行线
-   `VLayerDeckglGeoArrowPolygon` - 由地心箭形多边形/多多多边形列填充+中取多边形
-   `VLayerDeckglGeoArrowSolidPolygon` - 3D挤出多边形(高通缩相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相接相相
-   `VLayerDeckglGeoArrowText` - 地理箭点位置的文本标签
-   `VLayerDeckglGeoArrowTrips` - 动画沿地心箭线行走,带有倒数时间戳

**风能视觉** (所需经费) `maplibre-gl-wind`(中文(简体) )

-   `VLayerWindParticle` - 有以速度为基础的彩色坡道的动画风粒子流

> 风能数据帮助者(`createWindDataFromOpenWeatherMap`, (中文(简体) ), `generateWindTexture`, (中文(简体) ), `WindParticleLayer`, (中文(简体) ), `windUniforms`已经 **没有** 从 `@geoql/v-maplibre`。直接从 `maplibre-gl-wind`数字 :
> 
> ```ts
> import { createWindDataFromOpenWeatherMap } from 'maplibre-gl-wind';
> ```

**一般层**

-   `VLayerDeckgl` - 直接使用任何甲板.gl层级

### 控制组件

-   **`VControlNavigation`** - 导航控制(分区、旋转)
-   **`VControlScale`** - 规模指标
-   **`VControlGeolocate`** - 地理位置控制
-   **`VControlFullscreen`** - 全屏切换
-   **`VControlAttribution`** - 归属控制
-   **`VControlLidar`** - LiDAR点云查看器(LAS/LAZ/COPC支持、流线、彩色方案)

## deck.gl 实例

```vue
<script setup lang="ts">
  import { VMap, VLayerDeckglScatterplot } from '@geoql/v-maplibre';

  const mapOptions = {
    style: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
    center: [-122.4, 37.8],
    zoom: 11,
  };

  const data = [
    { coordinates: [-122.4, 37.8], size: 100 },
    { coordinates: [-122.5, 37.7], size: 200 },
  ];
</script>

<template>
  <VMap :options="mapOptions" style="height: 500px">
    <VLayerDeckglScatterplot
      id="points"
      :data="data"
      :get-position="(d) => d.coordinates"
      :get-radius="(d) => d.size"
      :get-fill-color="[255, 140, 0]"
      :radius-min-pixels="5"
      :pickable="true"
      @click="(info) => console.log('Clicked:', info.object)"
    ></VLayerDeckglScatterplot>
  </VMap>
</template>
```

## 风能可视化示例

```vue
<script setup lang="ts">
  import { VMap, VLayerWindParticle } from '@geoql/v-maplibre';

  const mapOptions = {
    style: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
    center: [0, 20],
    zoom: 2,
  };

  // Wind data points with speed (m/s) and direction (degrees, 0=North)
  const windData = [
    { lat: 40.7, lon: -74.0, speed: 5.2, direction: 180 },
    { lat: 34.0, lon: -118.2, speed: 3.1, direction: 270 },
    // ... more points
  ];
</script>

<template>
  <VMap :options="mapOptions" style="height: 500px">
    <VLayerWindParticle
      id="wind"
      :wind-data="windData"
      :num-particles="8192"
      :speed-factor="50"
      :color-ramp="[
        [0.0, [59, 130, 189, 255]],
        [0.5, [253, 174, 97, 255]],
        [1.0, [213, 62, 79, 255]],
      ]"
      :speed-range="[0, 30]"
    ></VLayerWindParticle>
  </VMap>
</template>
```

## 使用 Nuxt

对于 Nuxt 应用程序,请将地图组件以 `ClientOnly`数字 :

```vue
<script setup lang="ts">
  import { VMap } from '@geoql/v-maplibre';

  const mapOptions = {
    style: 'https://demotiles.maplibre.org/style.json',
    center: [-74.5, 40],
    zoom: 9,
  };
</script>

<template>
  <ClientOnly>
    <VMap :options="mapOptions" style="height: 500px"></VMap>
  </ClientOnly>
</template>
```

添加样式到您的 `nuxt.config.ts`数字 :

```typescript
export default defineNuxtConfig({
  css: [
    'maplibre-gl/dist/maplibre-gl.css',
    '@geoql/v-maplibre/dist/v-maplibre.css',
  ],
});
```

## 类型脚本支持

所有组件全部输入。 视需要导入类型:

```typescript
import type { MapOptions, LngLatLike } from 'maplibre-gl';
import type { Color, PickingInfo } from '@deck.gl/core';
```

## 发展

此软件包是 [v- maplibre 单列](https://github.com/geoql/v-maplibre)。 。 。 .

```bash
# Clone and install (from monorepo root)
git clone https://github.com/geoql/v-maplibre.git
cd v-maplibre
pnpm install

# Build this package
pnpm --filter @geoql/v-maplibre run build

# Run tests
pnpm run test

# Watch mode
pnpm run dev:lib
```

## 许可证

麻省理工学院执照 - 看 [自由主义](https://npmcn.com/package/%40geoql/v-maplibre/LICENSE) 详情

## 贷项

以下列方式建造:

-   [MapLibre GL 联合来文](https://maplibre.org/)
-   [甲板.gl (英语)](https://deck.gl/)
-   [第3组](https://vuejs.org/)
-   [维特](https://vitejs.dev/)
-   [导弹](https://github.com/protomaps/PMTiles)

## 捐款

欢迎捐款! 请随意提交拉力请求.

* * *

由 GeoQL 制作

## 常见问题

### @geoql/v-maplibre 是什么？

MapLibre GL 的 Vue 3 组件 - 有完整类型脚本支持的被动映射组件

### 如何安装 @geoql/v-maplibre？

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

### @geoql/v-maplibre 支持 TypeScript 吗？

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

### @geoql/v-maplibre 支持 ESM 还是 CommonJS？

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

### @geoql/v-maplibre 可以商用吗？

@geoql/v-maplibre 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @geoql/v-maplibre 的下载量有多少？

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

### @geoql/v-maplibre 还在维护吗？

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

