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)​

掛載後的元素屬性​

生命週期​

頁面中運行的內容​

控制台消息​

不支持的功能​

相關頁面​