Editor 参考文档

product="editor" 会将 Kaleidr 的地图编辑工具挂载到您的页面。编辑器在挂载目标内部创建自己的地图，并将操作面板叠加在地图上。它直接在页面文档中运行，而不是在 iframe 中运行。

嵌入式编辑器仅将编辑结果保留在页面内存中。不能通过嵌入式编辑器保存、导出或发布内容，也没有变更回调。 刷新页面或调用 handle.destroy() 会丢弃所有修改。


密钥	可发布密钥 (`kld_pk_live_…`)，必填。
权限范围	`design`，新密钥默认具有。
套餐	所有套餐，包括 Free。
运行位置	您的页面中。
持久化	不支持。
实例数	每页一个。
CSP	参见 Content Security Policy 中的 Editor 部分。

分步指南见嵌入 Editor。

功能范围

包含	不包含
文本：放置在地图上的文字	数据标签页和数据集上传
图片：放置在地图上的图片	Studio 的示例地图与样式类型设计目录
标记	AI 面板
弹窗	3D 模型库
背景：地图后方的背景层	分享和发布
图层：底图标签、3D 建筑、光照和地形	项目：保存、打开和列出地图
设计：选择底图要素、类别或区域并重新设置样式	登录
图例：标签和图例设置

左列按顺序列出了编辑器的侧边工具栏。嵌入式编辑器中的设计是重新设置样式的工具，不包含 Studio 的设计目录。

挂载

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

<kaleidr-map product="editor" publishable-key="kld_pk_live_…"
             style-id="kaleidr-night" center="-0.1276,51.5072" zoom="12"
             style="display:block; height:640px"></kaleidr-map>

挂载目标必须具有高度。编辑器会占据目标全部宽度和高度。它会在目标中添加自己的元素，而不会删除已有元素，因此应使用空容器。

选项

挂载选项	属性	类型	默认值	必填	描述
`product`	`product`	`'editor'`	无	是	选择 Editor。
`publishableKey`	`publishable-key`	字符串	无	是	具有 `design` 权限的 `kld_pk_…` 密钥。浏览器会在发出请求前拒绝 `kld_sk_…` 服务器密钥。
`styleId`	`style-id`	字符串	组织的默认底图，否则为 `kaleidr-morning`	否	样式 ID（例如 `kaleidr-night`）或完整样式 URL。参见样式 ID。挂载时固定。
`center`	`center`	`[longitude, latitude]`；属性值为 `"longitude,latitude"`	`[0, 0]`	否	初始中心位置。
`zoom`	`zoom`	数字	`2`	否	初始缩放级别。不传 `center` 也能生效。
`pitch`	`pitch`	数字，单位为度	`0`	否	初始倾斜角度。
`bearing`	`bearing`	数字，单位为度	`0`	否	初始旋转角度。
`theme`	`theme`	对象或对象的 JSON 字符串	无	否	最多 17 个命名键。参见主题键。仅在挂载时读取。
`apiBase`	`api-base`	URL	`https://api.kaleidr.com/inference-api`	否	会话交换的目标地址。必须包含 `/inference-api` 路径。生产环境无需设置。
`tileBase`	`tile-base`	URL	`https://tile.kaleidr.com`	否	解析样式 ID 的服务器。生产环境无需设置。
`base`	`base`	URL	`https://cdn.kaleidr.com`	否	SDK 加载 `editor.js` 的来源。仅使用来源部分，而且只接受基础地址覆盖规则中允许的来源。
`enabled`	`flag`	布尔值	无	否	启用开关中针对本次挂载的控制项。

shareId、map、mapTarget、contained 和 viewerBase 不影响 Editor 挂载。不存在 styleUrl 选项；请通过 styleId 传入 URL。

底图

编辑器按以下顺序选择底图：

您传入的 styleId。
组织的默认底图（如果已设置）。
kaleidr-morning。

挂载后无法更换底图，Editor 也不支持 handle.setStyle。要更换底图，请销毁编辑器并重新挂载。这会丢弃所有修改。

相机

center 中经度在前。
每个值可以是数字或数字字符串。
如果某个挂载选项不是有限数值，该选项会被忽略，并使用默认值。控制台可能显示 [kaleidr:editor] ignored zoom: abc is not a finite value — using 2 instead.
如果元素的相机属性不是数字，则会静默丢弃并使用默认值。

主题键

theme 必须是对象，键名来自下表。每个值都是包含 CSS 值的字符串。不在列表中的键名或非空字符串以外的值都会被静默忽略：fontSizeBase: 14 无效，而 fontSizeBase: '14px' 有效。

键	样式作用	示例
`brandColor`	主按钮、焦点轮廓和当前工具。	`'#0b5fff'`
`brandColorHover`	`brandColor` 的悬停状态。	`'#0847c2'`
`brandColorOn`	显示在 `brandColor` 背景上的文字与图标。	`'#ffffff'`
`textColor`	正文和标题文字。	`'#111827'`
`textColorMuted`	说明文字等次要文本。	`'#6b7280'`
`surfaceColor`	卡片和对话框的填充颜色。	`'#ffffff'`
`borderColor`	边框与分隔线。	`'#e5e7eb'`
`glassBg`	半透明面板（侧栏及其弹出面板）的背景。传入不透明色可获得扁平效果。	`'rgba(255,255,255,0.8)'`
`glassBlur`	上述面板的 `backdrop-filter` 值。	`'blur(12px)'`
`cardRadius`	卡片及对话框的圆角半径。	`'12px'`
`buttonRadius`	按钮和标签的圆角半径。	`'8px'`
`listRadius`	列表行的圆角半径。	`'6px'`
`fontPrimary`	主要 `font-family`。	`'"Inter", system-ui, sans-serif'`
`fontMono`	等宽字体 `font-family`。	`'ui-monospace, monospace'`
`fontSizeBase`	基础字号。	`'14px'`
`sidebarRailWidth`	侧边工具栏宽度。	`'64px'`
`quickActionsWidth`	浮动快捷操作栏宽度。	`'320px'`

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

