Tile 參考

product="tile" 根據樣式 ID 顯示 Kaleidr 底圖。SDK 將可發佈密鑰交換為 Tile 工作階段，然後將掛載目標的內容替換為載入 https://map-embed.kaleidr.com/?style=<style> 的 iframe。地圖在該 iframe 內繪制。

Kaleidr 通過工作階段驗證密鑰、權限範圍及頁面來源，統計地圖載入次數，並提供組織的默認底圖。工作階段不會傳給 iframe。iframe URL 只包含樣式 ID 和指定的鏡頭參數（camera、pitch、bearing），不包含可發佈密鑰或工作階段令牌；iframe 內的地圖也不會使用它們發出要求。

密鑰	可發佈密鑰（kld_pk_live_…），必填。
權限範圍	maps，新密鑰默認具有此權限。
套餐	所有套餐，包括 Free。
渲染位置	來自 https://map-embed.kaleidr.com 的 iframe。
計量	每個 Tile 工作階段計一次地圖載入。
CSP	script-src https://cdn.kaleidr.com、connect-src https://api.kaleidr.com、frame-src https://map-embed.kaleidr.com。

分步教程請參閱使用 Kaleidr 底圖。

掛載

使用元素：

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             center="-0.1276,51.5072" zoom="11"
             style="display:block; height:480px"></kaleidr-map>

使用 JavaScript：

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

選項

掛載選項	屬性	類型	默認值	必需	說明
product	product	'tile'	無	是	選擇 Tile 產品。
publishableKey	publishable-key	字符串	無	是	kld_pk_… 密鑰，具有 maps 權限。服務器密鑰（kld_sk_…）在瀏覽器中會被拒絕，不會發送要求。
styleId	style-id	字符串	若已設置，則為組織默認底圖	建議提供	下表中的樣式 ID，或樣式文檔的完整 https:// URL。必須符合 ^[A-Za-z0-9._:/~-]{1,200}$。
center	center	[longitude, latitude]；屬性格式為 "longitude,latitude"	樣式默認視圖	否	初始中心點。
zoom	zoom	數字	樣式默認視圖	否	初始縮放級別；掛載時若沒有 center 則忽略。
pitch	pitch	數字，單位為度	樣式默認視圖	否	初始傾斜角。
bearing	bearing	數字，單位為度	樣式默認視圖	否	初始旋轉角。
apiBase	api-base	URL	https://api.kaleidr.com/inference-api	否	工作階段交換要求的目標地址。必須包含 /inference-api 路徑，生產環境通常無需設置。
viewerBase	viewer-base	URL	https://map-embed.kaleidr.com	否	iframe 的載入來源；僅使用來源部分。它是地圖頁面的主機，而非地圖資料主機。
base	base	URL	https://cdn.kaleidr.com	否	SDK 載入 tile.js 的來源。僅使用來源，且只接受基礎地址覆蓋規則允許的來源。
enabled	flag	布爾值	無	否	每次掛載的啓用開關。

shareId、theme、map、mapTarget、contained 和 tileBase 對 Tile 掛載無效。

樣式 ID

style-id	外觀
kaleidr-morning	明亮：白色地面、青色水域、白色道路。
kaleidr-afternoon	中等色調地面、綠色植被和灰色道路。
kaleidr-evening	黃金時刻：溫暖的沙色與橄欖色。
kaleidr-night	深海軍藍和炭黑色，配以琥珀色高速公路。
kaleidr-plain	白色畫布，顯示邊界和地點標籤。縮放級別達到 15 後顯示 3D 建築。
kaleidr-editorial	無標籤的午後配色，適合小型或裝飾性地圖。

規則：

