地图编辑器 SDK：如何为 SaaS 产品添加地图创建功能

地图编辑器 SDK 能够把地图创建或编辑功能加入 SaaS 产品，而无需迫使用户转到独立的构建工具。宿主应用继续管理身份、权限、项目、计费、数据所有权和发布策略，SDK 则提供页面内的画布与工具。Kaleidr Editor 会挂载自己的 MapLibre 地图，通过限制来源的可发布密钥进行身份验证，并在宿主定义持久化方案之前将编辑内容保存在内存中。

以下章节涵盖产品边界、架构、挂载、持久化、安全、用户体验和常见错误。若要把对话功能连接到实时渲染器，请参阅如何为地图添加 AI 聊天。若要了解更广泛的 SDK 类别，请参阅什么是 AI 地图 SDK？。

地图编辑器 SDK 要点

编辑界面与产品： 编辑器负责编辑画布；宿主负责用户、项目、权限、持久化和发布。

默认保存在内存： 独立版 Kaleidr Editor 不会持久保存编辑内容，因此应在上线前设计保存和发布流程。

可发布密钥 + design： 使用带有 design 作用域且限制来源的浏览器密钥；切勿暴露服务器密钥。

挂载一次，销毁一次： 将生命周期与 SPA 路由和租户切换绑定。

分离发布权限： 编辑草稿与发布公开地图不应使用相同权限。

SaaS 产品外壳内嵌基于 MapLibre 的地图编辑器，并包含宿主后端持久化和独立的已发布 Viewer 路径。

如何为 SaaS 产品添加地图编辑器 SDK？

本指南把地图创建工作区放入现有 SaaS 工作流。用户可以打开项目、在 MapLibre 画布上编辑、选择底图样式、使用可用的地图工具，并在离开时不残留 SDK 状态。持久化集成到位后，保存、发布和交付仍由宿主控制。示例使用 Kaleidr Editor，因为其文档说明了如何通过共享加载器使用页面内 Editor 产品；评估任何第三方地图编辑器 SDK 时，都可以采用相同的职责划分模型。

地图编辑器 SDK 与 Studio、Viewer 或 GIS 有何区别？

地图编辑器 SDK 是可复用组件，可为另一个应用添加创作工具，包括导航、选择、绘制、样式设置和相关控件。它不应替代宿主的账户系统、数据库、权益、审计记录或项目工作流。可靠的边界是：编辑器拥有编辑界面，宿主产品拥有用户、项目、权限、持久化和发布决策。

产品类型	主要用途	最适合的场景
地图编辑器 SDK	在产品内创建或编辑	必须让用户留在应用内的 SaaS 工作流
独立地图构建器	专用创作应用	可以离开宿主产品工作的团队
已发布地图 Viewer	只读交付	客户或公众浏览地图
地图渲染器	相机和图层 API	由开发者完全定制的地图产品
GIS	权威空间操作	由组织负责的分析和治理

在同一基础上比较 Embedded Editor、Kaleidr Studio、Published Viewer 和 Platform Design API 的四路径决策模型。

Kaleidr Studio 是以提示词为起点、围绕 Prompt → Process → Refine → Deploy 组织的完整创作产品。Kaleidr Editor 是可嵌入的编辑界面，Kaleidr Viewer 用于显示已发布地图。这些路径共享渲染和样式概念，但并不是可互换的产品界面。

SaaS 架构应如何管理编辑器状态？

生产级地图编辑工作流需要明确划分产品外壳、编辑器、凭据、后端策略、数据系统和交付的职责。宿主 SaaS 负责身份、租户、导航、项目、计费、权限和工作流。Kaleidr Editor 负责页面内编辑界面、自己的 MapLibre 地图、生命周期以及可用的客户端工具。可发布密钥赋予浏览器访问 Editor 产品和 design 能力的权限。宿主后端负责授权、持久化、版本控制、审计、导入、导出和发布策略。权威数据系统负责数据集和业务规则。Viewer 或其他目标负责交付经过批准的只读结果。

将浏览器中的内存编辑会话与宿主后端授权、版本控制、租户项目存储和已发布 Viewer 交付分离的架构。

