GeoLibre嵌入式分享实战：URL参数、viewer模式与iframe集成的完整指南-平芜编程栈

GeoLibre嵌入式分享实战：URL参数、viewer模式与iframe集成的完整指南

【免费下载链接】GeoLibreA lightweight, cloud-native GIS platform for visualizing, exploring, and analyzing geospatial data. It runs in the web browser, on the desktop, on mobile, and inside Jupyter notebooks.项目地址: https://gitcode.com/GitHub_Trending/ge/GeoLibre

GeoLibre 是一款轻量级、云原生的开源 GIS 平台，支持在浏览器、桌面端、移动端和 Jupyter Notebook 中可视化、探索与分析地理空间数据。本文带你 3 步完成它的嵌入式分享：用 URL 参数打开远程地图，用 viewer 模式生成只读交互地图，再用 iframe 把地图嵌入任意网页，并进一步掌握截图就绪信号与 postMessage 运行时通信。

什么是 GeoLibre 嵌入式分享？

GeoLibre 的浏览器版本身就是一个可嵌入的静态站点：没有服务器账号，数据在你的浏览器本地处理。你只需要把地图项目变成一个公开的.geolibre.json链接，然后通过 URL 查询参数告诉地图：

加载哪个项目：url/data参数
以什么界面出现：layout=viewer、maponly等布局参数
初始主题与细节：theme、toolbar、panels等

这正是它"云原生"理念在分享场景的体现——一份地图，一条链接，任意网页。官方参考文档见 docs/user-guide/embedding.md，图文教程见 docs/tutorials/sharing-embedding.md。

第 1 步：生成一个可分享的地图链接

在 GeoLibre 中构建你的地图：添加图层、设置样式、调整到期望的初始视图
打开Project → Share...，确认标题并上传
得到一个公开的项目文件地址（形如https://share.geolibre.app/你/my-map.geolibre.json）

💡 分享会保存图层、样式、插件状态与地图视图；但读取本机文件的图层无法上传——分享对话框会提前把它们列出来。注意：分享服务只存项目文件，不存你的数据文件。

第 2 步：用 URL 参数定制嵌入效果

把项目链接放进url参数，就得到一条"活的"地图链接：

https://web.geolibre.app/?url=https://share.geolibre.app/you/my-map.geolibre.json

更妙的是，参数可以自由组合。最常用的几个：

参数	示例	效果
`url`	`url=.../my-map.geolibre.json`	加载分享项目
`data`	`data=.../places.geojson`	直接加载 GeoJSON/GeoParquet/PMTiles/COG 等公开数据
`style`	`style=.../sample.style.json`	为`data`数据应用 MapLibre 样式
`layout`	`layout=viewer`	只读 viewer 模式（见下节）
`toolbar`	`toolbar=none`	隐藏顶部工具栏，保留侧栏与状态栏
`panels`	`panels=collapsed`	侧栏折叠为图标条；`none`则完全隐藏
`maponly`	`maponly`	隐藏所有界面，只留地图
`theme`	`theme=dark`	初始深色主题

组合示例——一条干净的深色纯地图链接：

https://web.geolibre.app/?url=https://share.geolibre.app/you/project.geolibre.json&maponly&theme=dark

viewer 模式：读者能探索、但改不动的只读地图

layout=viewer是嵌入式分享里最值得记住的参数。它保留：

Layers 面板：含文件夹分组与图层 quick filters——地图不仅能看，还能"提问"
View 菜单与视图快捷键（[、]、n、u、r）
Controls（录制 Tour/视频等只读操作）、底图切换、搜索/识别

同时彻底隐藏一切"创作"入口：拖文件到地图不会导入，几何编辑器、Annotations 等会写项目的插件无法激活，项目快捷键（Ctrl/Cmd+S）和命令面板（Ctrl/Cmd+K）也被禁用。嵌入页无法被键盘、拖拽或项目文件带偏到编辑状态——这对发布到公司门户或报表页面非常重要。

viewer 布局的解析逻辑见 useLayoutOptions.ts，其图层面板实现见 ViewerLayerPanel.tsx。

🎯 选型口诀：读者需要切换图层、探索数据→layout=viewer；地图只是页面里的一张图→maponly。

不分享项目，直接嵌入远程数据

没有现成项目？data参数可以直接打开公开的 GeoJSON、GeoParquet、PMTiles、COG，甚至包含多个 GeoJSON 的 ZIP 包（每个文件成为独立图层）：

