<kaleidr-map> — 元素
宣告式 façade。放置元素並設定屬性；它會在 連接時掛載，並在移除時卸載。
<kaleidr-map product="viewer" share-id="abcd1234" style="height:480px"></kaleidr-map>
屬性表
已根據 kaleidr-sdk/packages/embed/src/element.ts 驗證。屬性名稱
採用 kebab-case；kaleidr.js 中對應的 Kaleidr.mount(...) 選項名稱
採用 camelCase。
| 屬性 | 產品 | 必填 | 預設值 | 含義 |
|---|---|---|---|---|
product | 全部 | 是 | — | chat | viewer | editor | tile |
publishable-key | chat, editor, tile | 是* | — | kld_pk_live_…；運行時交換為 session token |
api-key | chat, editor, tile | — | — | 已棄用別名；也接受舊版 kld_live_… |
share-id | viewer | 是 | — | 已發布地圖 / share id；省略時會在 bundle 載入時拋出錯誤 |
map-id | viewer | — | — | share-id 的別名 |
style-id | tile, editor | 選用 | tile：viewer 預設值；editor：組織預設值 → kaleidr-morning | 底圖 style id，或（editor）完整 style URL |
map-target | chat | 選用 | — | host map element 的 CSS selector |
contained | chat | 選用 | false | 將面板固定在 mount element 內，而不是浮動在 document.body 上 |
center | viewer, tile, editor | 選用 | — | lon,lat |
zoom | viewer, tile, editor | 選用 | editor: 2 | 初始 zoom |
pitch | viewer, tile, editor | 選用 | 0 | 初始 pitch |
bearing | viewer, tile, editor | 選用 | 0 | 初始 bearing |
theme | chat, editor | 選用 | — | JSON CSS-token object string |
doorway | 全部 | 選用 | 產品預設值 | iframe | attach 覆蓋 |
base | 全部 | 選用 | https://cdn.kaleidr.com | 用於延遲載入 bundle（/embed/v1/*.js）的 CDN origin |
viewer-base | viewer, tile | 選用 | https://map-embed.kaleidr.com | iframe 載入的 origin — 與 bundle CDN 不同 |
api-base | chat, editor, tile | 選用 | https://api.kaleidr.com/inference-api | 必須包含 /inference-api。 像 https://api.kaleidr.com 這樣的 bare origin 會在工作階段交換時傳回 404。適用於所有執行工作階段交換的產品（chat、editor、tile）。 |
tile-base | editor | 選用 | https://tile.kaleidr.com | 用於解析目錄中 style-id 值的 Tile CDN |
flag | 全部 | 選用 | — | 每個元素的 dormancy 覆蓋設定 |
* 授權/計費使用時必填。Viewer 不需要金鑰；向 Viewer embed
傳入金鑰會以 product_not_allowed 拒絕。
請為元素設定高度（內嵌 style 或 CSS）。每個產品都會填滿其
容器；位於未設定尺寸容器中的 iframe 產品會回退為
固定 500px 高度，以保持可見。
Handle matrix
行為與 /embed/v1/ 目前發布版本一致。不支援的組合不會拋出錯誤 —
SDK 會記錄 [kaleidr] 警告並傳回。這是 v1 主版本別名的 contract；
移除可呼叫的方法會構成破壞性行為變更。
| 方法 | chat | viewer | editor | tile |
|---|---|---|---|---|
destroy() | 是 | 是 | 是 | 是 |
setCamera(camera) | no-op | 是 | 是 | 是 |
setTheme(theme) | 是（即時） | n/a | 僅掛載時 | n/a |
setStyle(styleId) | n/a | n/a | n/a | 僅在 tile 中公開 |
Chat 不會控制地圖相機 — 在 Kaleidr.mount(...) 之後請使用
您自己的地圖實例的相機 API。Editor 的即時 setTheme 將在後續 SDK
版本中提供；掛載時的 theme 已經可用。
即時更新
center、zoom、pitch 與 bearing 會被監聽，並在不重新掛載的情況下重新調整 viewer、
editor 與 tile 的視野。theme 變更會 即時更新 chat；
editor theme 仍然僅在掛載時套用。
Chat + map-target
Chat 連接至您的即時地圖，而字串屬性無法攜帶 map instance。可以透過以下兩種 方式提供：
- Imperative（建議）：
Kaleidr.mount(el, { product: 'chat', publishableKey, map, contained: true }). - Declarative： 將 map instance 儲存在 host element 上：
hostEl.__kaleidrMap__ = map，然後設定map-target="#host"。
沒有地圖時，chat 會以 headless 模式運行（無地圖互動）。