具体行为：

主题并不接受任意 CSS 自定义属性。像 '--my-color' 这样的键会被忽略。
编辑器挂载期间，主题值会应用到文档根元素，让弹出在任何位置的对话框都能使用它们。销毁编辑器时，会恢复之前的值。
主题仅在挂载时读取一次。Editor 不支持 handle.setTheme，在挂载后修改 theme 属性只会记录警告而没有效果。
如果 theme 是字符串，则必须是以 { 开头的 JSON。其他内容都会被忽略并显示控制台警告。

控制句柄

Kaleidr.mount 会同步返回句柄。所有产品的用法见句柄矩阵。

成员	在 Editor 中
`handle.product`	`'editor'`
`handle.setCamera(camera)`	移动编辑器的地图。
`handle.setTheme(theme)`	不支持。记录警告且不执行操作。
`handle.setStyle(style)`	不支持。记录警告且不执行操作。
`handle.destroy()`	移除编辑器及其地图、恢复主题值、停止会话续期，并丢弃编辑结果。

句柄没有 map 成员。您的页面无法访问编辑器内部的地图对象。

`setCamera(camera)`

handle.setCamera({ center: [2.3522, 48.8566], zoom: 12, duration: 1000 });

字段	类型	描述
`center`	`[number, number]`	经度、纬度。
`zoom`	数字	缩放级别。
`pitch`	数字	倾斜角度（度）。
`bearing`	数字	旋转角度（度）。
`duration`	数字	动画时长（毫秒）。省略或传入 `0` 则直接跳转。

编辑器仍在加载时发出的调用会进入队列，待编辑器启动后再执行。

挂载后的元素属性

在已挂载的 <kaleidr-map product="editor"> 上，修改 center、zoom、pitch 或 bearing 会立即移动地图且没有动画。修改 style-id、theme 或其他属性均无效。

生命周期

事件	结果
`Kaleidr.mount(...)` 或元素连接到文档	同时执行会话交换和加载 `editor.js`。两项操作完成后编辑器启动。
调用 `handle.destroy()` 或移除元素	编辑器及其修改全部消失。
将元素移动到其他父元素	先销毁再重新挂载。编辑内容丢失。
已存在一个编辑器时再挂载第二个	不支持。必须先销毁第一个。
页面重新加载	修改全部丢失。

页面中运行的内容

与 iframe 产品不同，Editor 会影响承载它的页面：

从 https://cdn.kaleidr.com 加载多兆字节大小的 editor.js 资源包。
通过 JavaScript 向文档添加样式表。
从 https://tile.kaleidr.com 请求底图的样式、瓦片、精灵图和字体。样式、精灵图和字体的请求通过查询参数 key 携带您的可发布密钥，用于让底图服务器识别页面；瓦片数据请求不携带密钥。会话令牌绝不会被放入 URL。
为地图启动来自 blob: URL 的 Web Worker。
挂载期间，在文档根元素设置主题值。

对应的 CSP 指令见 Content Security Policy。

控制台消息

消息	含义
`[kaleidr:editor] [editor-embed] attach() requires an { apiKey }`	未提供密钥。不渲染任何内容。
`[kaleidr:editor] kaleidr session exchange failed (<status>)`	会话交换遭到拒绝。原因位于 Network 标签页的响应中。403 的代码在 `detail` 中，例如密钥缺少 `design` 时的 `insufficient_scope`；429 的代码在 `error` 中。
对 `…/sdk/sessions` 的 CORS 错误，随后出现 `[kaleidr:editor]` fetch 错误	密钥未知或已撤销，或页面来源不在允许来源中。
`[kaleidr:editor] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. …`	传入了服务器密钥，没有发出请求。
`[kaleidr:editor] ignored <field>: <value> is not a finite value — using <default> instead.`	传给 `Kaleidr.mount` 的某个相机选项不是数字。元素属性不会产生该消息。
`[kaleidr:editor] <message>`	编辑器地图报告了错误，例如样式或瓦片加载失败。
`[kaleidr] theme string must be JSON …; named string themes are not supported. Ignored.`	`theme` 是非 JSON 对象字符串。
`[kaleidr] theme JSON parse failed (…); ignored.`	`theme` 包含格式错误的 JSON。
`[kaleidr] setTheme() is not supported on product "editor" — the call is a no-op. …`	调用了 `setTheme`，或挂载后修改了 `theme` 属性。
`[kaleidr] setStyle() is not supported on product "editor" — the call is a no-op. …`	调用了 `setStyle`。

不支持的功能

保存、导出或发布编辑结果。
变更事件、就绪事件或错误回调。
访问地图对象、自定义图层或读取用户绘制的内容。
挂载后切换底图或主题。
在同一页面挂载多个编辑器。

功能范围​

挂载​

选项​

底图​

相机​

主题键​

控制句柄​

setCamera(camera)​

挂载后的元素属性​

生命周期​

页面中运行的内容​

控制台消息​

不支持的功能​

相关页面​