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/GeoLibreGeoLibre 是一款轻量级、云原生的开源 GIS 平台支持在浏览器、桌面端、移动端和 Jupyter Notebook 中可视化、探索与分析地理空间数据。本文带你 3 步完成它的嵌入式分享用 URL 参数打开远程地图用 viewer 模式生成只读交互地图再用 iframe 把地图嵌入任意网页并进一步掌握截图就绪信号与 postMessage 运行时通信。什么是 GeoLibre 嵌入式分享GeoLibre 的浏览器版本身就是一个可嵌入的静态站点没有服务器账号数据在你的浏览器本地处理。你只需要把地图项目变成一个公开的.geolibre.json链接然后通过 URL 查询参数告诉地图加载哪个项目url/data参数以什么界面出现layoutviewer、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/?urlhttps://share.geolibre.app/you/my-map.geolibre.json更妙的是参数可以自由组合。最常用的几个参数示例效果urlurl.../my-map.geolibre.json加载分享项目datadata.../places.geojson直接加载 GeoJSON/GeoParquet/PMTiles/COG 等公开数据stylestyle.../sample.style.json为data数据应用 MapLibre 样式layoutlayoutviewer只读 viewer 模式见下节toolbartoolbarnone隐藏顶部工具栏保留侧栏与状态栏panelspanelscollapsed侧栏折叠为图标条none则完全隐藏maponlymaponly隐藏所有界面只留地图themethemedark初始深色主题组合示例——一条干净的深色纯地图链接https://web.geolibre.app/?urlhttps://share.geolibre.app/you/project.geolibre.jsonmaponlythemedarkviewer 模式读者能探索、但改不动的只读地图layoutviewer是嵌入式分享里最值得记住的参数。它保留Layers 面板含文件夹分组与图层 quick filters——地图不仅能看还能提问View 菜单与视图快捷键[、]、n、u、rControls录制 Tour/视频等只读操作、底图切换、搜索/识别同时彻底隐藏一切创作入口拖文件到地图不会导入几何编辑器、Annotations 等会写项目的插件无法激活项目快捷键Ctrl/CmdS和命令面板Ctrl/CmdK也被禁用。嵌入页无法被键盘、拖拽或项目文件带偏到编辑状态——这对发布到公司门户或报表页面非常重要。viewer 布局的解析逻辑见 useLayoutOptions.ts其图层面板实现见 ViewerLayerPanel.tsx。 选型口诀读者需要切换图层、探索数据→layoutviewer地图只是页面里的一张图→maponly。不分享项目直接嵌入远程数据没有现成项目data参数可以直接打开公开的 GeoJSON、GeoParquet、PMTiles、COG甚至包含多个 GeoJSON 的 ZIP 包每个文件成为独立图层https://web.geolibre.app/?datahttps://assets.geolibre.app/data/places.geojsonstylehttps://assets.geolibre.app/data/sample.style.json重复data可叠加多个数据集style按位置一一对应。若数据源自带查询参数如?categoryparks记得整体做 URL 编码避免被当成 GeoLibre 自己的分隔符。第 3 步把 viewer 放进 iframe拿到满意的链接后一段iframe即可完成集成iframe srchttps://web.geolibre.app/?urlhttps://share.geolibre.app/you/my-map.geolibre.jsonmaponly titleGeoLibre map width100% height600 styleborder: 0; loadinglazy allowfullscreen; geolocation /iframe三个实用建议loadinglazy长页面中延迟加载地图首屏更快allow属性授予全屏与定位权限viewer 的地图工具才能完整工作按版面调高度纯地图嵌入时无需为工具栏预留空间浏览器构建支持地图导航、URL/浏览器选择的数据加载、样式、SQL Workspace 与大部分插件本地文件对话框、本机 MBTiles 读取、项目保存等桌面独有能力在嵌入中不可用。进阶一loadingtrue 截图就绪信号报表配图不再半成品自动生成报表、文章配图时最怕截图截到半加载的地图。给链接加上loadingtruehtml元素就会暴露机器可读的就绪状态属性值data-geolibre-load-stateloading/ready/errordata-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导出当前地图 PNGon(viewChanged)监听相机移动约 4 次/秒节流安全设计该协议默认关闭必须在部署端配置可信来源白名单Docker 中为环境变量GEOLIBRE_EMBED_ORIGINS双向校验来源防止任意网页驱动地图白名单还可进一步收窄可用命令拒绝的命令会返回明确错误而非静默失败。客户端源码见 packages/embed/src/index.ts服务端钩子见 useEmbedApi.ts完整协议参考见 packages/embed/README.md。常见问题Q嵌入的地图会被访客改坏吗Alayoutviewer下项目快捷键、命令面板、拖拽导入与写项目插件全部禁用嵌入页无法进入编辑状态。Q为什么私有数据打不开Aurl/data使用浏览器同源凭证拉取登录态 URL 只能在同源部署的 GeoLibre 中打开公开场景请使用带签名的过期 URL 或自托管部署。Q嵌入支持哪些数据格式AGeoJSON、GeoParquet、PMTiles矢量/栅格瓦片、COG、多文件 ZIP以及返回 GeoJSON 的 REST API远程服务器需支持跨域CORS与字节范围请求。小结场景推荐方案网页里放一张干净地图urlmaponly读者需要探索数据urllayoutviewer无项目的临时分享data 可选style报表自动截图loadingtrue等ready与业务系统深度联动geolibre/embed 来源白名单从一条url参数到postMessage实时联动GeoLibre 的嵌入式分享覆盖了从快速分享一张图到GIS 能力嵌入企业门户的完整光谱——而且全部在浏览器本地完成查看者无需任何账号。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考