`<kaleidr-map>` 元素

<kaleidr-map> 是聲明式掛載 Kaleidr 產品的方式。你在 HTML 中寫入帶屬性的元素，它進入文檔時自動掛載，離開文檔時自動清理。該元素由 kaleidr.js 定義，因此頁面必須載入此腳本。

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

這個元素是一個輕量封裝：將自身屬性轉換為選項，並在自身上調用 Kaleidr.mount。元素能做到的事情都能通過 Kaleidr.mount 完成，反過來卻不一定：元素無法接收實時地圖對象，也不會暴露句柄。

適合使用元素的情況	適合使用 `Kaleidr.mount` 的情況
嵌入內容是靜態 HTML。	需要通過句柄調用 `setCamera`、`setStyle`、`setTheme` 或 `destroy`。
CMS 或模板負責生成 HTML。	要把 Chat 連接到自己的地圖，需要傳入 `map` 選項。
希望從文檔移除元素時自動清理。	由框架控制組件的掛載與卸載時機。

屬性

屬性名稱使用 kebab-case，對應的掛載選項使用 camelCase。

屬性	掛載選項	產品	必需	默認值	掛載後監聽	說明
`product`	`product`	全部	是	無	否	`chat`、`viewer`、`editor` 或 `tile`。
`publishable-key`	`publishableKey`	chat、editor、tile	是，除非 Chat 使用已發佈地圖	無	否	你的 `kld_pk_…` 金鑰。Viewer 不使用。
`share-id`	`shareId`	viewer、chat	Viewer：是	無	否	Viewer：已發佈地圖 ID。無金鑰的 Chat：提供聊天功能的已發佈地圖。
`map-id`	`mapId`	viewer	否	無	否	`share-id` 的別名。
`style-id`	`styleId`	tile、editor	Tile 建議設置	組織默認底圖；Editor 之後退回 `kaleidr-morning`	否	底圖樣式 ID 或樣式 URL。
`map-target`	`mapTarget`	chat	否	無	否	CSS 選擇器，指向助手要控制的 Viewer 或 Tile `<kaleidr-map>` 元素。
`contained`	`contained`	chat	否	關閉	否	將面板停靠在此元素內部，該元素需設置定位和尺寸。
`lang`	`lang`	chat	否	若 `<html lang>` 是格式正確的語言標記，則使用它，否則為英語	否	面板回答所用語言，使用 BCP 47 標記，如 `en`、`ko` 或 `pt-BR`。參閱Chat 語言。
`chat-title`	`title`	chat	否	面板自身標題	否	聊天窗口標題。屬性是 `chat-title` 而不是 `title`；HTML 元素的 `title` 是懸停提示。
`placeholder`	`placeholder`	chat	否	面板自身的佔位文字	否	輸入框的佔位提示。
`layout`	`layout`	viewer	否	`map`	否	`bar` 掛載聊天列；聊天列也會讀取 `chat-title`、`placeholder`、`theme` 和 `lang`，但有自己的預設值，參閱 Viewer 選項。`locator` 和 `listings` 在地點資料庫集合的清單旁顯示地圖，參閱地點版面。`guide` 在場所地圖旁開啟聊天，參閱導覽版面。`live` 顯示車輛和今天的站點，參閱即時版面。
`collection`	`collection`	viewer 門市查詢、物件清單、導覽和即時	否	地圖繪製的第一個與版面類型相符的集合	否	要列出的集合 ID；在 `live` 上為車輛集合的 ID。
`stops`	`stops`	viewer 即時	否	地圖繪製的第一個站點集合	否	站點集合的 ID。
`filters`	`filters`	viewer 門市查詢和物件清單	否	集合的所有篩選	否	要顯示的訪客篩選，以 `\|` 分隔：`search`、`category`、`price`、`beds`、`baths`、`open_now`。
`card`	`card`	viewer	否	`auto`	否	`compact` 地點卡片只顯示標題、副標題和動作。
`prompt`	`prompt`	viewer	否	無	否	地圖打開時要向地圖的 Kaleidr AI 提出的問題；在聊天列上則是輸入框的預填文字。
`prompt-param`	`promptParam`	viewer	否	無	否	當訪客來自同一來源的頁面時，從頁面 URL 的該查詢參數讀取 `prompt`。
`prompts`	`prompts`	viewer 聊天列	否	無	否	示例問題，以 `\|` 分隔。
`accent`	`accent`	viewer 聊天列	否	`#2da84a`	否	CSS 顏色。
`results-url`	`resultsUrl`	viewer 聊天列	否	無	否	將訪客帶往該頁面，並附加 `?q=<question>`。
`center`	`center`	viewer、tile、editor	否	產品默認值	是	`"longitude,latitude"`，例如 `"-0.1276,51.5072"`。
`zoom`	`zoom`	viewer、tile、editor	否	產品默認值	是	數字。Viewer 和 Tile 掛載時僅在同時提供 `center` 時才使用。
`pitch`	`pitch`	viewer、tile、editor	否	產品默認值	是	傾斜角，單位為度。
`bearing`	`bearing`	viewer、tile、editor	否	產品默認值	是	旋轉角，單位為度。
`theme`	`theme`	chat、editor	否	無	是（僅 Chat 會應用）	JSON 對象字符串。Chat 使用 CSS 自定義屬性；Editor 使用17 個主題字段。
`flag`	`enabled`	全部	否	無	否	每個元素的啓用開關。
`base`	`base`	全部	否	`https://cdn.kaleidr.com`	否	產品腳本包來源。僅允許 Kaleidr CDN（`https://cdn.kaleidr.com`）、載入 `kaleidr.js` 時的來源或頁面本身的來源，其他值將被忽略並記錄警告。參閱基礎地址覆蓋規則。
`viewer-base`	`viewerBase`	viewer、tile	否	`https://map-embed.kaleidr.com`	否	iframe 載入來源。
`api-base`	`apiBase`	chat、editor、tile	否	`https://api.kaleidr.com/inference-api`	否	工作階段交換和產品要求的目標地址。必須包含 `/inference-api`。
`tile-base`	`tileBase`	editor	否	`https://tile.kaleidr.com`	否	樣式 ID 的解析主機。