宿主后端不得在未重新授权的情况下信任浏览器提供的项目 ID、租户 ID、数据集 ID 或发布目标。挂载编辑器会让地图创建具有原生体验，但浏览器仍是不可信环境。公开文档说明：product: "editor" 选择 Editor 包；默认入口是 attach/in-process，而不是 iframe；styleId 接受目录中的底图 ID 或完整样式 URL；默认底图为 kaleidr-morning；句柄始终提供 destroy()；支持时还可更新相机和主题。独立嵌入不会持久保存编辑内容；如无额外后端配置，也不包含完整的 AI 驱动 Studio 界面、Control Tower 或自包含的 3D 资产库。

如何安全挂载 Kaleidr Editor？

请确认：API 密钥和嵌入具有 Pro 或 Enterprise 访问权限；可发布密钥允许使用 Editor 且带有 design 作用域；开发、预发布和生产环境设置了精确的允许来源；目标元素具有明确高度；已选择初始样式；宿主具有项目与权限模型；已规划持久化策略和 SPA 销毁流程。只从 https://cdn.kaleidr.com/embed/v1/kaleidr.js 加载一次带版本的加载器。加载器默认处于休眠状态，因此应在加载前启用嵌入，或为每次挂载传入 enabled 选项。最小挂载示例如下：

const editor = Kaleidr.mount("#editor", {
  product: "editor",
  publishableKey: "kld_pk_live_REPLACE_ME",
  styleId: "kaleidr-morning",
  enabled: true
});

window.addEventListener("pagehide", () => {
  editor.destroy();
});

将占位密钥替换为真实的可发布密钥，为编辑工具预留足够的画布高度，并在地图外部播报加载或失败状态。该示例遵循当前的 Editor attach 参考、Editor 集成指南和 kaleidr.js 加载器参考。它只负责挂载编辑器，不会保存内存中的规范，因为公开句柄参考并未记录持久化方法。若声明式标记已足够，可以在 <kaleidr-map> 元素中指定 product="editor"、publishable-key 和 style-id。当宿主需要明确的句柄或由框架管理的生命周期时，应使用命令式 API。在 React 或其他 SPA 中，只在 effect 内挂载一次，并在清理时调用 destroy()；不要在每次表单字段变化时重新挂载。

如何规划持久化、安全和用户体验？

独立嵌入会把编辑内容保存在内存中。团队通常选择三条路径之一：把 Editor 当作原型设计的临时界面；若用户可以离开 SaaS 外壳，则在 Kaleidr Studio 中完成全部创作；或者构建宿主集成工作流，包括项目加载、验证、草稿保存、版本控制、冲突处理、审批、发布、回滚和审计。公开的 Editor SDK 参考没有记录可自行假设的方法，例如未记录的保存方法或变更监听器；在向客户承诺保存功能之前，请与 Kaleidr 确认受支持的状态传输接口。数据集分析、部分应用地图规范、样式或主题目录等平台 design 路由，应通过服务器密钥放在宿主后端。浏览器中的 Editor 继续通过 SDK 使用可发布密钥。

多租户安全模型，将浏览器可发布密钥、Kaleidr 会话、宿主授权、按租户隔离的项目存储以及从草稿到发布的状态分开。

把可发布密钥限制到精确来源，在本地开发之外强制使用 HTTPS，将密钥限制到 design 和必要的产品，并在切换账户或租户时销毁编辑器。在后端按用户和租户授权每个项目与数据集，独立于浏览器状态验证所有权，在持久保存或发布前验证地图规范，并分离草稿、审核和发布权限。OWASP API Security Top 10 将对象级授权失效列为主要风险：浏览器提供的项目 ID 从来不是充分授权。保持产品外壳可见，让用户知道正在编辑哪个项目；把保存和发布放在宿主界面中，不要仅凭内存中的编辑内容制造虚假的“已保存”状态；并预留比 Viewer 通常需要的更多垂直空间。为编辑器区域设置无障碍名称，保留对周边操作的键盘访问，避免焦点陷阱，播报保存和错误状态，并按照 WCAG 2.2 尽可能提供无需拖动的替代操作。

