嵌入地圖編輯器

完成本指南後，您的網頁將顯示 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 步：銷毀編輯器​

完整網頁示例​

運行方式​

提醒您的用戶​

檢查是否正常運行​

故障排查​

限制​

後續步驟​