嵌入地图编辑器

完成本指南后，您的网页将显示 Kaleidr 地图底图及与品牌风格一致的地图编辑工具。所有套餐（包括 Free）均可使用。您需要带有 design 权限范围的可公开使用密钥；新建密钥默认包含该权限。

编辑内容不会保存

嵌入式编辑器仅在页面内存中保留编辑结果。不会通过嵌入组件保存、导出或发布任何内容，页面也不会收到变更回调。刷新页面或调用 handle.destroy() 都会丢失编辑内容。如果需要永久保存地图，请在 Kaleidr Studio 中创建，再使用 Viewer 嵌入。

开始之前

从 kaleidr.com/api-keys 获取可公开使用密钥 (kld_pk_live_…)。参阅获取 API 密钥。
如果密钥设置了允许的来源，请将测试网页的来源（例如 http://localhost:3000）加入列表。没有来源限制的密钥可以在任意网站使用。
准备通过 HTTP 提供页面的方式，例如 npx serve .。
如果网站设置了内容安全策略（CSP），请允许 Content Security Policy 中的编辑器指令。编辑器运行在页面内，需要 connect-src、img-src、worker-src、font-src 和 style-src 配置，iframe 产品则不需要这些配置。
同一页面不要同时加载其他 Kaleidr 编辑器。

第 1 步：添加指定尺寸的容器并挂载编辑器

<div id="editor" style="height:640px"></div>

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<script>
  const handle = Kaleidr.mount('#editor', {
    product: 'editor',
    publishableKey: 'kld_pk_live_…',
  });
</script>

**预期结果：**容器中显示世界范围的 Kaleidr 底图（默认 kaleidr-morning，除非组织另设默认值），地图上有 Create 按钮。点击 Create 可打开编辑器侧边栏，使用文字、图片、标记和弹出窗口工具。

容器必须设置高度。编辑器会占据容器宽度与高度的 100%，所有面板都限制在容器内。

也可以使用自定义元素。它默认采用 display:block，因此高度设置会生效；示例中再次写入 display:block，以兼容 Safari 16.4 之前的版本：

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style="display:block; height:640px"></kaleidr-map>

第 2 步：选择底图和初始相机视角

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-night',
  center: [-0.1276, 51.5072], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
});

**预期结果：**深色底图显示经过倾斜和旋转的伦敦市中心。

底图选择优先级如下：

如果传入 styleId，就使用指定样式，例如 kaleidr-morning、kaleidr-afternoon、kaleidr-evening、kaleidr-night、kaleidr-plain 或 kaleidr-editorial。各样式说明参阅 Tile 参考文档。
否则使用组织已配置的默认底图（如有）。
如果没有组织默认值，则使用 kaleidr-morning。

相机默认中心为 [0, 0]、缩放级别 2、倾斜角 0、旋转角 0。与 Viewer 和 Tile 不同，编辑器允许单独传入 zoom，无需同时指定 center。

通过 Kaleidr.mount 传入的相机选项若不是有限数值，将被忽略并在控制台提示。对于元素属性，非数字的相机值会被直接丢弃，不显示消息。

[kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.

第 3 步：设置面板主题（可选）

通过 theme 让编辑器面板匹配产品风格。该对象最多支持 17 个指定名称的键；其他键将被忽略。

const handle = Kaleidr.mount('#editor', {
  product: 'editor',
  publishableKey: 'kld_pk_live_…',
  theme: {
    brandColor: '#0b5fff',
    brandColorHover: '#0847c2',
    brandColorOn: '#ffffff',
    fontPrimary: '"Inter", system-ui, sans-serif',
    cardRadius: '12px',
    buttonRadius: '8px',
  },
});

**预期结果：**当前工具、焦点轮廓和主要按钮采用品牌色，面板使用品牌字体。

全部 17 个键参阅编辑器参考文档。

需要注意的三点：

所有值都是 CSS 值。brandColor 接受任意 CSS 颜色；cardRadius 接受任意 CSS 长度；fontPrimary 接受任意 font-family 值。字体资源需自行加载。
编辑器挂载期间，主题应用到整个文档，销毁时会恢复之前的值。只有您自己的样式使用相同自定义属性时才可能受到影响。
主题仅在挂载时读取。编辑器不支持 handle.setTheme。若要更换主题，必须销毁并重新挂载编辑器，这会丢失已有编辑内容。

在自定义元素上，theme 是 JSON 字符串：

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             theme='{"brandColor":"#0b5fff","buttonRadius":"8px"}'
             style="display:block; height:640px"></kaleidr-map>

第 4 步：从网页控制相机移动（可选）

document.getElementById('paris').addEventListener('click', () => {
  // With a duration the map animates. Without one it jumps.
  handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });
});

