在網站中嵌入互動式地圖

你可以使用直接 iframe、可重複使用的 Web 元件，或連接即時地圖的 JavaScript SDK，在網站中嵌入互動式地圖體驗。獨立發佈的地圖適合使用 iframe；希望以簡潔 HTML 使用由供應商維護的實作時，可選擇 Web 元件；當主頁面需要控制鏡頭、生命週期或產品操作時，則應使用 SDK。正式環境中的嵌入還需要明確的尺寸、網域控制、無障礙支援、可檢索文字與操作分析。

下文將介紹嵌入方式選擇、Kaleidr Viewer 設定、響應式容器、安全性、無障礙、SEO 與常見錯誤。若要把對話功能連接至即時算繪器，請參閱如何在地圖中加入 AI 聊天。若要瞭解 SDK 這項產品類別，請參閱什麼是 AI 地圖 SDK？。

地圖嵌入要點

先選擇方式： 依主頁面所需的控制程度選擇 iframe、Web 元件、SDK 或原生地圖函式庫，而不是依程式碼範例的長度決定。

預留高度： 載入前為地圖容器設定明確高度，避免容器塌陷與版面位移。

已發佈的 Viewer： Kaleidr Viewer 使用 product="viewer" 與共用 ID；存取由共用連結和發佈者允許的網域共同控制。

在畫布外提供文字： 標題、摘要與地點清單能讓鍵盤使用者、輔助技術與搜尋系統有效使用頁面。

衡量任務完成： 追蹤載入、選取、路線要求與轉換，而不只是地圖顯示次數。

三種整合路徑——直接 iframe、Web 元件和 JavaScript SDK——透過網域控制、可及性與分析功能，整合單一響應式互動式地圖體驗。

如何嵌入互動式地圖體驗？

本指南將為行銷網站、目的地指南、房產頁面、門市定位器、文章或軟體產品建立響應式地圖區域。完成的體驗包括已發佈的互動式地圖、適用桌面與行動裝置的容器、地圖之外清楚的標題與文字摘要、由主頁面控制鏡頭的選用能力、網域或憑證限制、載入與失敗狀態、替代地圖專有資訊的無障礙內容，以及衡量互動情況的事件。範例使用 Kaleidr Viewer，因為它能透過一個載入器與一個自訂元素嵌入已發佈的地圖；相同的決策架構也適用於供應商 iframe、地圖 Web 元件，以及以 Mapbox、Google Maps、MapLibre 或 Leaflet 建立的自訂實作。

如何選擇合適的嵌入方式？

第一個決定是主機網站需要多少控制權。內容頁面上已發布的地圖通常不需要與 SaaS 工作流程中的地圖相同的架構，因此預設情況下避免選擇最複雜的方法。

方法	最佳合適	首頁控制	主要權衡
直接 iframe	獨立地圖或供應商嵌入	低	最快速的設定，有限的整合
網頁元件	使用簡單的 HTML 重新使用可重新使用的已發佈地圖	Medium	清除標記;行為取決於元件合約
JavaScript SDK	與相機、生命週期、事件或人工智慧的產品整合	高	更多執行責任
原生地圖庫	完全自訂地圖應用程式	最高	最大控制，最大的工程表面

嵌入方法決策架構，比較直接的 iframe、Web 元件、JavaScript SDK 以及設定、控制、生命週期、自訂與安全性的原生地圖函式庫。

當地圖能獨立運作、主頁面只需顯示地圖，且希望盡量減少開發工作時，可直接使用 iframe。HTML iframe 元素會建立獨立的嵌入式瀏覽環境；這種隔離很有用，但也代表另一個擁有自身資源與無障礙要求的文件環境。當團隊希望使用宣告式 HTML 元素，地圖 ID 或鏡頭等屬性已經足夠，且由供應商維護內部實作時，可使用 Web 元件。自訂元素可將載入與訊息傳遞隱藏在穩定的公開合約之後。當主應用程式必須保留操作控制代碼、更新鏡頭或主題、在路由變更時銷毀地圖、連接即時算繪器，或協調瀏覽器驗證、事件與 AI 工作流程時，應使用 JavaScript SDK。

Kaleidr Viewer 嵌入如何運作？

Kaleidr Viewer 透過共用 ID 嵌入已發佈的 Kaleidr 地圖。Viewer 管理自己的地圖，並在 <kaleidr-map> 元件內部的 iframe 邊界中運作；主頁面可透過 SDK 控制代碼與文件化的訊息介面，控制支援的行為。現行合約有四項重要屬性：product="viewer" 選擇已發佈地圖的 Viewer；share-id 識別該地圖；Viewer 存取由共用連結控制且不需要 API 金鑰；發佈者設定的允許網域仍然適用。Viewer 與 Kaleidr Chat 不同：Viewer 管理自己的地圖，而 Chat 可以連接主應用程式中已經運作的 Mapbox、Google Maps、MapLibre 或 Leaflet 執行個體。

已發布的檢視器安全性與生命週期:主機網站會載入版本化的載入程式，並使用共用識別碼宣告萬聯映射，此網頁元件會驗證來源並建立 iframe 邊界，且已發布的地圖服務會透過獨立的分析路徑來強制執行共用連結與允許的網域檢查。

