@geolibre/embed

中文文档
3.8.0发布于 2026/11/15MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 1.5万

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

中文使用文档
文档目录6 节
  1. 安装
  2. 使用量
  3. API 密码
  4. API 关闭, 除非部署选择使用
  5. 文档
  6. 许可证

@geolibre/嵌入

npm version npm downloads license

驱动一个无依赖的打字客户端 地理图书馆 嵌入到一个 <iframe> 从它的一页.

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

源回波 : 开源软件国际化之简体中文组编辑 软件包版本跟踪应用程序版本,因为两艘船都来自同一版本.

安装

npm install @geolibre/embed

使用量

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—— 说要求。 准确的源码托管应用程序 .
timeoutMs15000个等多长时间 ready。 。 。 .
requestTimeoutMs15000个每令等多时.
方法决定:
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数字 :

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

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 用于 您自己的主机部署.

文档

见 嵌入和共享 联 合 国 允许列表、 URL 参数、 完整协议引用和原始 postMessage 以不愿依赖的主机为例.

许可证

麻省理工学院

版本与发布记录

@geolibre/embed 共发布 18 个版本,首次发布于 2026/08/02;过去 12 个月发布了 18 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.8.0latest2026/11/151 天前
3.7.02026/11/087 天前
3.6.12026/11/0313 天前
3.6.02026/10/3115 天前
3.5.22026/10/2819 天前
3.5.12026/10/2720 天前

关于 @geolibre/embed 的常见问题

@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 和提交记录判断。