错误	后果	建议修正
假设独立版 Editor 会持久保存工作	会话结束时用户丢失更改	明确设计持久化并确认集成接口
假设未记录的句柄方法	生产系统依赖不存在的 API	只使用已记录的方法
在浏览器代码中暴露服务器密钥	后端 bearer 变为公开信息	使用限制来源的可发布密钥
未启用 SDK 就挂载	加载器保持休眠	启用嵌入或传入 `enabled: true`
未设置容器高度	编辑器折叠或无法使用	预留足够的响应式高度
把 Editor 与 Studio 视为相同产品	预期超出独立嵌入能力	区分嵌入编辑与 Studio 完整创作
信任浏览器中的租户 ID	可能发生跨租户访问	在后端重新授权每个项目
忽略 SPA 销毁处理	重复的编辑器和监听器不断累积	保留句柄并调用 `destroy()`

最终结论

地图编辑器 SDK 可以为 SaaS 产品添加地图创建功能，而无需从头重建完整的编辑画布、渲染器集成和浏览器身份验证模型。Kaleidr Editor 当前提供基于 MapLibre、可嵌入页面的界面，并通过带有 design 作用域的可发布密钥进行身份验证。独立嵌入将编辑内容保存在内存中，因此挂载编辑器并不等于交付完整的持久化创作系统。当产品需要集成编辑界面，且宿主团队将负责项目、权限、持久化、发布和可审计性时，应选择 Editor SDK。若可接受独立的完整创作工作流，则选择 Kaleidr Studio。在向客户承诺保存功能之前，应确认状态传输和所有 AI 辅助接口。

为 SaaS 产品添加地图编辑功能

使用带版本的 JavaScript 加载器、限制来源的可发布密钥和 design 作用域挂载 Kaleidr Editor。请**阅读 Editor 集成指南，了解连接选项和生命周期。有关身份验证、design 端点和宿主集成工作流，请查阅开发者文档**和 Enterprise 要求。

常见问题

什么是地图编辑器 SDK？

地图编辑器 SDK 是可复用组件，可向另一个应用添加地图创建或编辑工具。宿主产品通常继续管理用户、项目、权限、持久化和发布。

Kaleidr Editor 可以嵌入 SaaS 产品吗？

可以。当前 SDK 记录了如何使用 product: "editor" 在目标元素中挂载。Editor 会在页面中创建自己的 MapLibre 地图。

独立版 Editor 会保存用户的地图吗？

不会。公开文档说明编辑内容存在于内存规范中，独立嵌入不会将其持久保存。请在上线前规划宿主持久化。

Editor 使用哪种凭据？

通过 SDK 使用带有 design 作用域、且仅限批准来源的浏览器可发布密钥。切勿在浏览器代码中放置服务器密钥。

Kaleidr Editor 与 Kaleidr Studio 相同吗？

不同。Studio 是以提示词为起点的完整创建和发布产品。Editor 是用于其他应用内部的可嵌入编辑界面。

References

Kaleidr. Attach the Map Editor. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/guides/attach-the-editor
Kaleidr. Auth & Scopes. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/auth-and-scopes
Kaleidr. CORS & Allowed Origins. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/cors-and-allowed-origins
Kaleidr. Editor — Mount the Map Editor. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/sdk/editor-attach
Kaleidr. Endpoints. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/platform-api/endpoints
Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 3 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
Kaleidr. Pricing & Plans. kaleidr.com. Accessed 3 August 2026. https://kaleidr.com/pricing
MapLibre. Map — MapLibre GL JS. Accessed 3 August 2026. https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/
OWASP. OWASP Top 10 API Security Risks — 2023. Accessed 3 August 2026. https://owasp.org/API-Security/editions/2023/en/0x11-t10/
World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 3 August 2026. https://www.w3.org/TR/WCAG22/

@misc{kaleidr_editor_attach,
  title  = {Editor -- Mount the Map Editor},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/sdk/editor-attach}
}

@misc{kaleidr_editor_guide,
  title  = {Attach the Map Editor},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/guides/attach-the-editor}
}

@misc{kaleidr_loader,
  title  = {kaleidr.js -- the Loader},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/sdk/kaleidr-js}
}

@misc{kaleidr_auth_scopes,
  title  = {Auth and Scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 3 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{owasp_api_security,
  title  = {OWASP Top 10 API Security Risks -- 2023},
  author = {{OWASP}},
  note   = {Accessed 3 August 2026},
  url    = {https://owasp.org/API-Security/editions/2023/en/0x11-t10/}
}

@misc{wcag22,
  title  = {Web Content Accessibility Guidelines 2.2},
  author = {{World Wide Web Consortium}},
  note   = {Accessed 3 August 2026},
  url    = {https://www.w3.org/TR/WCAG22/}
}