掛載產品前，只需從 https://cdn.kaleidr.com/embed/v1/kaleidr.js 載入一次標示版本的載入器。載入器會定義 <kaleidr-map>、安裝 window.Kaleidr，然後視需要載入所選產品套件。最小化的已發佈地圖嵌入會為自訂元素設定明確高度：

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

此範例遵循目前的快速入門、<kaleidr-map> 參考文件與Viewer 嵌入文件。請將 abcd1234 替換為已發佈地圖的共用 ID。地圖必須已發佈，並獲准在主網域中算繪。應使用文件化的元件，而不要建構不屬於公開合約的內部 Viewer URL。

如何建立響應式且支援無障礙的地圖頁面？

嵌入式地圖需要明確的高度。若無一個，容器可能會崩塌、產生不穩定的版面配置，或回落至提供者特定的預設值。將元素包裹在地圖載入前保留空間的外殼中——寬度全、最小高度，且在桌面上通常具有16:9的長寬比，而窄型手機則具有較高的固定最小值。保留空間可減少意外的版面配置移動;未定義尺寸的嵌入是累積佈局轉移的常見原因(web.dev CLS 指引)測試實際地圖，而非僅依賴寬幅比:淺寬螢幕地圖通常適用於桌面，但在手機上卻變得難以使用。

桌面與行動互動地圖版面配置，包含預留高度、可見焦點環、透過搜尋與標記的鍵盤路徑，以及等效位置列表。

在支援的情況下，Viewer 元件會監測 center、zoom、pitch、bearing 與 theme；center 使用經度、緯度順序。請選擇能直接呈現地圖用途的初始鏡頭，例如重點街區、開發與大眾運輸，或具有明確搜尋及篩選功能的全國視圖。當主頁面需要操作控制代碼時，應在載入器就緒後透過命令式 API 掛載：

const viewer = Kaleidr.mount("#featured-map", {
  product: "viewer",
  shareId: "abcd1234",
  center: [-0.12, 51.5],
  zoom: 11
});

// In an SPA, call destroy before removing the page or component.
window.addEventListener("pagehide", () => {
  viewer.destroy();
});

產品套件載入期間，Kaleidr.mount() 會同步傳回操作控制代碼；在產品套件就緒前發出的呼叫會進入佇列。控制代碼一律提供 destroy()，並可能在所選產品支援時提供 setCamera() 或 setTheme()。單頁應用程式應將銷毀操作接入路由生命週期，避免重複導覽建立重複的嵌入執行個體。

互動式地圖無法是唯一取得必要資訊的方式。 WCAG 2.2 提供可存取網頁內容的架構:為地圖提供有意義的標題與標註區域，發布包含姓名、地址、分類與操作的等效位置清單，確認鍵盤使用者可觸及地圖後離開地圖，且避免使用純色標記。對於原始的 iframe，請包含描述性的 title 屬性，而非「map」等通用標籤。

團隊應如何處理網域、效能與 SEO？

共用 ID 並不代表不受限制的公開權限。Kaleidr Viewer 透過共用連結控制存取，發佈者設定的允許網域仍然生效；僅限核准網站的地圖不會因為有人知道共用 ID 就在其他網站算繪。網域清單應涵蓋正式環境、需要時的 www 變體、預備環境，以及受支援的本機開發環境。Kaleidr 目前的定價為 Pro 與 Enterprise 提供嵌入支援。Viewer 本身不需要 API 金鑰，但團隊應在正式部署前確認方案、地圖載入配額與發佈控制（定價）。

將地圖視為一個有意義的應用表面。載入前保留尺寸。當不對初始視點(原生)至關重要時，會延遲載入或延遲於摺疊下方的地圖 loading="lazy" 適用於原始 iframe，而自訂元件可能需要主機側交叉側觀察器或點擊式外牆。請勿延誤該頁面主要於摺疊式上的地圖。避免在單頁上載入重複的地圖堆疊，並測量實際裝置上的載入時間、時間，直到互動、磁磚傳輸以及行動記憶體。

主機頁面仍需要可爬取且具描述性的文字。在頂端附近標示地圖內容、在 HTML 中發布重要位置或結論、使用描述性標題，以及僅在與可見內容相符時才會新增結構化資料。JavaScript 渲染的 Google 文件為搜尋系統引入了額外的階段(JavaScript SEO 基礎知識)將嵌入內容放入一個穩定的規範頁面中，而非許多僅由地圖中心不同的近乎相同的網址。嵌入步驟前的地圖建立與發布內容已涵蓋於人工智慧互動地圖建置工具.

