Viewer
Viewer 可将你在 Kaleidr Studio 发布的地图嵌入自己的网页。地图在 Kaleidr 托管的 iframe 中渲染，因此网页不需要加载地图程序库，也不需要 API 密钥。只需已发布地图的 ID。
如果地图已经在 Studio 中创建，而你想让访客查看，例如门店查找器、校园地图、活动路线或文章中的数据地图，请使用 Viewer。
概览
| 问题 | 回答 |
|---|---|
| 需要什么？ | 已发布地图的 ID。不需要 API 密钥或会话。 |
| 哪些套餐？ | 包括 Free 在内的所有套餐。发布需要 Kaleidr 账户。 |
| 如何显示？ | 在 https://map-embed.kaleidr.com 提供的 iframe 中。 |
| 显示哪些内容？ | 作者发布的地图，包括标记、路线、设置样式的图层，以及通过 Studio 数据面板上传的数据集和图像叠加层。 |
| 如何嵌入？ | 使用普通 <iframe> 或 SDK 的 <kaleidr-map product="viewer"> 元素。 |
| 费用如何计算？ | 每次查看按地图所有者所属组织计入一次地图加载。 |
| 页面能操作地图吗？ | 可以设置或移动相机，并监听加载完成与错误消息。除此之外不能操作。 |
最简嵌入
<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>
将 YOUR_MAP_ID 替换为发布后 Studio 嵌入代码中显示的 ID。元素默认使用 display:block，因此 height 会生效。示例中还明确写了 display:block，以兼容 Safari 16.4 之前的版本——在这些版本 中元素保持行内状态并忽略 height。
如果无法在页面中添加脚本（例如网站构建器、CMS 或接受 HTML 的电子邮件简报工具），请改用 Studio 生成的 iframe：
<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>
两种方式显示的是同一张地图。嵌入已发布地图说明何时选择哪一种。
工作原理
- 你在 Studio 发布地图。Studio 为其分配 ID 并生成嵌入代码。
- 你的网页加载该代码。SDK 元素或普通 iframe 会指向
https://map-embed.kaleidr.com/embed/YOUR_MAP_ID。 - iframe 内的页面获取已发布地图并绘制，同时显示作者上传的数据集和图像叠加层。如果地图设置了允许的域名列表，会先验证网页的域名是否在列表中。
- 地图绘制完成后，iframe 向页面发送
kaleidr-embed:ready消息。若无法绘制，则发送kaleidr-embed:error，并在地图位置显示简短说明。
你的网页不会收到地图数据，也不能访问 iframe 内部。地图程序库、样式及网络请求都留在 iframe 内，因此内容安全策略只需允许该框架。
访客可以执行的操作
- 平移、旋转、倾斜地图，使用地图上的缩放按钮、双指缩放或滚轮进行缩放。指针位于地图上方时滚动会缩放地图，与 Studio 中相同；指针位于地图之外时，滚动会移动网页。
- 浏览器请求权限后，使用定位按钮显示自己的位置。
- 如果作者在 Studio 启用了弹出信息，可点击地图打开地点弹窗。
- 阅读地图图例以及底部的来源与署名信息。
- 就地图向 Kaleidr AI 提问：作者在 Studio 的 Kaleidr AI 磁贴中开启 Control Tower 时，可在 Ask Kaleidr 面板中提问；开启 Popup Window 时，可在弹出窗口中提问。参阅已发布地图上的 Kaleidr AI。
嵌入地图为只读。访客无法编辑地图，也不会保存访客的操作。
页面可以执行的操作
- 设置初始相机：使用
center、zoom、pitch和bearing。默认使用作者保存的视图。页面传入的相机字段逐项优先于作者的设置。 - 随后移动相机：使用
handle.setCamera(...)，或更改元素的相机属性。 - 了解地图是否加载成功：监听 iframe 发送的两种消息。
- 移除地图：调用
handle.destroy()或移除元素。
地图所有者的控制选项
这些选项位于 Studio，而不在嵌入代码中：
- 发布与取消发布。 已发布地图显示 Studio 中当前保存的内容，因此保存的编辑会在下次加载嵌入地图时公开，无须重新发布。重新发布 会记录一个新的发布版本，但保留相同链接。如果要私下修改地图，应先取消发布，完成后再发布。取消发布 会停止地图的所有嵌入，再次发布则恢复相同的嵌入 URL。参阅取消发布地图。
- 上传的数据。 已发布地图绘制的数据集及图像叠加层会显示给访客。要停止提供数据，可在数据面板中删除数据集，或取消发布地图。分享链接在取消发布后仍可使用；删除数据集也会从分享链接中移除该数据。发布的地图是公开的，因此只应发布允许任何人读取的数据。参阅已发布地图中的上传数据。
- 允许的域名。 限制可显示地图的网站。验证使用网页发送的 Referrer，因此不发送 Referrer 的网页无法显示受域名限制的地图。
- Kaleidr AI。 在地图的 Kaleidr AI 磁贴中开启 Ask Kaleidr 面板（Control Tower）和弹出窗口中的 AI 聊天（Popup Window）。
限制
- Viewer 不使用密钥，因此密钥级别的允许来源限制不适用。应使用地图的允许域名设置。
- 你的网页不能读取地图图层、添加标记或接收地图的点击事件。
- 嵌入内容不会自行调整高度。请为元素或 iframe 指定高度。
- 地图所有者的组织用完当期地图加载额度后，嵌入位置会显示额度提示，直到额度重置。
- 访客会完整下载地图绘制的每个数据集，因此基于大型表格的地图显示会更慢。
后续步骤
- 嵌入已发布地图：发布、嵌入、限制域名并检查运行情况。
- Viewer 参考文档：所有选项、句柄、消息和错误代码。
- 已发布地图上的聊天：让访客就地图提出问题。
- 内容安全策略：Viewer 嵌入需要的两项指令。