• ID 必須完全匹配且區分大小寫，沒有簡寫別名。
• 若省略 styleId，嵌入內容使用通過工作階段返回的組織默認底圖。若未設置默認底圖，iframe 顯示“Couldn't find a map id in the URL.”。建議顯式設置 styleId，避免依賴賬戶配置。
• 顯式傳入的 styleId 始終優先於組織默認設置。
• 不存在的 ID 會導致 iframe 空白，併發送kaleidr-embed:error 消息，錯誤程式碼為 maplibre_error。
• 值中包含不允許的字符時不會掛載。控制台顯示 [kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.。因此樣式 URL 不能包含查詢字符串。

鏡頭

初始鏡頭以樣式默認視圖為基礎，傳入的每個字段分別覆蓋樣式中的對應值。若樣式沒有默認視圖，則顯示整個世界：中心點 [0, 20]、縮放級別 2、無傾斜、無旋轉。

• center 的經度在前：[-0.1276, 51.5072] 表示倫敦。
• 掛載時，僅在提供 zoom 時同時包含 center 才會生效。
• pitch 和 bearing 不依賴 center。

尺寸

• iframe 寬度為掛載目標的 100%，無邊框且帶圓角。
• 若掛載時目標已有高度，iframe 高度為其 100%；否則固定為 500 像素。
• 掛載過程會替換目標的子元素，並設置 position:relative（目標沒有內聯定位時）及 overflow:hidden。
• <kaleidr-map> 默認使用 display:block，因此可以設置 height。請明確指定高度。示例仍寫有 display:block，以兼容 Safari 16.4 之前無法自動採用塊級佈局的情況。

句柄

Kaleidr.mount 同步返回句柄。所有產品的情況請查看句柄矩陣。

成員	Tile 中的行為
handle.product	'tile'
handle.setCamera(camera)	移動地圖鏡頭。
handle.setStyle(style)	原地切換底圖。
handle.setTheme(theme)	不支持；記錄警告且不執行操作。
handle.destroy()	移除 iframe 並停止續期工作階段。

setStyle(style)

handle.setStyle('kaleidr-night');

接受樣式 ID 或完整的樣式 URL，解析方式與掛載時的 styleId 相同。iframe 不重新載入，鏡頭位置保持不變，也不會新增地圖載入計數。只有 Tile 支持 setStyle。

setCamera(camera)

handle.setCamera({
  center: [2.3522, 48.8566], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
  duration: 1200,            // milliseconds
});

字段	類型	說明
center	[number, number]	經度、緯度。
zoom	數字	縮放級別。與掛載時不同，這裡 zoom 不需要同時提供 center。
pitch	數字	傾斜角，單位為度。
bearing	數字	旋轉角，單位為度。
duration	數字	動畫時長，單位為毫秒。省略或設為 0 時立即跳轉。

所有字段均可選；未提供的字段保留當前值。

調用時機

你隨時都可以調用 setCamera 和 setStyle，只要 Kaleidr.mount 已返回，甚至可以緊接著在下一行調用。地圖尚未就緒時的調用會按順序暫存，並在 iframe 內地圖報告就緒後執行。最多保留最近 256 次調用。若在有限等待時間內仍未收到就緒報告（通常是 iframe 載入後 10 秒），暫存調用仍會發出，同時出現一條控制台警告。不必先等待 kaleidr-embed:ready。若要指定地圖打開時的視圖和樣式，直接使用掛載選項效果更好，可避免載入後再次切換。

掛載後的元素屬性

對於已掛載的 <kaleidr-map product="tile">，更改 center、zoom、pitch 或 bearing 會無動畫地移動地圖。更改 style-id、publishable-key 或任何其他屬性均無效果。

iframe 消息

// The basemap drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'tile' }

// Something failed to draw.
{ type: 'kaleidr-embed:error', id: string, code: 'maplibre_error', message: string }

// No style: none was passed, and the organization has no default basemap.
{ type: 'kaleidr-embed:error', id: null, code: 'no_id', message: string }

id 是傳入的樣式 ID 或 URL。若為 no_id，其值為 null，iframe 顯示“Couldn't find a map id in the URL.”，且不會發送 ready。

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  if (event.source !== target.querySelector('iframe')?.contentWindow) return;
  const msg = event.data;
  if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
  if (msg?.type === 'kaleidr-embed:error') onError(msg);
});

• 地圖繪制完成後只發送一次 ready；執行 setStyle 後不會再次發送。
• maplibre_error 可能在 ready 之前或之後多次出現。
• iframe 使用 loading="lazy"，因此只有接近可視區域後才會載入併發送消息。
• 工作階段被拒絕時不會創建 iframe，所以也不會發送消息；請查看控制台錯誤。
• iframe 還會發送 type 以 kaleidr-embed: 開頭的其他消息。SDK 利用這些消息將 Chat 連接到地圖，但它們不屬於公開契約。

