# @geolibre/embed 中文文档

规范地址：https://npmcn.com/package/%40geolibre/embed/

版本：3\.8\.0
npm 元数据更新时间：2026-11-14T21:52:02.781Z
中文译文更新时间：2026-11-16T04:27:07.504Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40geolibre/embed
原文对照：https://npmcn.com/package/%40geolibre/embed/?lang=original
项目主页：https://geolibre.app/user-guide/embedding/
源码仓库：https://github.com/opengeos/GeoLibre

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

- 包体积（解压后）：23.2 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-01T22:13:54.009Z
- 最新版本发布：2026-11-14T21:52:02.392Z
- 近 30 天下载量：15471（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

为 GeoLibre iframe 输入的客户端嵌入了 API

## 安装

```sh
npm install @geolibre/embed
```

也可以使用：`pnpm add @geolibre/embed`、`yarn add @geolibre/embed`、`bun add @geolibre/embed`

## README

# @geolibre/嵌入

[![npm version](https://img.shields.io/npm/v/@geolibre/embed.svg)](https://www.npmjs.com/package/@geolibre/embed) [![npm downloads](https://img.shields.io/npm/dm/@geolibre/embed.svg)](https://www.npmjs.com/package/@geolibre/embed) [![license](https://img.shields.io/npm/l/@geolibre/embed.svg)](https://github.com/opengeos/GeoLibre/blob/main/LICENSE)

驱动一个无依赖的打字客户端 [地理图书馆](https://github.com/opengeos/GeoLibre) 嵌入到一个 `<iframe>` 从它的一页.

URL 参数配置 GeoLibre 嵌入一次, 装入时 。 这个包是给 之后的一切:飞去唱片 刚刚有人点击你的UI, 切换图层, 应用过滤器, 将地图导出为 PNG, 并听到用户的内容 在地图内。 它说出GeoLibre的版本 `postMessage` 协议,以及 手动处理容易出错的两个部分: 将每个命令,与它相配 有几个可以马上飞去.

源回波 : [开源软件国际化之简体中文组](https://github.com/opengeos/GeoLibre)编辑 软件包版本跟踪应用程序版本,因为两艘船都来自同一版本.

## 安装

```bash
npm install @geolibre/embed
```

## 使用量

```ts
import { connect } from "@geolibre/embed";

const iframe = document.querySelector("iframe");
const map = await connect(iframe, { origin: "https://gis.example.com" });

await map.setView({ center: [-95.7, 37.1], zoom: 5 });
await map.setLayerVisibility("roads", false);

const layers = await map.listLayers();
console.log(layers.map((layer) => layer.name));

map.on("selectionChanged", ({ featureIds }) => showRecordFor(featureIds[0]));
```

`connect` 一旦应用程序报告它准备好了就解决,所以没有 握起手来写自己。 通过 **应用程序** 源头,不是你自己的:两者都是 每条出入境信息的目标 以及入境信息的过滤器.

## API 密码

`connect(iframe, options)` → `Promise<GeoLibreEmbedClient>`

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `origin` | —— 说 | 要求。 准确的源码托管应用程序 . |
| `timeoutMs` | 15000个 | 等多长时间 `ready`。 。 。 . |
| `requestTimeoutMs` | 15000个 | 每令等多时. |

| 方法 | 决定: |
| --- | --- |
| `loadProject(url)` | `void` |
| `setView(target)` | `void` |
| `highlightFeature({ layerId, … })` | `void` |
| `openTool(id, params?)` | `void` |
| `setLayerVisibility(layerId, visible)` | `void` |
| `listLayers()` | `LayerSummary[]` |
| `setFilter(layerId, expression)` | `void` |
| `getViewport()` | `Viewport` |
| `addLayer(spec)` | 新层 `id` |
| `addData(url, options?)` | 新层 `id`编号 |
| `exportImage()` | a 巴布亚新几内亚 `data:` 網址 |
| `getLayerFeatures(layerId)` | `EmbedFeature[]` |
| `getDrawnFeatures()` | `EmbedFeature[]` |
| `on(event, listener)` | 未订阅函数 |
| `disconnect()` | 没有承诺 |

命令拒绝而不是错误地解决:被拒绝的请求以 应用程序本身的错误信息, 以及一个无法解答的错误信息 暂停 。 打电话 `disconnect()` 当iframe离开, 所以一个等待的诺言 无法挂起页面的生命.

活动 : `ready`, (中文(简体) ), `ack`, (中文(简体) ), `projectLoaded`, (中文(简体) ), `selectionChanged`, (中文(简体) ), `viewChanged`, (中文(简体) ), `toolCompleted`, (中文(简体) ), `serverFileWritten`, (中文(简体) ), `featuresChanged`。 。 。 .

一个希望用户绘制应用程序加载的主机 `layout=viewer&draw`,哪个 让几何编辑器运行在其它只读的查看器中(添加) `plugin=geo-editor` ; 部署需要 `project:edit` 绘制和阅读下面的图画的能力也需要 在嵌入式许可列表和 `export:data` 能力.

`getLayerFeatures(layerId)` 财务报告和审定财务报表 `getDrawnFeatures()` 回读特性 (确切位置为所储存). 它们反映了插件 API `getLayerFeatures` 财务报告和审定财务报表 `getDrawnFeatures` 和 Python 部件 `get_features` 财务报告和审定财务报表 `get_drawn_features`。 。 。 . `getDrawnFeatures` 返回用户的自由绘图(全部) Sketches 分层组合; 如果未绘制空数组 。 他们拒绝 用于未知的图层, 当部署否认时 `export:data`层 持有不包含内存特性( 鼠标、 瓦片、 远程矢量源) 返回 空阵列,所以空阵列表示"没有内相特性"(空出地层, 或光栅、瓦片或远程源);层 `type` 不告诉这些 分开 已删除的层拒绝 . `featuresChanged` (单位:千美元)`{ layerId, featureCount, removed? }`(中文(简体) ) 每层被解开的火 当层的内质特征收集 替换(绘制、编辑、属性编辑、刷新、后入数据;可能 火而不改变内容),同时使用 `removed: true` 在这样的时候 层被删除。 它不会被发送到整个项目负载( 使用 ) `projectLoaded`(中文(简体) ) 需求 `export:data`数字 :

```ts
map.on("featuresChanged", async ({ layerId, removed }) => {
  if (removed) {
    // The layer is gone and getLayerFeatures would reject: drop your copy.
    return;
  }
  const features = await map.getLayerFeatures(layerId);
});
```

## API 关闭, 除非部署选择使用

GeoLibre 的部署忽略了此协议, 直到它命名其来源为止 信任,所以一个公共实例永远不能被任何页面框架所驱动. 对于一个环境变量的多克图像:

```bash
docker run --rm -p 8080:80 \
  -e GEOLIBRE_EMBED_ORIGINS="https://portal.example.com" \
  ghcr.io/opengeos/geolibre:latest
```

静态建筑,用它烤入 `VITE_GEOLIBRE_EMBED_ORIGINS="https://portal.example.com" npm run build`。 。 。 . 公众 `web.geolibre.app` 构建没有允许列表, 因此运行时间 API 用于 您自己的主机部署.

## 文档

见 [嵌入和共享](https://geolibre.app/user-guide/embedding/) 联 合 国 允许列表、 URL 参数、 完整协议引用和原始 `postMessage` 以不愿依赖的主机为例.

## 许可证

麻省理工学院

## 常见问题

### @geolibre/embed 是什么？

为 GeoLibre iframe 输入的客户端嵌入了 API

### 如何安装 @geolibre/embed？

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

### @geolibre/embed 支持 TypeScript 吗？

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

### @geolibre/embed 支持 ESM 还是 CommonJS？

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

### @geolibre/embed 可以商用吗？

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

### @geolibre/embed 的下载量有多少？

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

### @geolibre/embed 还在维护吗？

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