錯誤	發生什麼事	建議更正
沒有明確的地圖高度	地圖會崩塌或調整版面配置	載入前保留回應式尺寸
使用原始的內部檢視器網址	主機需依賴無文件的詳細資料	使用 `<kaleidr-map>` 或 `Kaleidr.mount()`
不得使用網域	在單一環境中工作，生產失敗	新增經過核准的精確部署網域
立即載入每一張地圖	不必要的 JavaScript、磁磚和資料	請在下方的地圖中請轉至下方，或使用點擊載入
僅限地圖內容	使用者與搜尋系統遺漏必要事實	新增文字摘要及等效位置列表
SPA 中無拆封	重複實例與聽眾累積	保留手柄與通話 `destroy()`
只有地圖瀏覽才能追蹤	曝光被誤認為是任務完成	追蹤選取、方向、詳細資料和轉換
嵌入私人營運資料	可共享的表面會洩露錯誤的記錄	使用授權的應用程式工作流程

最終結論

當獨立的供應商地圖已經足夠時，使用直接 iframe；當團隊希望透過受維護的公開合約建立簡潔的宣告式嵌入時，使用 Web 元件；當主應用程式需要鏡頭控制、生命週期管理、AI 互動、驗證或更深入的產品整合時，則使用 JavaScript SDK。Kaleidr Viewer 適用於需要在多個網站中一致顯示且不需瀏覽器 API 金鑰的已發佈地圖：主頁面載入 kaleidr.js、提供共用 ID、預留響應式容器，並遵守允許網域。成功的嵌入應可靠載入、清楚說明用途、支援行動裝置與鍵盤操作、在地圖之外提供必要資訊，並協助訪客完成可衡量的任務。

嵌入已發佈的 Kaleidr 地圖

在 Kaleidr Studio 中發佈地圖，複製共用 ID，然後透過標示版本的 JavaScript 載入器加入 Viewer。請閱讀 Viewer 嵌入文件，瞭解元件與訊息傳遞合約。當地圖需要成為更大產品工作流程的一部分時，請在 開發者文件 中查看 Chat、Editor、Tiles、驗證與 Platform API。

常見問題

如何在網站中嵌入互動式地圖？

選擇已發布的地圖或提供者，將其支援的 iframe、網頁元件或 JavaScript SDK 新增至頁面、保留回應式容器、設定存取權限，以及在地圖外部提供可存取的文字。

iframe 是嵌入地圖最簡單的方式嗎？

通常。當地圖自包含且頁面幾乎不需要控制時，iframe 便適合。當主機需要穩定的產品合約、相機更新、生命週期控制、事件或人工智慧互動時，網頁元件或 SDK 會更好。

Kaleidr Viewer 需要 API 金鑰嗎？

不。目前的檢視器為共用連結，並使用已發布的地圖分享識別碼。仍適用由出版商定義的允許網域限制。

如何讓嵌入式地圖適應不同螢幕？

提供包裝紙並繪製顯式尺寸，使用全寬度，保留最低高度，並調整高度或版面配置以設計窄螢幕。測試行動裝置上的實際控制與資訊面板。

能否使用 JavaScript 控制嵌入的 Kaleidr 地圖？

是的。指令檢視器整合會傳回一個可支援相機更新且始終提供的控制器 destroy() 對拆下來。

參考資料

Google. Embed a Map. Google Maps Embed API documentation. Accessed 2 August 2026. https://developers.google.com/maps/documentation/embed/embedding-map
Google. Understand JavaScript SEO Basics. Google Search Central. Accessed 2 August 2026. https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics
Kaleidr. kaleidr.js — the Loader. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-js
Kaleidr. kaleidr-map — the Element. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/kaleidr-map-element
Kaleidr. Pricing & Plans. kaleidr.com. Accessed 2 August 2026. https://kaleidr.com/pricing
Kaleidr. Quickstart. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/quickstart
Kaleidr. Viewer — Embed a Published Map. Kaleidr Developer Docs. Accessed 2 August 2026. https://docs.kaleidr.com/sdk/viewer-embed
MDN Web Docs. iframe: The Inline Frame Element. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe
MDN Web Docs. Using Custom Elements. Accessed 2 August 2026. https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
World Wide Web Consortium. Web Content Accessibility Guidelines (WCAG) 2.2. Accessed 2 August 2026. https://www.w3.org/TR/WCAG22/
web.dev. Optimize Cumulative Layout Shift. Accessed 2 August 2026. https://web.dev/articles/optimize-cls

@misc{kaleidr_viewer_embed,
  title  = {Viewer -- Embed a Published Map},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 2 August 2026},
  url    = {https://docs.kaleidr.com/sdk/viewer-embed}
}

@misc{kaleidr_loader,
  title  = {kaleidr.js -- the Loader},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 2 August 2026},
  url    = {https://docs.kaleidr.com/sdk/kaleidr-js}
}

@misc{mdn_iframe,
  title  = {iframe: The Inline Frame Element},
  author = {{MDN Web Docs}},
  note   = {Accessed 2 August 2026},
  url    = {https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe}
}

@misc{w3c_wcag22,
  title  = {Web Content Accessibility Guidelines 2.2},
  author = {{World Wide Web Consortium}},
  note   = {Accessed 2 August 2026},
  url    = {https://www.w3.org/TR/WCAG22/}
}

@misc{google_javascript_seo,
  title  = {Understand JavaScript SEO Basics},
  author = {{Google}},
  note   = {Google Search Central; accessed 2 August 2026},
  url    = {https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics}
}