Viewer 參考
product="viewer" 顯示在 Kaleidr Studio 中發佈的地圖。SDK 將掛載目標內容替換為載入 https://map-embed.kaleidr.com/embed/<id> 的 iframe。地圖在該 iframe 內繪制。
| 金鑰 | 不需要。請勿傳入金鑰。 |
| 套餐 | 所有套餐，包括 Free。 |
| 渲染位置 | 來自 https://map-embed.kaleidr.com 的 iframe。 |
| 計量 | 每次查看計一次地圖載入，由地圖所有者的組織承擔。 |
| CSP | script-src https://cdn.kaleidr.com 和 frame-src https://map-embed.kaleidr.com。 |
分步教程請參閱嵌入已發佈地圖。
掛載
使用元素：
<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>
使用 JavaScript：
const handle = Kaleidr.mount('#map', {
product: 'viewer',
shareId: 'YOUR_MAP_ID',
});
完全不使用 SDK：
<iframe src="https://map-embed.kaleidr.com/embed/YOUR_MAP_ID"
width="100%" height="480" style="border:0;" loading="lazy"
referrerpolicy="no-referrer-when-downgrade" allow="geolocation; microphone; fullscreen; clipboard-write"
title="Kaleidr map"></iframe>
聊天列
layout="bar" 將 Viewer 變為聊天列：在你的頁面上只顯示一個提問輸入框，訪客提問之前不載入地圖。提問後會打開已發佈地圖，由地圖的 Kaleidr AI 在其中回答。
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="bar"
chat-title="Ask about the neighborhood"
prompts="Coffee within a short walk|Parks nearby"></kaleidr-map>
回答會在以下兩處之一打開：
| 設置 | 提問後的行為 |
|---|---|
不設置 results-url（默認） | 地圖在頁面上方打開並佔滿窗口，然後提出問題。訪客可以通過關閉按鈕將其關閉。之後的提問仍發給同一張地圖，因此對話會繼續。 |
results-url="/map" | 瀏覽器跳轉到該頁面並附加 ?q=<question>。該頁面上設置了 prompt-param="q" 的 Viewer 會在地圖打開時提出問題，前提是訪客來自同一來源的頁面。 |
結果頁面：
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" prompt-param="q"
style="display:block; height:600px"></kaleidr-map>
- 由地圖回答。 問題會發送到地圖自身的 Ask Kaleidr 面板，因此地圖需要開啓 Control Tower（Studio，Kaleidr AI），並適用已發佈地圖上的 Kaleidr AI 的規則：由地圖所有者付費，地圖允許的網域決定它在哪些網站回答。對於未開啓 Control Tower 的地圖，地圖會打開，但不會提出問題。
- 聊天列本身不載入地圖。 訪客提問時地圖才會載入，並計為一次地圖載入。
- 聊天列在自己的 shadow root 中繪制， 因此頁面的 CSS 不會改變其樣式，其樣式也不需要
style-src權限。寬度與元素相同，高度隨內容而定。 - 其自身標籤跟隨
lang， 未設置lang時則跟隨訪客的瀏覽器語言：英語、西班牙語、法語、德語、葡萄牙語、日語、韓語、簡體和繁體中文，以及阿拉伯語。你設置的chat-title、placeholder和prompts按原文顯示。 prompt預填輸入框，handle.send()從代碼提問。handle.send('Parks nearby')提出該問題；handle.send()提出輸入框中的內容。
template.kaleidr.com 上的生成器可以為你選擇的地圖生成這兩段代碼。
地點版面
layout="locator" 和 layout="listings" 在已發佈地圖旁顯示該地圖所繪製的地點資料庫集合清單，並附上集合的篩選和卡片。
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="locator"
filters="search|category|open_now"
style="display:block; height:600px"></kaleidr-map>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="listings"
filters="price|beds|baths"
style="display:block; height:720px"></kaleidr-map>
| 版面 | 清單 | 圖釘 |
|---|---|---|
locator | 依距離排序的地點，附有搜尋欄、我附近按鈕 、篩選和數量。若搜尋未符合清單中的任何地點，地圖會移到所搜尋的地點。 | 集合圖層，使用在 Studio 中設定的樣式。 |
listings | 照片卡片，在較寬的框架中分兩欄顯示，依距離、價格由低到高或價格由高到低排序。 | 價格標籤。 |
- 框架寬度達 768 像素以上時，清單位於地圖旁； 更窄時，清單位於地圖上方的面板中，由訪客向上拖曳。
- 清單與地圖保持同步。 在清單中選擇地點會將地圖移到該地點並開啟其卡片；選擇圖釘會將清單捲動到該地點。清單、圖釘和數量始終顯示相同的地點。
- 清單一次顯示 50 個地點， 可透過顯示更多繼續顯示。
- 「我附近」會向訪客要求位置。 SDK 建立的 iframe 允許此操作；直接使用的 iframe 需要
allow="geolocation"。 - 在不繪製任何集合的地圖上，兩種版面都只顯示地圖。
filters 以 | 分隔，選擇要顯示集合本身的哪些訪客篩選。無論你以何種順序撰寫，都會依集合中的順序顯示；集合未提供的篩選會被忽略。沒有 filters 時，版面會顯示集合的所有篩選。
| 篩選 | 顯示 | 符合 |
|---|---|---|
search | 一個文字欄 | 名稱、地址或類別包含該文字的地點。 |
category | 類別按鈕，最多顯示最常見的 30 個 | 屬於任一所選類別的地點。 |
price | 最低值和最高值 | 價格在範圍內的地點。縮小範圍後，沒有價 格的地點會被隱藏。 |
beds、baths | 不限、1+、2+、3+、4+ | 至少有該數量的地點。 |
open_now | 一個開關 | 依地點本身時區此刻正在營業的地點。開關開啟時，沒有營業時間的地點會被隱藏。 |
訪客設定的所有篩選會同時生效。
card 設定地點卡片顯示多少內容。預設值 auto 是在 Studio 中設計的卡片。compact 只顯示標題、副標題和動作，適合小框架。
地點動作依集合的定義運作。路線在地圖中繪製路線，並提供 Apple 地圖和 Google 地圖；連結在新分頁中開啟；撥打電話開啟電話連結；請求動作（例如 Schedule a Tour）會在地圖上方開啟商家的請求表單。
導覽版面
layout="guide" 開啟一張場所地圖，並在旁邊顯示其 Ask Kaleidr 面板：例如飯店的街區指南，或場所的周邊地圖。它列出一個場所集合（collection，否則為地圖繪製的第一個場所集合），並需要開啟 Control Tower。在沒有繪製任何場所集合的地圖上，此版面只顯示地圖。
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="guide"
style="display:block; height:640px"></kaleidr-map>
- 聊天優先。 在寬度 769 像素以上的框架中，面板寬 400 像素，位於地圖左側。較窄時，它是覆蓋在地圖上、高度 45% 的面板，訪客可向上拖曳到 85%。說明回答由 AI 產生的提示始終位於輸入框下方。
- 輸入框上方的類別標籤是集合中最常見的八個類別。點按標籤會顯示該類別的圖釘，並以訪客的語言提問「顯示 錨點 附近的 類別」。Plan My Day 會提問「以 錨點 為中心規劃我的一天」。
- 錨點是地圖的 起點圖釘，在 Studio 的地圖設定中指定：地圖所繪製集合中的一個地點，或放在地圖上的一個點，例如你的飯店。它會繪製成帶有名稱的獨立圖釘，導覽中的「附近」即指它的附近。沒有錨點的地圖使用地圖中心。
- 一日行程。 被要求規劃一天時，導覽會繪製一條從錨點出發的路線，先造訪你自己集合中的地點，再造訪 Kaleidr 自有的地點資料，並以訪客的語言用帶有名稱和時間的停靠點卡片顯示。
- 場所卡片顯示在 Studio 中設計的卡片，你標記的地點會帶有 Staff Pick，下方顯示你的連線提供的卡片。連線的內容只會出現在卡片上，絕不會出現在導覽的回答中。
- 請求。 場所的 Reserve 動作會開啟商家的請求表單。
聊天串流中的導覽
viewer 會告訴地圖的 Kaleidr AI 它顯示的是哪種版面。POST /chat/control/stream 的用戶端會看到兩個屬於導覽的欄位：
| 欄位 | 位置 | 結構 |
|---|---|---|
layout | 請求本文 | 顯示導覽版面時為 "guide"；否則省略，即一般的地圖回合。最多 16 個字元，否則請求會以 422 invalid_layout 遭拒。 |
itinerary | 串流中的一個事件，並在 end 事件中重複 | { title, stops: [{ name, time?, note? }] }：一日行程的標題和 1 到 12 個帶名稱的停靠點，已使用訪客的語言。note 只會出現在你自己的地點上。 |
不顯示一日行程的用戶端可以忽略此事件。
即時版面
layout="live" 顯示你的車輛現在在哪裡，以及今天在哪裡停靠：例如餐車的路線、接駁車、行動服務。它讀取兩個集合：一個車輛集合，其位置來自即時追蹤；以及一個帶有時刻表的站點集合。
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="viewer" share-id="YOUR_MAP_ID" layout="live"
collection="VEHICLES_COLLECTION_ID" stops="STOPS_COLLECTION_ID"
style="display:block; height:640px"></kaleidr-map>
| 選項 | 預設值 | 讀取 |
|---|---|---|
collection | 地圖繪製的第一個車輛集合 | 即時顯示的車輛。 |
stops | 地圖繪製的第一個站點集合 | 站點及其服務時段。 |
在兩者都未繪製的地圖上，此版面只顯示地圖。在寬度 769 像素以上的框架中，面板位於地圖旁邊；較窄時則是覆蓋在地圖上的面板。
- 面板頂端顯示 即時 標籤；沒有車輛在班時顯示 目前未營運。
- 每輛顯示的車輛一列：車輛名稱；行駛中、已停車、位於 加站點名稱，或在最後一次回報早於車隊的 標示為過時的時間 時顯示 5 分鐘前出現；以及 下一站、約 12 分鐘 和 估計 標籤。
- 今日路線：今天的站點依服務時段排序，每個站點顯示其時段、服務車輛和一個徽章。
- 到我這裡要多久？ 會請求訪客的位置，若訪客拒絕，則使用所在城市的大略位置，並顯示所顯示的車輛到達訪客需要多久。該位置只用於這次估算，絕不會被儲存。
- 選取車輛後會持續跟隨該車輛，直到訪客移動地圖。選取站點會開啟其卡片，顯示今天的時段或下一個服務日期。
| 徽章 | 條件 |
|---|---|
| 就在這裡 | 車輛已在該站點報到。 |
| 今日休息 | 司機已將車輛標示為今日休息。 |
| 營業中 | 站點的某個時段包含此刻。 |
| 下一時段：11:00–14:00 | 站點今天稍後還有時段。 |
| 今日不營業 | 站點今天沒有時段。其卡片會顯示 14 天內的下一個服務日期。 |
訪客看到的移動平順，且從不猜測。 車輛從一個已回報的位置滑動到下一個位置，絕不會超前最後一次回報。位置每 10 秒重新整理一次，除非地圖作者選擇了其他間隔（5 到 60 秒），頁面隱藏時暫停。今天的狀態和預估時間每分鐘重新整理一次。重新整理失敗時保留上一次 的畫面。
只顯示在班的車輛， 精確度不超過車隊的公開精確度所允許的範圍。班次結束的車輛會在下一次重新整理時消失。
所有時間都是預估。 它依道路距離和一般速度計算，不包含交通狀況。時間無條件進位到分鐘，顯示為 約 12 分鐘 或 約 1 小時 20 分鐘，絕不顯示為到達時刻。兩點之間沒有道路路線時，該列顯示 無法估計。道路路線以 OpenStreetMap 資料建立，© OpenStreetMap contributors，依據 ODbL 授權。
Request Pickup 是站點集合的請求動作。當其作者開啟了讓訪客選擇上車點和目的地時，訪客會先透過搜尋地址或點按地圖設定上車點（若不變更則為站點本身）和目的地，再填寫請求表單。這兩個點會隨請求一起送出。
面板的標籤文字跟隨 viewer 的語言，支援與聊天列相同的十種語言。
選項
| 掛載選項 | 屬性 | 類型 | 默認值 | 必需 | 說明 |
|---|---|---|---|---|---|
product | product | 'viewer' | 無 | 是 | 選擇 Viewer。 |
shareId | share-id | 字符串 | 無 | 是 | 從 Studio 嵌入代碼取得的已發佈地圖 ID。必須符合 ^[A-Za-z0-9._~-]{1,100}$。 |
mapId | map-id | 字符串 | 無 | 否 | shareId 的別名，僅在沒有 shareId 時使用。 |
center | center | [longitude, latitude]；屬性格式為 "longitude,latitude" | 保存的視圖 | 否 | 初始中心。 |
zoom | zoom | 數字 | 保存的視圖 | 否 | 初始縮放；掛載時沒有 center 則忽略。 |
pitch | pitch | 數字，單位為度 | 保存的視圖 | 否 | 初始傾斜角。 |
bearing | bearing | 數字，單位為度 | 保存的視圖 | 否 | 初始旋轉角。 |
viewerBase | viewer-base | URL | https://map-embed.kaleidr.com | 否 | iframe 的載入來源，僅使用來源部分。生產環境不需要設置。 |
base | base | URL | https://cdn.kaleidr.com | 否 | SDK 載入 viewer.js 的來源。只使用來源，而且只接受基礎地址覆蓋規則允許的來源。 |
enabled | flag | 布爾值 | 無 | 否 | 每次掛載的啓用開關。 |
prompt | prompt | 字符串 | 無 | 否 | 地圖打開時要向地圖的 Kaleidr AI 提出的問題。在聊天列上為輸入框的預填文字。最多 500 個字符。 |
promptParam | prompt-param | 字符串 | 無 | 否 | 從頁面自身 URL 的此查詢參數讀取 prompt：在聊天列的結果頁面上為 q。僅當訪客來自同一來源的頁面時才讀取，因此來自其他地方的連結無法讓地圖提出任何問題。 |
layout | layout | 'map'、'bar'、'locator'、'listings'、'guide' 或 'live' | 'map' | 否 | bar 掛載聊天列。locator 和 listings 在集合清單旁顯示地圖，參閱地點版面。guide 在場所地圖旁開啟聊天，參閱導覽版面。live 顯示車輛和今天的站點，參閱即時版面。 |
collection | collection | string | 地圖繪製的第一個與版面類型相符的集合 | 否 | 門市查詢、物件清單和導覽：要列出的集合 ID。即時：車輛集合的 ID。 |
stops | stops | string | 地圖繪製的第一個站點集合 | 否 | 即時：站點集合的 ID。 |
filters | filters | 字串陣列；屬性中以 | 分隔 | 集合的所有篩選 | 否 | 門市查詢和物件清單：在集合提供的篩選中，顯示 search、category、price、beds、baths 和 open_now 中的哪些。 |
card | card | 'auto' 或 'compact' | 'auto' | 否 | compact 卡片只顯示標題、副標題和動作。 |
prompts | prompts | 字符串數組；屬性中以 | 分隔 | 無 | 否 | 聊天列：示例問題，顯示為點擊即可提問的按鈕。 |
title | chat-title | 字符串 | 無 | 否 | 聊天列：輸入框上方的標籤。 |
placeholder | placeholder | 字符串 | “Ask about this map”，使用聊天列的語言 | 否 | 聊天列：輸入框的佔位文字。 |
accent | accent | CSS 顏色 | #2da84a | 否 | 聊天列：發送按鈕、圖標和焦點環的顏色。 |
theme | theme | 'light'、'dark' 或 'auto' | 'light' | 否 | 聊天列：配色。auto 跟隨訪客的系統設置。 |
lang | lang | 語言標記 | 訪客的瀏覽器語言 | 否 | 聊天列：其自身標籤的語言。 |
resultsUrl | results-url | URL | 無 | 否 | 聊天列：將訪客帶往此頁面並附加 ?q=<question>，而不是在頁面上方打開地圖。 |
publishableKey、styleId、map、mapTarget 和 contained 對 Viewer 掛載無效。在此提供金鑰甚至會產生副作用：SDK 會將其交換為 Viewer 根本不用的工作階段，如果交換失敗，地圖也無法顯示。
地圖 ID
shareId 接受 Studio 為地圖生成的兩種 ID：
- 已發佈地圖的 ID。 此 ID 出現在 發佈與嵌入 頁面的嵌入代碼中，也出現在 分享 對話框的 嵌入 選項卡中，兩者相同。
- 分享鏈接的 ID。 此 ID 是 分享 對話框 鏈接分享 選項卡的 URL 末尾那 16 個字符。
已發佈地圖 ID 顯示當前保存的地圖。分享鏈接 ID 則顯示創建鏈接時保存的設計快照。Kaleidr AI 接受這兩種 ID：在分享鏈接上，它依據快照中的 Kaleidr AI 開關運作，前提是地圖處於已發佈狀態，並使用地圖當前允許的域名；參閱已發佈地圖上的 Chat。
空白或格式無效的 ID 不會拋出異常。SDK 會記錄
[kaleidr:viewer] Kaleidr map: invalid id "" — must match ^[A-Za-z0-9._~-]{1,100}$.
且不會渲染任何內容。Kaleidr.mount 仍會返回句柄，但其方法不起作用。
直接 iframe URL
https://map-embed.kaleidr.com/embed/<id>?camera=<lon>,<lat>[,<zoom>]&pitch=<deg>&bearing=<deg>&q=<question>&layout=<layout>&collection=<id>&stops=<id>&filters=<a|b>&card=<card>
| 查詢參數 | 值 | 作用 |
|---|---|---|
camera | longitude,latitude 或 longitude,latitude,zoom | 初始中心，以及可選的縮放級別。 |
pitch | 數字，單位為度 | 初始傾斜角。 |
bearing | 數字，單位為度 | 初始旋轉角。 |
q | 文本，最多 500 個字符 | 地圖打開時要向地圖的 Kaleidr AI 提出的問題。僅當 Viewer 嵌入在頁面中時才會提問，對未開啓 Control Tower 的地圖無效。 |
layout | locator、listings、guide 或 live | 一種地點版面、導覽或即時版面。其他任何值都顯示地圖。 |
collection | 集合 ID | 版面列出的集合；在 live 上為車輛集合。 |
stops | 集合 ID | 在 live 上為站點集合。 |
filters | 以 | 分隔的篩選名稱 | 版面顯示的篩選。 |
card | auto 或 compact | 地點卡片顯示多少內容。 |
SDK 根 據鏡頭選項、prompt、layout、collection、stops、filters 和 card 構造相同的 URL。
鏡頭
初始鏡頭依次由以下來源構成。後一個來源只覆蓋自己提供的字段。
- 底圖默認視圖。
- 作者在 Studio 保存的視圖。作者可以為桌面、平板和手機寬度分別保存視圖，地圖會按照 iframe 的寬度選擇匹配的視圖。作者也可以選擇自動框選地圖內容，使內容適應視框。
- 頁面傳入的鏡頭參數：選項或屬性中的
center、zoom、pitch、bearing，或者直接 iframe URL 中的camera、pitch、bearing。
頁面提供的鏡頭參數優先於作者保存的視圖，包括根據屏幕寬度保存的視圖和自動內容框選。未提供的字段繼續採用作者的值。
採用按寬度適配視圖或內容框選的地圖，會在視框尺寸變化時重新調整視圖，直到訪問者手動移動地圖。但頁面設置的鏡頭也會結束這一行為：載入時傳入鏡頭參數，或調用 setCamera 後，地圖就不再因尺寸變化自動重新框選。setCamera 只修改指定字段，其餘保持不變。
center 中經度在前：[-0.1276, 51.5072] 表示倫敦。
尺寸
- iframe 寬度為掛載目標的 100%，沒有邊框，帶有圓角。
- 如果掛載時目標已有高度，iframe 高度為其 100%；否則固定為 500 像素。
- 掛載會替換目標的子元素，並設置
position:relative（未設置內聯定位時）和overflow:hidden。 <kaleidr-map>默認使用display:block，因此可以設置height。請指定高度。示例另外保留display:block，以兼容 Safari 16.4 之前無法自動將該元素設為塊級的版本。
句柄
Kaleidr.mount 同步返回句柄。所有產品的情況請參閱句柄矩陣。
| 成員 | Viewer 中的行為 |
|---|---|
handle.product | 'viewer' |
handle.setCamera(camera) | 移動地圖。 |
handle.setTheme(theme) | 不支持；發出警告且不執行操作。 |
handle.setStyle(style) | 不支持；發出警告且不執行操作。 |
handle.send(text) | 向地圖的 Kaleidr AI 提問，如同訪客輸入了 text。在聊天列上，不帶文本的 send() 會提出輸入框中的內容。在回答某個問題期間發送的問題會等待其完成，較新的問題會取代仍在等待的問題。 |
handle.setFilters(filters) | 設定地點版面的訪客篩選。在 map 版面中不會執行任何操作。 |
handle.showVehiclesLayer(layer) | 繪製或移動你自己的車輛圖層。 |
handle.clearVehiclesLayer() | 移除你的車輛圖層。 |
handle.destroy() | 移除 iframe 並停止監聽消息。 |
setCamera(camera)
handle.setCamera({
center: [2.3522, 48.8566], // [longitude, latitude]
zoom: 12,
pitch: 45,
bearing: -20,
duration: 800, // milliseconds
});
| 字段 | 類型 | 說明 |
|---|---|---|
center | [number, number] | 經度、緯度。 |
zoom | 數字 | 縮放級別。與掛載時不同，這裡 zoom 不需要 center 也能生效。 |
pitch | 數字 | 傾斜角，單位為度。 |
bearing | 數字 | 旋轉角，單位為度。 |
duration | 數字 | 動畫時長，單位為毫秒。省略或設為 0 時立即跳轉。 |
所有字段均為可選；未提供的字段保留當前值。
可以隨時調用 setCamera，只要 Kaleidr.mount 已返回，即使在下一行也可以。若 iframe 內的地圖尚未就緒，調用將被保留，並在地圖報告就緒後按順序執行。最多保留最近 256 次調用。若等待有限時間（通常是 iframe 載入後 10 秒）仍未收到就緒通知，調用仍會發出，並顯示一條控制台警告。無需等待 kaleidr-embed:ready。對於地圖打開時的初始視圖，使用掛載選項仍是直接方式，地圖會從該視圖開始而不是稍後再移動過去。
沒有用於讀取當前鏡頭參數的方法。
setFilters(filters)
handle.setFilters({
q: 'downtown',
category: ['Outlet', 'Flagship'],
price: [250000, null], // [min, max]; null leaves that end open
beds: 2,
baths: 1,
open_now: true,
});
| 欄位 | 類型 | 設定 |
|---|---|---|
q | 字串 | 搜尋欄。 |
category | 字串陣列 | 所選類別。 |
price | [number | null, number | null] | 最低價格和最高價格。 |
beds | 數字 | 最少臥室數。 |
baths | 數字 | 最少浴室數。 |
open_now | 布林值 | 「營業中」開關。 |
所有欄位皆為選用。訪客會看到篩選改變，就像自己設定的一樣，也可以再次修改。版面未顯示的篩選所對應的欄位，以及其他任何欄位，都會被忽略。與 setCamera 相同，在地圖就緒前發出的呼叫會被保留，並在就緒後套用。早於地點版面的 viewer 套件沒有 setFilters；此時呼叫不會執行任何操作，並記錄一則控制台警告，說明掛載未提供此方法。
showVehiclesLayer(layer)
在嵌入的地圖上繪製你的頁面已在追蹤的車輛，例如你自己派車系統中的位置。資料只從你的頁面傳入 iframe，不會送往其他任何地方：不經過 Kaleidr 的伺服器，viewer 也不會為此圖層擷取任何資料。
handle.showVehiclesLayer({
layer_id: 'shuttles',
vehicles: [
{ id: 'bus-1', name: 'Shuttle 1', lat: 40.7411, lng: -73.9897, bearing: 90, color: '#1f6feb' },
{ id: 'bus-2', name: 'Shuttle 2', lat: 40.7527, lng: -73.9772 },
],
});
// Ten seconds later, the same layer_id: each shuttle slides to its new point.
handle.showVehiclesLayer({ layer_id: 'shuttles', vehicles: nextPositions });
handle.clearVehiclesLayer();
| 字段 | 類型 | 說明 |
|---|---|---|
layer_id | string | 圖層名稱。再次使用相同的 ID 會就地更新圖層。 |
vehicles | array，最多 2,000 個 | 要繪製的車輛。 |
vehicles[].id | string | 必填。在多次呼叫之間識別同一輛車。 |
vehicles[].lat, vehicles[].lng | number | 必填。車輛的位置。 |
vehicles[].name | string | 繪製在車輛旁邊的標籤。 |
vehicles[].color | CSS 十六進位色彩 | 車輛的顏色。未提供時繪製為灰色。 |
vehicles[].bearing | number，度 | 車輛朝向的方向。 |
attribution | string | 你的資料的出處標示，點按車輛時顯示在其卡片上。 |
- 相同的
layer_id會就地更新。 每輛車從目前繪製的位置滑動到新的點，用時為距你上一次呼叫經過的時間，最長 30 秒。新呼叫中缺少的車輛會消失。 - 新的
layer_id或未提供時，會取代圖層。 地圖一次只顯示一個車輛圖層。 - 沒有
id，或lat和lng不是有限數值的車輛會被捨棄， 第 2,000 輛之後的車輛也是如此。 - 要移動車輛，請再次呼叫。 viewer 從不為此圖層主動擷取資料。
- 與
setCamera相同，在地圖就緒前發出的呼叫會被保留， 並在就緒後套用。
SDK 的 LiveLayerData 和 LiveVehicle 型別宣告了該圖層的結構。showVehiclesLayer 和 clearVehiclesLayer 是 viewer 方法：在 chat、editor 和 tile 上，它們會記錄一則警告且不執行任何操作。早於此圖層的 viewer 套件兩者都沒有；此時呼叫不會執行任何操作，並記錄一則控制台警告，說明掛載未提供此方法。
掛載後的元素屬性
在已掛載的 <kaleidr-map product="viewer"> 上，更改 center、zoom、pitch 或 bearing 會無動畫地移動地圖。更改 share-id 或其他屬性不起作用。若要切換地圖，需要移除該元素並插入新元素。
iframe 消息
iframe 會向嵌入頁面發送消息。其中兩種是公開的“已載入”和“失敗”信號：
// The map drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'publish' | 'share' }
// The map could not load, or part of it failed to draw.
{ type: 'kaleidr-embed:error', id: string | null, code: string, message: string }
window.addEventListener('message', (event) => {
if (event.origin !== 'https://map-embed.kaleidr.com') return;
if (event.source !== iframe.contentWindow) return; // which embed sent it
const msg = event.data;
if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
if (msg?.type === 'kaleidr-embed:error') onError(msg);
});
通過 SDK 使用時，iframe 是掛載目標內的第一個 <iframe>：target.querySelector('iframe')。
錯誤代碼
code | 是否終止 | 含義 |
|---|---|---|
no_id | 是 | iframe URL 不包含地圖 ID；id 為 null。 |
not_found | 是 | 該 ID 對應的已發佈地圖或分享連結不存在：地圖從未發佈或已取消發佈，分享連結的地圖已刪除或 Kaleidr 移除了該連結，或 ID 輸入錯誤。 |
domain_not_allowed | 是 | 地圖限制了允許的網域，嵌入頁面不符合要求，或瀏覽器未發送來源頁面信息。 |
map_loads_exhausted | 是 | 所有者組織已用完本週期地圖載入次數。 |
fetch_failed | 是 | 無法獲取地圖。 |
maplibre_error | 否 | 地圖已啓動，但某些內容繪制失敗。可能在 ready 前後多次發生。 |
出現終止性代碼後，iframe 會顯示簡短錯誤信息來代替地圖，也不會發送 ready。
規則
- 地圖繪制完成且瀏覽量已計入之後，每次載入只發送一次
ready。 - SDK 創建 iframe 時使用
loading="lazy"，因此只有 iframe 接近可視區域後才會發送消息。 - iframe 還會發送其他
type以kaleidr-embed:開頭的消息。SDK 用它們把 Chat 連接到地圖；這些消息不屬於公開契約且可能改變，請勿依賴。 - iframe 僅接受直接嵌入它的頁面所發送的控制消息，例如
setCamera對應的鏡頭移動。其他窗口或框架發來的消息會被忽略；應從持有 iframe 的頁面調用setCamera。 - SDK 和元素都不觸發 DOM 事件，也不提供
readyPromise。
訪問者看到的消息
這些消息會在 iframe 內替代地圖顯示：
| 文本 | 代碼 |
|---|---|
| "Loading map…" | 無：地圖載入中 |
| "Couldn't find a map id in the URL." | no_id |
| "This map isn't available — it may have been unpublished, paused, or the link is incorrect." | not_found |
| "This map isn't allowed to render on this site. Please contact the map owner." | domain_not_allowed |
| "This map has reached its map load limit. It will be available again when the owner's allowance resets." | map_loads_exhausted |
| "Could not load the map. Please try again in a moment." | fetch_failed |
| "Unexpected error loading the map." | 無：啓動時發生意外錯誤 |
已 上傳的資料
已發佈地圖會繪製作者在 Studio 的“資料”面板中添加的資料集和圖片疊加層。iframe 自行載入這些內容，不需要選項、屬性或金鑰，資料也不會經過你的頁面。
| 行為 | 詳情 |
|---|---|
| 顯示的內容 | 已發佈地圖包含的所有資料集和圖片疊加層，使用作者設置的圖層樣式顯示。 |
| 可查看人員 | 任何能夠打開地圖的人。限制嵌入網域並不意味著資料保密。 |
| 瀏覽器收到的內容 | 每個資料集的全部資料及所有列。較大的資料集載入更慢。 |
| 資料集載入失敗時 | 其他地圖內容正常繪制，只缺少該圖層。 |
| 在 Studio 資料面板中刪除資料集 | 資料集被永久刪除，並停止向已發佈地圖以及顯示它的分享鏈接提供資料。已經載入過資料的瀏覽器仍保留副本，已簽發的下載鏈接最長可能在一小時內繼續有效。 |
| 取消發佈地圖 | 不再通過發佈 ID 提供該地圖及其資料集。iframe 顯示 not_found。重新發佈可以恢復相同 ID。 |
| 分享鏈接 | 分享鏈接保存了創建時的地圖設計快照；取消發佈地圖後仍會顯示地圖，但在地圖重新發佈前不提供 Kaleidr AI。Studio 沒有刪除或暫停分享鏈接的操作；只有刪除地圖或由 Kaleidr 應所有者要求移除鏈接後才停止工作。參閱分享鏈接。 |
已發佈地圖上的上傳資料詳細介紹了上述情況。
允許的網域
地圖所有者可以在 Studio 的 分享、嵌入、指定網域 中限制哪些網站可以顯示地圖。
- 列出的網域也包含其子網域。
- 檢查時會將列表與瀏覽器在 iframe 請求中發送的來源頁面主機名進行比較。缺少來源頁面信息會導致驗證失敗。
- 驗證失敗時顯示“不允許”消息，併發送
domain_not_allowed。 - 因網域驗證失敗的查看不計入地圖載入次數。
計量
- 每次查看為地圖所有者組織統計一次地圖載入。
- 同一訪問者在 24 小時內再次查看同一地圖，不會重復計數。
- 在 Kaleidr 自有網站上的查看不計數。
- 配額用盡時，iframe 會顯示用量限制消息，直到配額重置。參閱配額與速率限制。
控制台消息
| 消息 | 含義 |
|---|---|
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile" | 元素缺少有效的 product，不會掛載。 |
[kaleidr:viewer] Kaleidr map: invalid id "…" — must match ^[A-Za-z0-9._~-]{1,100}$. | ID 為空或格式無效。 |
[kaleidr:viewer] mount target not found: <selector> | Kaleidr.mount 沒有找到匹配選擇器的元素。 |
[kaleidr:viewer] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/viewer.js | 因網路錯誤、攔截程序或 script-src 策略，無法載入 Viewer 腳本包。 |
[kaleidr] setStyle() is not supported on product "viewer" — the call is a no-op. … | 調用了 Viewer 不支持的句柄方法。 |
不支持的功能
- 點擊、鏡頭移動或選取事件，包括地點卡片和地點動作。
- 讀取地圖的鏡頭、圖層或資料。
- 向嵌入的地圖添加自己的標記或圖層，車輛圖層除外。
- 通過嵌入內容更改底圖或主題。