api-key 是 publishable-key 的已棄用別名。四種 …-base 屬性僅用於測試其他部署，生產環境不需要。

布爾屬性

flag 和 contained 會被解析為布爾值：

寫法	解釋結果
`contained`（不帶值）、`contained=""`	true
`"true"`、`"1"`、`"yes"`、`"on"`	true
`"false"`、`"0"`、`"no"`、`"off"`	false
不存在該屬性	未設置
其他任何值	忽略並在控制台警告

解析時不區分大小寫，也忽略詞語前後的空格，所以 flag="False" 仍會關閉元素。由於空值屬性表示真值，模板輸出 flag="" 會將元素啓用。請顯式輸出 false。

數字及鏡頭屬性

zoom、pitch 和 bearing 按數字解析。center 是兩個以逗號分隔的數字，經度在前。解析失敗的值會被靜默忽略，並使用產品默認值。

掛載後的屬性

元素會在進入文檔時讀取一次屬性。之後僅監聽五個屬性：

更改的屬性	viewer	tile	editor	chat
`center`、`zoom`、`pitch`、`bearing`	地圖立即跳轉到新鏡頭位置。	地圖立即跳轉到新鏡頭位置。	地圖立即跳轉到新鏡頭位置。	控制台警告，不執行操作。
`theme`	控制台警告。	控制台警告。	控制台警告，Editor 只在掛載時讀取主題。	更新面板樣式。
任何其他屬性	無效果。	無效果。	無效果。	無效果。

通過屬性更改鏡頭永遠不會產生動畫。需要動畫時，請通過 Kaleidr.mount 掛載並調用 handle.setCamera({ …, duration: 800 })。

修改其中一個鏡頭屬性時，元素會發送它當前擁有的所有鏡頭屬性。若只修改 zoom，而元素還設置了 center，該中心點也會重新應用。