**预期结果：**地图飞行至巴黎，用户在地图上放置的所有内容仍留在原始位置。

setCamera 是网页控制编辑器地图的唯一方式。返回的句柄不会暴露地图对象。

第 5 步：销毁编辑器

handle.destroy();

destroy() 会从容器移除编辑器、地图和面板，并恢复主题值。所有编辑内容都会丢失。

在单页应用中，当承载编辑器的路由或组件卸载时，应调用 destroy()。使用自定义元素时，将其从文档中移除有同样效果。参阅框架集成。

每个网页同时只能存在一个编辑器，因此挂载新编辑器之前务必先销毁现有编辑器。

完整网页示例

将文件保存为 index.html，填入密钥，并从密钥允许的来源通过 HTTP 提供该目录。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Kaleidr editor</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 0; }
    header { padding: 12px 16px; display: flex; gap: 8px; align-items: center; }
    #editor { height: calc(100vh - 56px); }
  </style>
</head>
<body>
  <header>
    <strong>Sketch on the map</strong>
    <button id="london">London</button>
    <button id="paris">Paris</button>
    <button id="reset">Start over</button>
    <span>Your work is not saved.</span>
  </header>

  <div id="editor"></div>

  <script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
  <script>
    const options = {
      product: 'editor',
      publishableKey: 'kld_pk_live_…',
      styleId: 'kaleidr-morning',
      center: [-0.1276, 51.5072],
      zoom: 11,
      theme: { brandColor: '#0b5fff', brandColorOn: '#ffffff' },
    };

    let handle = Kaleidr.mount('#editor', options);

    document.getElementById('london').addEventListener('click', () => {
      handle.setCamera({ center: [-0.1276, 51.5072], zoom: 11, duration: 1000 });
    });
    document.getElementById('paris').addEventListener('click', () => {
      handle.setCamera({ center: [2.3522, 48.8566], zoom: 11, duration: 1000 });
    });

    // One editor per page: destroy before mounting again.
    document.getElementById('reset').addEventListener('click', () => {
      handle.destroy();
      handle = Kaleidr.mount('#editor', options);
    });
  </script>
</body>
</html>

运行方式

项目	行为
运行位置	在网页文档中运行。地图画布和编辑器面板都是挂载容器内的元素。
会话	编辑器启动前，SDK 将密钥交换为短期会话，并在编辑器挂载期间持续续期。
编辑内容	仅保存在内存中；不会保存、导出、发布，也不会向网页报告修改。
底图	从 `https://tile.kaleidr.com` 加载；挂载时确定，之后不可改变。
主题	挂载时应用到整个文档，销毁时恢复。
相机	挂载时设置，之后通过 `handle.setCamera` 移动。
用量	编辑器会话请求不计入地图加载量；嵌入式编辑器没有消耗 AI 积分的功能。使用您的密钥发出的底图请求会按批次计入地图加载量：每小时每 20 次请求计为一次地图加载。请参阅地图加载量。
事件	不提供就绪事件、变更事件或错误回调。

提醒您的用户

编辑器本身不会提示工作内容只是临时保存。如果用户可能花时间编辑，请像上面的完整示例一样在网页界面中说明，以免他们误以为下次还可以找回地图。

检查是否正常运行

