跳到主要内容

Editor — 挂载地图编辑器

product="editor" 会将 Kaleidr 地图编辑器挂载到您的页面中。它会在元素内部 创建并控制自己的 MapLibre 地图 — 采用 attach 接入方式， 而不是 iframe。

  • 接入方式： attach — MapLibre 在父文档中运行。
  • 所需作用域： design.
  • 最低套餐： Pro — Free 密钥不允许使用 design 作用域。

开始之前​

  • 您页面的 origin 必须位于密钥的 origin allowlist 中。否则会话交换 将以 403 session_origin_mismatch 失败。file:// 不会发送 Origin，因此始终失败 — 请通过 HTTP(S) 提供。请参阅 获取 API 密钥。
  • 您的 CSP 必须允许 SDK loader、'wasm-unsafe-eval'（页面内的 MapLibre）， 以及 tile/vendor host — 请参阅 Content Security Policy。

挂载​

const handle = Kaleidr.mount('#editor', {
  publishableKey: 'kld_pk_live_…',
  product: 'editor',
  styleId: 'kaleidr-night',  // catalog basemap id or a full style URL
  // Omit it and the organization's stored default applies, falling back to
  // kaleidr-morning when it has none.
});

独立 embed 会运行编辑器的客户端工具 — 地图上的 编辑界面挂载在底图之上，编辑内容保留在 embed 的 内存 spec 中（不会持久化任何内容）。AI 驱动的界面（map-design 和 Control Tower）以及 3D 模型库不属于 独立 embed；它们需要 Kaleidr backend 和由 host 提供的 asset。

对于开发用底图，请传入 tileBase: 'https://tile-dev.kaleidr.com' — 这样目录中的 style id 将基于该地址解析，而不是生产环境的 tile.kaleidr.com。 请参阅 连接编辑器。

相机选项​

center、zoom、pitch 和 bearing 会在挂载时生效。统一 SDK 还会通过 editor handle 转发后续声明式的 相机属性更改。

Handle​

handle.destroy();
handle.setCamera({ center: [-0.12, 51.5], zoom: 11 });  // supported
  • handle.setTheme(...) 在挂载时接受 JSON CSS-token 对象； 通过 handle 进行实时更新将在后续 SDK 版本中提供（挂载时已经 可用）。
  • handle.setStyle(...) 在 editor 中不提供。请在 挂载时使用 styleId，或使用底层 MapLibre 地图自身的 style API 来进行 挂载后的样式切换。

底图请求会自动携带您的密钥​

Kaleidr 底图采用密钥授权 — tile.kaleidr.com 会拒绝未知的浏览器 origin。因此 embed 会通过 MapLibre 的 transformRequest，自动将您的 publishable 密钥 附加到底图请求中：

// what the embed does internally — you don't write this
transformRequest: (url) =>
  url.startsWith('https://tile.kaleidr.com/')
    ? { url: `${url}?key=kld_pk_live_…` }
    : { url };

有两个重要结果需要了解：

  • 密钥的 allowed origins 必须包含页面 origin。 如果密钥 创建时未包含您网站的 origin，则每个 tile 都会返回 429 tile_access_restricted。 请在以下页面更新： kaleidr.com/api-keys。
  • 只会重写 Kaleidr tile URL。 如果您传入位于 其他 host 上的 styleUrl，embed 会保持这些请求不变 — 您的密钥 永远不会附加到第三方 origin。