跳至主要内容

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。