**网页中：**底图填满容器，Create 按钮可打开侧边栏，并能在地图上放置文字或标记。
**控制台中：**没有包含 [kaleidr 的报错行。
**网络面板中：**从 https://cdn.kaleidr.com 加载 kaleidr.js 和 editor.js；存在状态为 200 的 POST …/sdk/sessions 请求；从 https://tile.kaleidr.com 获取样式和地图瓦片。

故障排查

SDK 会在控制台以 [kaleidr:editor] … 形式记录挂载失败。会话被拒绝时，只会显示 HTTP 状态码；具体原因需在网络面板查看 sessions 请求的响应。403 的错误码位于 detail；429 的错误码位于 error，说明位于 detail。

现象	原因	解决方法
无内容显示。控制台：`[kaleidr:editor] [editor-embed] attach() requires an { apiKey }`	未提供密钥。	传入 `publishableKey`。
无内容显示，控制台提示 `…/sdk/sessions` 的 CORS 错误及 `[kaleidr:editor]` 获取错误。	密钥不存在或已撤销，或网页来源未获授权。	检查密钥，在 kaleidr.com/api-keys 添加包括协议、主机和端口的精确来源，等待几分钟生效。
控制台：`[kaleidr:editor] kaleidr session exchange failed (403)`	密钥不包含 `design` 权限（`insufficient_scope`），仅允许其他产品（`product_not_allowed`），或套餐不支持（`tier_capability_not_allowed`）。	在网络面板查看 `detail`，创建包含默认权限的密钥。
控制台：`[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser…`	使用了服务器密钥。	改用公开密钥。如果网页曾公开，轮换服务器密钥。
容器为空且无高度。	挂载容器没有高度。	设置高度；Safari 16.4 之前的版本还需 `display:block`。
面板显示但地图空白；`https://tile.kaleidr.com` 返回 429，包含 `"error":"tile_access_restricted"`。	底图服务拒绝了请求。	检查有效公开密钥和允许来源，修改密钥后等待几分钟再刷新；如持续失败请联系支持。 `[kaleidr:editor] …`
面板显示但地图空白，控制台报告 CSP 违规。	策略拦截底图、工作线程或图片。	添加 Content Security Policy 中的编辑器指令。
编辑器没有样式。	安全策略阻止内联样式。	在 `style-src` 中允许 `'unsafe-inline'`。
第二个编辑器异常，或者第一个停止工作。	同时挂载了两个编辑器。	先销毁旧编辑器。
`[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op.`	主题仅在挂载时读取。	挂载时传入 `theme`。
`[kaleidr] theme string must be JSON…`	`theme` 属性不是 JSON 对象。	属性外使用单引号，JSON 内容使用双引号。
某主题键未生效。	键名不在支持列表中或拼写错误，未知键会静默忽略。	对照键名列表。
编辑内容消失。	页面刷新、编辑器销毁或元素移动/移除。	这是预期行为；参阅顶部提示。

限制

嵌入式编辑器不会保存、导出或发布任何内容。
不提供变更回调、就绪事件或错误回调。
无法访问地图对象，因此不能添加自定义图层，也无法读取绘制内容。
不提供数据标签页、设计素材库、AI 面板、3D 模型库、分享或项目功能。工具栏包含 Text、Image、Marker、Popup、Background、Layer、Design 和 Legend；参阅功能范围。
每页只能有一个编辑器。
挂载后不能修改底图或主题。

后续步骤

编辑器参考文档：所有选项和主题键。
框架集成：在 React、Next.js 和 Vue 中挂载及销毁编辑器。
Content Security Policy：编辑器需要的安全策略指令。
嵌入已发布地图：用于需要永久保存的地图。

开始之前​

第 1 步：添加指定尺寸的容器并挂载编辑器​

第 2 步：选择底图和初始相机视角​

第 3 步：设置面板主题（可选）​

第 4 步：从网页控制相机移动（可选）​

第 5 步：销毁编辑器​

完整网页示例​

运行方式​

提醒您的用户​

检查是否正常运行​

故障排查​

限制​

后续步骤​