工作階段與計量

每次 Tile 掛載時，SDK 會發送

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
x-api-key: kld_pk_live_…
content-type: application/json

{"product":"tile"}

並接收

{
  "session_token": "kld_sess_live_…",
  "expires_in": 900,
  "product": "tile",
  "basemap_style_id": "kaleidr-morning"
}

basemap_style_id 表示組織默認底圖；如果未設置，則為 null。

每次成功交換 "product":"tile" 會為組織統計一次地圖載入。交換發生在以下時機：

時機	計數
首次掛載	1
只要持續掛載，工作階段到期前 90 秒	每次 1
標籤頁重新可見，且工作階段已經到期或將在 90 秒內到期	1
調用 destroy() 後重新掛載，或重新插入被移除的元素	1

注意：

• 續期失敗後每 30 秒重試一次；已經顯示的地圖不會被移除。
• 首次交換失敗則掛載失敗，不會自動重試。需要重新掛載。
• destroy() 會停止工作階段續期。
• 鏡頭移動、切換樣式和訪問者交互均不計入地圖載入。

Tile 工作階段交換會因為下列第一項適用原因而被拒絕：

狀態	detail	原因
403	publishable_key_required	密鑰不是可發佈密鑰。
403	origin_required	要求未攜帶來源。
403	origin_not_allowed	頁面來源不在密鑰允許的來源列表中。
403	product_not_allowed	密鑰僅允許其他產品。
403	tier_capability_not_allowed	當前套餐不允許此產品。
403	insufficient_scope	密鑰缺少 maps 權限。
429	map_load_quota_exceeded	組織的地圖載入配額已用盡。

在上述檢查之前，若平台關閉了工作階段交換，會返回 404 sessions_disabled；若平台出現故障，可能返回 503 sessions_not_configured。兩者均不是密鑰造成的。全部錯誤程式碼見錯誤參考。

與 Chat 配合使用

Chat 掛載可以控制 Tile 元素。給 Tile 元素分配一個 id，並將 Chat 的 map-target 屬性（掛載選項 mapTarget）指向它：

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               style="display:block; height:560px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

在 Tile 地圖中，助手可添加帶彈窗的圖釘、將鏡頭調整到地點範圍，並繪制路線、城市等區域的輪廓以及實時車輛位置。操作指南請參閱使用 Kaleidr 底圖，佈局見主題與佈局，Chat 選項見Chat 參考。

控制台消息

消息	含義
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	元素缺少有效的 product，不會掛載。
[kaleidr:tile] kaleidr session exchange failed (<status>)	工作階段交換遭拒。原因在網絡面板的響應中：403 時查看 detail，map_load_quota_exceeded 也在其中；429 時查看 error，例如 rate_limited。
…/sdk/sessions 出現 CORS 錯誤，隨後出現 [kaleidr:tile] 要求錯誤	密鑰未知或已撤銷，或來源不被允許。來源遭拒時，響應不包含 CORS 頭，瀏覽器會向 SDK 隱藏響應。
[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. Use your publishable key (kld_pk_…) here and keep the server key server-side.	傳入了服務器密鑰；不會發送要求。
[kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.	styleId 包含非法字符。
[kaleidr:tile] mount target not found: <selector>	Kaleidr.mount 沒有找到匹配選擇器的元素。
[kaleidr:tile] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/tile.js	無法載入 Tile 腳本包。
[kaleidr] setTheme() is not supported on product "tile" — the call is a no-op. …	調用了 Tile 不支持的句柄方法。
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …	瀏覽器緩存了舊版 tile.js。請繞過緩存重新載入。

不支持的功能

• 向地圖添加自己的標記、圖層或彈窗。
• 點擊、鏡頭移動或選擇事件。
• 讀取當前鏡頭參數。
• 不使用 iframe 直接運行地圖。

相關文檔

• 使用 Kaleidr 底圖
• <kaleidr-map> 元素
• 載入器 kaleidr.js
• 配額與速率限制