若要更改 share-id、style-id、publishable-key、product、flag、contained、lang、chat-title 或 placeholder，應替換元素：移除後用新的屬性重新插入。Tile 可調用 handle.setStyle 在原位切換樣式，但僅適用於通過 Kaleidr.mount 掛載的地圖。

// Show a different published map in the same place.
const old = document.querySelector('kaleidr-map');
const next = old.cloneNode(false);
next.setAttribute('share-id', 'ANOTHER_MAP_ID');
old.replaceWith(next);

生命週期

事件	元素的行為
進入文檔	讀取屬性並掛載。Chat、Editor 和 Tile 會開始交換工作階段。
在 `kaleidr.js` 載入前已位於文檔中	先不操作，腳本載入後才掛載。
離開文檔	銷毀掛載，清理自身添加的內容並停止工作階段續期。
重新進入文檔	重新讀取屬性、掛載，並開啓新的工作階段交換。
被移動到另一父元素下	先離開再進入：先銷毀再掛載。
缺少 `product` 或值不是四種產品之一	記錄 `[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"` 且不掛載。之後設置 `product` 不會產生效果。

由此產生以下注意事項：

插入元素之前先設置屬性。 如果通過 JavaScript 創建元素，請先設置全部屬性，再將其添加到文檔。先插入的話，會使用當時已有的屬性立即掛載。

const el = document.createElement('kaleidr-map');
el.setAttribute('product', 'tile');
el.setAttribute('publishable-key', 'kld_pk_live_…');
el.setAttribute('style-id', 'kaleidr-night');
el.style.cssText = 'display:block; height:480px';
document.getElementById('slot').appendChild(el); // mounts here

重新掛載不是免費的。 Tile 再掛載會多計一次地圖載入，Editor 會丟失編輯結果，Chat 會開啓新對話。框架中的列表重新渲染等代碼可能重建或重排 DOM 節點，悄然觸發這些行為。參閱框架集成。
隱藏的元素仍會掛載。 display:none 不會延遲掛載，關閉的標籤面板中的 Tile 仍會啓動工作階段。
元素會顯示其子內容，直到地圖替換它們。 元素內部的內容會顯示；Viewer 和 Tile 載入後會以 iframe 替換這些內容，因此子內容可以充當載入佔位符，掛載失敗或被啓用開關阻止時仍作為備用顯示。Chat 和 Editor 不會移除子內容。若不需要，請保持元素為空。

尺寸

<kaleidr-map> 默認是 display:block，因此能夠設置 height：

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="height:480px"></kaleidr-map>

關於此默認值的三個要點：

你的 display 設置始終優先。 內聯樣式、樣式表規則及 hidden 屬性都會覆蓋默認值。如果 CSS 將元素設為 display:inline，height 就不再起作用。
無需放寬 Content Security Policy。 默認行為不是通過 <style> 標籤或 style 屬性提供的，因此即使沒有 'unsafe-inline' 也能正常工作。
Safari 16.4 之前不支持此默認行為。 元素保持內聯，並忽略 width 和 height。所以示例會保留 display:block，並將其寫在 style 屬性中：在支持默認值的瀏覽器中無害，在舊版 Safari 中則是設置尺寸所必需的。

因此，本文檔使用以下寫法：

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="display:block; height:480px"></kaleidr-map>

或者在整個網站的樣式表中統一設置：

kaleidr-map { display: block; height: 480px; }

產品	尺寸行為
viewer、tile	iframe 寬度佔元素的 100%。若掛載時元素已有高度，iframe 高度佔其 100%；否則固定為 500 像素。掛載時會設置 `position:relative`（若沒有內聯定位）和 `overflow:hidden`。
editor	編輯器佔元素寬高的 100%；沒有高度時不可見。
chat	沒有 `contained` 時，面板是視口左上角的固定窗口，元素大小無關緊要。有 `contained` 時，面板位於元素內部，元素需有 `position:relative`（或其他定位方式）及尺寸。

500 像素的備用高度只在掛載時決定一次。若當時元素沒有高度，即使之後設置尺寸，iframe 仍保持 500 像素高。

