@geolibre/embed

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

Typed client for GeoLibre's iframe embed API

原始使用文档
文档目录6 节
  1. Install
  2. Usage
  3. API
  4. The API is off unless the deployment opts in
  5. Documentation
  6. License

@geolibre/embed

npm version npm downloads license

Typed, dependency-free client for driving a GeoLibre map embedded in an <iframe> from the page around it.

URL parameters configure a GeoLibre embed once, at load. This package is for everything after that: fly to the record someone just clicked in your own UI, toggle a layer, apply a filter, export the map as a PNG, and hear what the user does inside the map. It speaks GeoLibre's versioned postMessage protocol, and handles the two parts that are easy to get wrong by hand: the origin checks in both directions, and correlating each command with its acknowledgement so several can be in flight at once.

Source repo: opengeos/GeoLibre. The package version tracks the app version, since both ship from the same release.

Install

npm install @geolibre/embed

Usage

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 resolves once the app reports that it is ready, so there is no handshake to write yourself. Pass the app's origin, not your own: it is both the target of every outbound message and the filter on inbound ones.

API

connect(iframe, options) → Promise<GeoLibreEmbedClient>

OptionDefaultDescription
origin—Required. Exact origin hosting the app.
timeoutMs15000How long to wait for ready.
requestTimeoutMs15000How long to wait for each command.
MethodResolves with
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)the new layer's id
addData(url, options?)the new layer ids
exportImage()a PNG data: URL
getLayerFeatures(layerId)EmbedFeature[]
getDrawnFeatures()EmbedFeature[]
on(event, listener)an unsubscribe function
disconnect()not a promise

Commands reject rather than resolving falsely: a rejected request rejects with the app's own error message, and one that goes unanswered rejects with a timeout. Call disconnect() when the iframe goes away, so a pending promise cannot hang for the life of the page.

Events: ready, ack, projectLoaded, selectionChanged, viewChanged, toolCompleted, serverFileWritten, featuresChanged.

A host that wants users to draw loads the app with layout=viewer&draw, which lets the geometry editor run in the otherwise read-only viewer (add plugin=geo-editor to open its toolbar on load); the deployment needs the project:edit capability to draw, and reading the drawings back below also needs your origin on the embed allowlist and the export:data capability.

getLayerFeatures(layerId) and getDrawnFeatures() read features back out (ids exactly as stored). They mirror the plugin API's getLayerFeatures and getDrawnFeatures and the Python widget's get_features and get_drawn_features. getDrawnFeatures returns the user's free drawings (all Sketches layers combined; an empty array if nothing is drawn yet). They reject for an unknown layer and when the deployment denies export:data. A layer that holds no in-memory features (raster, tiles, remote vector sources) returns an empty array, so an empty array means "no in-memory features" (an empty layer, or a raster, tile or remote source); the layer type does not tell these apart. A removed layer rejects. featuresChanged ({ layerId, featureCount, removed? }) fires, debounced per layer, when a layer's in-memory feature collection is replaced (drawings, edits, attribute edits, refreshes, late-loaded data; it may fire without a content change), and at once with removed: true when such a layer is removed. It is not sent for whole project loads (use projectLoaded) and needs 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);
});

The API is off unless the deployment opts in

A GeoLibre deployment ignores this protocol until it names the origins it trusts, so a public instance can never be driven by whatever page frames it. For the Docker image that is one environment variable:

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

For a static build, bake it in with VITE_GEOLIBRE_EMBED_ORIGINS="https://portal.example.com" npm run build. The public web.geolibre.app build sets no allowlist, so the runtime API is for your own hosted deployment.

Documentation

See Embedding & Sharing for the allowlist, the URL parameters, the full protocol reference, and a raw postMessage example for hosts that would rather not take a dependency.

License

MIT

版本与发布记录

@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 是什么?

Typed client for GeoLibre's iframe embed 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 和提交记录判断。