https://web.geolibre.app/?data=https://assets.geolibre.app/data/places.geojson&style=https://assets.geolibre.app/data/sample.style.json

重复data可叠加多个数据集，style按位置一一对应。若数据源自带查询参数（如?category=parks），记得整体做 URL 编码，避免&被当成 GeoLibre 自己的分隔符。

第 3 步：把 viewer 放进 iframe

拿到满意的链接后，一段<iframe>即可完成集成：

<iframe src="https://web.geolibre.app/?url=https://share.geolibre.app/you/my-map.geolibre.json&maponly" title="GeoLibre map" width="100%" height="600" style="border: 0;" loading="lazy" allow="fullscreen; geolocation" ></iframe>

三个实用建议：

loading="lazy"：长页面中延迟加载地图，首屏更快
allow属性：授予全屏与定位权限，viewer 的地图工具才能完整工作
按版面调高度：纯地图嵌入时无需为工具栏预留空间

浏览器构建支持地图导航、URL/浏览器选择的数据加载、样式、SQL Workspace 与大部分插件；本地文件对话框、本机 MBTiles 读取、项目保存等桌面独有能力在嵌入中不可用。

进阶一：loading=true 截图就绪信号，报表配图不再"半成品"

自动生成报表、文章配图时，最怕截图截到半加载的地图。给链接加上loading=true，<html>元素就会暴露机器可读的就绪状态：

属性	值
`data-geolibre-load-state`	`loading`/`ready`/`error`
`data-geolibre-load-pending`	待加载图层名的 JSON 数组
`data-geolibre-load-errors`	错误信息 JSON 数组

ready意味着项目已加载、可见图层已挂载、当前视口瓦片就绪、相机停止且字体加载完成（并连续 500ms 保持稳定）。配合 Playwright 等工具，等状态变为ready再截图即可。

进阶二：postMessage 运行时通信，让嵌入地图"活"起来

URL 参数只在加载时生效一次。若想让嵌入地图持续交互——用户在业务系统里点击记录，地图自动飞过去并高亮——用官方的@geolibre/embed类型化客户端：

import { connect } from "@geolibre/embed"; const map = await connect(document.querySelector("iframe"), { origin: "https://web.geolibre.app", }); map.on("selectionChanged", ({ featureIds }) => showRecordFor(featureIds[0])); await map.setView({ center: [-95.7, 37.1], zoom: 5 }); await map.highlightFeature({ layerId: "fields", filter: { parcel_id: 42 }, fit: true });

常用命令一览：

命令	用途
`setView`	飞行到中心点/包围盒
`highlightFeature`	按 id 或属性过滤高亮要素
`setLayerVisibility`	显示/隐藏图层
`addData`	不刷新 iframe 加载远程数据
`exportImage`	导出当前地图 PNG
`on("viewChanged")`	监听相机移动（约 4 次/秒节流）

安全设计：该协议默认关闭，必须在部署端配置可信来源白名单（Docker 中为环境变量GEOLIBRE_EMBED_ORIGINS），双向校验来源，防止任意网页驱动地图；白名单还可进一步收窄可用命令，拒绝的命令会返回明确错误而非静默失败。客户端源码见 packages/embed/src/index.ts，服务端钩子见 useEmbedApi.ts，完整协议参考见 packages/embed/README.md。

常见问题

Q：嵌入的地图会被访客改坏吗？A：layout=viewer下，项目快捷键、命令面板、拖拽导入与写项目插件全部禁用，嵌入页无法进入编辑状态。

Q：为什么私有数据打不开？A：url=/data=使用浏览器同源凭证拉取，登录态 URL 只能在同源部署的 GeoLibre 中打开；公开场景请使用带签名的过期 URL 或自托管部署。

Q：嵌入支持哪些数据格式？A：GeoJSON、GeoParquet、PMTiles（矢量/栅格瓦片）、COG、多文件 ZIP，以及返回 GeoJSON 的 REST API；远程服务器需支持跨域（CORS）与字节范围请求。

小结

场景	推荐方案
网页里放一张干净地图	`url`+`maponly`
读者需要探索数据	`url`+`layout=viewer`
无项目的临时分享	`data`（+ 可选`style`）
报表自动截图	`loading=true`，等`ready`
与业务系统深度联动	`@geolibre/embed`+ 来源白名单