如果 Content Security Policy 禁止內聯 style 屬性，請在樣式表中設置尺寸。元素自身的塊級默認行為不受該策略影響。

句柄矩陣

該元素不會暴露句柄。若要調用這些方法，請使用能返回句柄的 Kaleidr.mount 進行掛載。

方法	chat	viewer	editor	tile
`destroy()`	是	是	是	是
`setCamera(camera)`	不支持	是	是	是
`setTheme(theme)`	是	不支持	不支持	不支持
`setStyle(style)`	不支持	不支持	不支持	是
`send(text)`	不支持	是	不支持	不支持
`setFilters(filters)`	不支持	是	不支持	不支持
`showVehiclesLayer(layer)`	不支持	是	不支持	不支持
`clearVehiclesLayer()`	不支持	是	不支持	不支持

每個句柄都包含所有這些方法。標記為“不支持”的方法在調用時不會執行操作，只會記錄控制台警告，不會拋出異常。這屬於 /embed/v1 契約的一部分。

各產品的情況：

chat：setTheme 更改面板外觀。setCamera 不支持，因為 Chat 不擁有地圖；助手在回答時會移動其連接的地圖，而你自己的代碼應使用地圖庫 API 來移動它。
viewer：setCamera 移動已發佈地圖。setFilters 設定地點版面的訪客篩選。showVehiclesLayer 在地圖上繪製你自己的車輛，clearVehiclesLayer 將其移除，參閱車輛圖層。
editor：setCamera 移動編輯器的地圖。主題和底圖在掛載時確定。
tile：setCamera 移動地圖，setStyle 直接切換底圖。

setCamera 接收 { center, zoom, pitch, bearing, duration }。所有字段均為可選，center 是 [longitude, latitude]，duration 單位為毫秒。完整說明見 kaleidr.js。

Chat 與 `map-target`

Chat 可以控制兩種地圖：

你自己的地圖（Mapbox GL JS、MapLibre GL JS、Google Maps 或 Leaflet）。無法在屬性中直接寫入地圖對象，因此應使用 Kaleidr.mount，並傳入 map 選項。參閱Chat 參考。

同一頁面上的 Kaleidr Viewer 或 Tile 元素。 使用 CSS 選擇器讓 map-target 指向它：

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               style="display:block; height:480px"></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>

兩個元素的順序無關緊要。Chat 會在實際需要時查找目標。

沒有 map 或 map-target 時，Chat 是不帶地圖的聊天面板。

容器和 Chat 元素的樣式將面板放置在地圖之上。各項聲明見主題與佈局。已發佈地圖上的 Chat 見已發佈地圖上的 Chat。

控制台消息

消息	含義
`[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	`product` 缺失或拼寫錯誤，元素不會掛載。
`[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. Use <attribute>="true" / "false" (or omit it).`	`flag` 或 `contained` 的值不在允許範圍內。消息會指出是哪個屬性：`flag="…"` 或 `contained="…"`。
`[kaleidr] base "<value>" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.`	`base` 指定了不被接受的來源。產品仍從默認 CDN 載入。
[kaleidr] embed is disabled — this mount passed `enabled: false` (or `flag="false"`). …	元素被其 `flag` 阻止掛載。移除此限制並替換元素。
`[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. …`	Chat 元素的鏡頭屬性發生變化。
`[kaleidr] setTheme() is not supported on product "<product>" — the call is a no-op. …`	Viewer、Tile 或 Editor 元素的 `theme` 屬性發生變化。

掛載失敗時，控制台消息格式為 [kaleidr:<product>] …。完整說明見 kaleidr.js。

不支持的功能

事件：元素不會派發 DOM 事件。
屬性或方法：元素沒有 setCamera 方法、handle 屬性或 ready Promise。
重新讀取屬性：除了五個受監聽屬性，掛載後的變化都會被忽略。

屬性​

布爾屬性​

數字及鏡頭屬性​

掛載後的屬性​

生命週期​

尺寸​

句柄矩陣​

Chat 與 map-target​

控制台消息​

不支持的功能​

相關文檔​

屬性