# @allmaps/maplibre 中文文档

规范地址：https://npmcn.com/package/%40allmaps/maplibre/

版本：1\.0\.0-beta\.44
npm 元数据更新时间：2026-10-01T09:24:36.254Z
中文译文更新时间：2026-11-06T06:55:36.734Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.4 MB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：6 个
- 首次发布：2024-01-08T10:16:14.342Z
- 最新版本发布：2026-09-22T07:08:11.499Z
- 近 30 天下载量：4277（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 6 个）

## 中文简介

Allmaps 地图Libre 类

## 安装

```sh
npm install @allmaps/maplibre
```

也可以使用：`pnpm add @allmaps/maplibre`、`yarn add @allmaps/maplibre`、`bun add @allmaps/maplibre`

## README

# @allmaps/地图

所有地图插件 [地图Libre GL](https://maplibre.org/)。此插件允许显示地理参考 [IIIF 图像](https://iiif.io/) 在地图里。 插件通过加载工作 [地理参考说明](https://iiif.io/api/georef/extension/georef/) 并使用WebGL从一个 IIIF 图像服务器上转换图像,以覆盖其正确的地理位置.

见 [页面存档备份,存于互联网档案馆 allmaps.org](https://allmaps.org/) 更多信息.

[![Example of the Allmaps plugin for MapLibre](https://raw.githubusercontent.com/allmaps/allmaps/main/packages/maplibre/example.jpg)](https://observablehq.com/@allmaps/maplibre-plugin)

实例:

-   [可观察笔记本](https://observablehq.com/@allmaps/maplibre-plugin)
-   [可观察笔记本](https://observablehq.com/@allmaps/maplibre-plugin)

## 如何运作

此插件创建了新类 `WarpedMapLayer` 扩展 MapLibre 的 [`CustomLayerInterface`](https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/)。您可以在 WardedMapLayer 中添加一个或多个地理参考说明(或带有多个地理参考说明的注释页),并在您的 MapLibre 地图中添加 WardedMapLayer 。 这将使您地图Libre地图上的地理参考注释中包含的所有地理参考地图生效.

为了了解每个地理参考地图的引擎盖下会发生什么,请参看 [@ allmaps/ 放弃](https://npmcn.com/package/%40allmaps/render/) 软件包.

此插件继承了大量方法 [@ allmaps/ warpedmapplayer (帮助)](https://npmcn.com/package/%40allmaps/warpedmaplayer/),核心软件包集成连接 Allmaps 插件到 [@ allmaps/ 放弃](https://npmcn.com/package/%40allmaps/render/) 软件包.

## 安装

这个软件包在浏览器和Node.js中作为无害环境管理或UMD模块发挥作用.

用 pnpm 安装 :

```sh
pnpm install @allmaps/maplibre
```

您可以通过运行在本地建立此软件包 :

```sh
pnpm run build
```

在本地开发期间测试此软件包的最简单方法是通过 [@ allmaps/ test- plugins](https://npmcn.com/package/test/plugins/)中还包括一个最小的例子 `./index.html` 并可通过 `pnpm run dev`。 。 。 .

## 使用量

为MapLibre 5.0所建,但也应与更早的版本合作.

### 将一个被扭曲的MapLayer添加到地图里

创建一个 `WarpedMapLayer` 并把它添加到地图上 看起来像这样:

```js
import { Map as MapLibreMap } from 'maplibre-gl'
import { WarpedMapLayer } from '@allmaps/maplibre'

const map = new MapLibreMap({
  container: 'map',
  // @ts-expect-error MapLibre types are incompatible
  style: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json',
  center: [-73.9337, 40.8011],
  zoom: 11.5,
  // Pitch is currently not supported by the Allmaps plugin for MapLibre
  maxPitch: 0
})

const annotationUrl = 'https://annotations.allmaps.org/images/d180902cb93d5bf2'
const warpedMapLayer = new WarpedMapLayer()

map.on('load', () => {
  // @ts-expect-error MapLibre types are incompatible
  map.addLayer(warpedMapLayer)
  warpedMapLayer.addGeoreferenceAnnotationByUrl(annotationUrl)
})
```

被扭曲的MapLayer 使用 MapLibre 执行 [自定义 Layer 界面](https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/)。它可以像其他的 MapLibre 地层一样被添加到地图中,但有些东西需要考虑:

-   `WarpedMapLayer` 不使用一个 [来源](https://maplibre.org/maplibre-style-spec/sources/) (虽然这可以在今后实施,类似于 [@ allmaps/ 打开层](https://npmcn.com/package/%40allmaps/openlayers)) (中文(简体) ).
-   `WarpedMapLayer` 目前不支持投出, 因此在您的地图上禁用它 .
-   就像其他的MapLibre地层一样,一个被扭曲的地图 层必须有一个独特的 `id`默认情况下 `id` 有数值 `warped-map-layer`。当在您的地图上添加多个WardedMapLayers时,通过一个独特的 `id` 切入其构造器:

```js
const warpedMapLayerWithUniqueId = new WarpedMapLayer({layerId: 'my-unique-id'})
```

### 装入地理参考说明的方法

一旦该地层被添加到地图中,就可以在图中添加地理参考注释 `WarpedMapLayer` 使用 `addGeoreferenceAnnotation` 财务报告和审定财务报表 `addGeoreferenceAnnotationByUrl` 函数:

```js
fetch(annotationUrl)
  .then((response) => response.json())
  .then((annotation) => warpedMapLayer.addGeoreferenceAnnotation(annotation))
```

或者说:

```js
await warpedMapLayer.addGeoreferenceAnnotationByUrl(annotationUrl)
```

也可以先创建出WarpedMapList并传递到创作的地层. 这样做的优点是能够先计算出一个被wappedMapList的属性,例如获得界限并传递到MapLibre地图.

```js
import { Map as MapLibreMap } from 'maplibre-gl'

import { WarpedMapLayer } from '@allmaps/maplibre'
import { WarpedMapList } from '@allmaps/render'
import { WebGL2WarpedMap } from '@allmaps/render/webgl2'

const annotationUrl = 'https://annotations.allmaps.org/images/d180902cb93d5bf2'
const annotation = await fetch(annotationUrl).then((response) =>
    response.json()
  )

const warpedMapList = new WarpedMapList<WebGL2WarpedMap>()
await warpedMapList.addGeoreferenceAnnotation(annotation)
const bbox = warpedMapList.getMapsBbox()

map = new MapLibreMap({
  container: 'map',
  // @ts-expect-error MapLibre types are incompatible
  style: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json',
  // Pitch is currently not supported by the Allmaps plugin for MapLibre
  maxPitch: 0
})

map.on('load', () => {
  const warpedMapLayer = new WarpedMapLayer({ warpedMapList })
  // @ts-expect-error MapLibre types are incompatible
  map.addLayer(warpedMapLayer)
  if (bbox) {
    map.fitBounds(bbox, { padding: 20 })
  }
})
```

注意 `...ByUrl()` 函数不可用在 WardedMapList 上.

### 扭曲的MapLayer API, 选项和事件

见 [@ allmaps/ warpedmapplayer (帮助)](https://npmcn.com/package/%40allmaps/warpedmaplayer/) 用于来自 WardedMapLayer 类的方法的 API 文档的软件包(由所有 Allmaps 插件共享)。 它描述的方法像 `addGeoreferenceAnnotation()` ,并包含一个列表,列出可以设置在类实例上的所有选项,以及所有传递给托管层实例的本地地图实例的事件.

你可以设置 **选项** 在整个层上,或在层上的特定地图上(覆盖层选项):

```js
warpedMapLayer.setLayerOptions({ visible: true })
warpedMapLayer.setMapOptions(mapId, { visible: true })
```

你可以听从 **事件** 以典型方式:

```js
map.on('warpedmapadded', (event) => {
  console.log(event.mapIds)
})
```

## 许可证

麻省理工学院

## API 密码

### `MapLibreWarpedMapLayerOptions`

###### 类型

```ts
SpecificMapLibreWarpedMapLayerOptions & Partial<WebGL2RenderOptions>
```

### `new WarpedMapLayer(options)`

创建扭曲的MapLayer实例

###### 参数

-   `options?` (单位:千美元)`Partial<MapLibreWarpedMapLayerOptions> | undefined`(中文(简体) )
    -   选项

###### 回返

`WarpedMapLayer`。 。 。 .

###### 扩展

-   `BaseWarpedMapLayer`
-   `CustomLayerInterface`

### `WarpedMapLayer#getBounds()`

将所有地图的边框取为 MapLibre LngLat Boundes 像对象

这是默认的 MapLibre 获得Bounds () 函数

以 Lon- lat 返回结果 `EPSG:4326`。 。 。 .

###### 参数

没有参数.

###### 回返

所有地图的边框`LngLatBoundsLike | undefined`) (中文(简体) ).

### `WarpedMapLayer#getCenterZoomBearing(options)`

获取中心,缩放和轴承,使"Maplibre地图"的取景口符合地层中的所有地图.

可用作

-   地图. jumpTo () 供立即更改
-   平滑平缓的 Map. Easeto ()
-   Map.flyTo() 用于放大和放大的飞行动画

###### 参数

-   `options?` (单位:千美元)`Partial<Partial<MaskOptions> & { bearingMapIds?: string[]; bearingCallbackFn: (bearing: number) => number; fit: Fit; } & CenterZoomBearing & { ...; } & { ...; }> | undefined`(中文(简体) )

###### 回返

中心、缩放和承载(`{center?: LngLatLike; zoom?: number; bearing?: number}`) (中文(简体) ).

### `WarpedMapLayer#getMapCenterZoomBearing(mapId, options)`

获取中心,缩放和轴承使 Maplibre 地图的取景口符合所选地图所需的.

可用作

-   地图. jumpTo () 供立即更改
-   平滑平缓的 Map. Easeto ()
-   Map.flyTo () 用于一个飞行动画, 它缩放出并回缩放

###### 参数

-   `mapId` (单位:千美元)`string`(中文(简体) )
-   `options?` (单位:千美元)`Partial<Partial<MaskOptions> & { bearingMapIds?: string[]; bearingCallbackFn: (bearing: number) => number; fit: Fit; } & CenterZoomBearing & { ...; } & { ...; }> | undefined`(中文(简体) )

###### 回返

中心、缩放和承载(`{center?: LngLatLike; zoom?: number; bearing?: number}`) (中文(简体) ).

### `WarpedMapLayer#getMapsBounds(mapIds)`

将所有选中地图的边框取为 MapLibre LngLatBounds 像对象

这是默认的 MapLibre 获得Bounds () 函数

以 Lon- lat 返回结果 `EPSG:4326`。 。 。 .

###### 参数

-   `mapIds` (单位:千美元)`Array<string>`(中文(简体) )
    -   地图标识

###### 回返

所有所选地图的边框( r)`LngLatBoundsLike | undefined`) (中文(简体) ).

### `WarpedMapLayer#getMapsCenterZoomBearing(mapIds, partialOptions)`

获取中心,缩放和轴承 使 Maplibre 地图的取景口符合所有选中的地图 .

可用作

-   地图. jumpTo () 供立即更改
-   平滑平缓的 Map. Easeto ()
-   Map.flyTo () 用于一个飞行动画, 它缩放出并回缩放

###### 参数

-   `mapIds` (单位:千美元)`Array<string>`(中文(简体) )
-   `partialOptions?` (单位:千美元)`Partial<Partial<MaskOptions> & { bearingMapIds?: string[]; bearingCallbackFn: (bearing: number) => number; fit: Fit; } & CenterZoomBearing & { ...; } & { ...; }> | undefined`(中文(简体) )

###### 回返

中心、缩放和承载(`{center?: LngLatLike; zoom?: number; bearing?: number}`) (中文(简体) ).

### `WarpedMapLayer#id`

###### 类型

```ts
string
```

### `WarpedMapLayer#map?`

###### 类型

```ts
MaplibreMap
```

### `WarpedMapLayer#nativePassWarpedMapEvent(event)`

传递事件

###### 参数

-   `event` (单位:千美元)`Event`(中文(简体) )

###### 回返

`void`。 。 。 .

### `WarpedMapLayer#nativeUpdate()`

触发地图的本地更新功能

###### 参数

没有参数.

###### 回返

`void`。 。 。 .

### `WarpedMapLayer#onAdd(map, gl)`

当图层被添加时, 方法会调用 .

###### 参数

-   `map` (单位:千美元)`MaplibreMap`(中文(简体) )
    -   此自定义图层是刚刚添加的 .
-   `gl` (单位:千美元)`WebGL2RenderingContext`(中文(简体) )
    -   地图的 WebGL 2 上下文 .

###### 回返

`void`。 。 。 .

### `WarpedMapLayer#onContextLost`

###### 参数

-   `event` (单位:千美元)`MapContextEvent`(中文(简体) )

###### 回返

`void`。 。 。 .

### `WarpedMapLayer#onContextRestored`

###### 参数

-   `event` (单位:千美元)`MapContextEvent`(中文(简体) )

###### 回返

`void`。 。 。 .

### `WarpedMapLayer#onRemove()`

当图层被移除时, 方法会调用 .

###### 参数

没有参数.

###### 回返

`void`。 。 。 .

### `WarpedMapLayer#render()`

翻出一层来.

###### 参数

没有参数.

###### 回返

`void`。 。 。 .

### `WarpedMapLayer#renderingMode`

###### 类型

```ts
'2d'
```

### `WarpedMapLayer#type`

###### 类型

```ts
'custom'
```

## 常见问题

### @allmaps/maplibre 是什么？

Allmaps 地图Libre 类

### 如何安装 @allmaps/maplibre？

在项目目录运行 npm install @allmaps/maplibre，或使用 pnpm add / yarn add / bun add。

### @allmaps/maplibre 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/allmaps\_\_maplibre 是否存在。

### @allmaps/maplibre 支持 ESM 还是 CommonJS？

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

### @allmaps/maplibre 可以商用吗？

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

### @allmaps/maplibre 的下载量有多少？

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

### @allmaps/maplibre 还在维护吗？

最新版本 1\.0\.0-beta\.44 发布于 2026/09/22（1 个月前）；至今共发布 40 个版本，其中过去 12 个月发布了 6 个；首次发布于 2024/01/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。