Tile
Tile 可在您的页面中放置一张 Kaleidr 底图。您选择 kaleidr-morning 或 kaleidr-night 等样式后，SDK 会通过 Kaleidr 托管的 iframe 显示它。您的页面无需加载地图库。
当您需要美观且可交互的底图，又不必自己在其上绘制元素时，可以使用 Tile：例如位置背景、“我们在哪里”信息面板，或者供 Kaleidr 聊天面板展示回答的地图。
如果您已有 Mapbox、MapLibre、Google Maps 或 Leaflet 地图，就不需要 Tile。直接把 Chat 添加到现有地图即可。
概览
| 问题 | 回答 |
|---|---|
| 需要什么？ | 可发布密钥 (kld_pk_live_…) 且具有 maps 权限范围。新密钥默认包含该权限。 |
| 支持哪些套餐？ | 所有套餐，包括 Free。 |
| 如何渲染？ | 通过由 https://map-embed.kaleidr.com 提供的 iframe。 |
| 如何选择外观？ | 使用 style-id。下文列出了六种通用样式。 |
| 如何收费？ | 每次 Tile 会话计一次地图加载。参见地图加载如何计数。 |
| 页面可以操作地图吗？ | 可以设置或移动镜头、更换样式，并监听加载成功和错误消息。 |
最简单的嵌入方式
<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
publishable-key="kld_pk_live_…"
style-id="kaleidr-morning"
style="display:block; height:480px"></kaleidr-map>
正常运行需要满足三个条件：
- 密钥。 在 kaleidr.com/api-keys 创建可发布密钥。参见获取 API 密钥。
- 允许的来源。 如果密钥配置了允许的来源，页面来源必须在其中。页面必须通过 HTTP 或 HTTPS 提供，而不能直接从磁盘打开。
- 高度。 元素默认使用
display:block，所以其height属性生效。示例中也写有display:block，用于兼容 16.4 之前仍将该元素视为行内元素的 Safari。
样式
style-id | 外观 |
|---|---|
kaleidr-morning | 明亮：白色地面、青色水域、白色道路。 |
kaleidr-afternoon | 中等色调地面、绿色植被和灰色道路。 |
kaleidr-evening | 黄金时段：温暖的沙色和橄榄色调。 |
kaleidr-night | 深海军蓝与炭灰色，搭配琥珀色高速公路。 |
kaleidr-plain | 白色画布，含边界和地点标签。从缩放级别 15 开始显示 3D 建筑。 |
kaleidr-editorial | 去掉标签的下午配色，适合小型或装饰性地图。 |
请始终传入 style-id。如果省略，嵌入地图会使用组织的默认底图（如果已设置）；否则会显示错误。
工作原理
- SDK 将您的可发布密钥发送给 Kaleidr，并取得短期 Tile 会话。这一步会检查密钥、权限范围及页面来源，同时计算一次地图加载。若组织设置了默认底图，响应也会携带该底图信息。这就是 Tile 会话的全部用途：地图不会再使用该会话调用接口。
- SDK 用显示所选样式的 iframe 替换元素内容。iframe URL 仅包含样式 ID 和您指定的镜头信息，不会包含可发布密钥或会话令牌。
- 地图在 iframe 内绘制。您页面的内容安全策略只需允许加载器、会话请求和 iframe。
- 地图绘制完成后，iframe 会向页面发送
kaleidr-embed:ready消息。
访客可以执行的操作
可以平移、旋转和倾斜地图，也可以通过地图上的按钮、双指缩放或滚轮缩放。指针位于地图上方时滚动会缩放地图；指针位于地图之外时，滚动会移动页面。
您的页面可以执行的操作
- 设置初始镜头： 使用
center、zoom、pitch和bearing。 - 稍后移动镜头： 使用
handle.setCamera(...)。 - 切换样式： 使用
handle.setStyle('kaleidr-night')，无需重新加载。 - 搭配聊天面板： 聊天实例可指向 Tile 元素，在其上显示回答内容。
- 获知何时加载完成： 监听
kaleidr-embed:ready消息。
地图加载如何计数
Tile 用量以地图加载次数计量，与您已发布地图的浏览计量单位相同。每次 SDK 获取 Tile 会话都会计为一次地图加载：
- 地图首次挂载时计一次；
- 只要挂载仍在运行，SDK 每次在会话到期前不久续期时再计一次。默认会话时长为 15 分钟；
- 销毁并重新挂载实例，或移除元素后重新插入时，再计一次。
访客浏览页面几分钟会消耗一次地图加载。页面保持打开一小时则大约消耗五次。这并不是“每次页面浏览只计一次”，因此应销毁不再显示的 Tile 实例。
当组织用完当前计费周期的地图加载额度时，新的 Tile 会话会收到 HTTP 429 拒绝。新挂载的地图不会显示任何内容，而已经显示的地图仍会留在页面上。额度说明见配额与速率限制。
限制
- Tile 是底图。您的页面无法在其上添加自己的标记、图层或弹出窗口，也收不到点击或镜头事件。配对的聊天面板可以在其上标注地 点。
- Tile 是受支持的 Kaleidr 底图展示方式。
- 修改已挂载元素的
style-id不会产生效果。请使用handle.setStyle或插入新元素。 - 不存在专门的 Tile 密钥。其他 Kaleidr 产品使用的可发布密钥也可用于 Tile。
后续步骤
- 使用 Kaleidr 底图：分步教程。
- Tile 参考文档：全部选项、控制句柄、消息及错误。
- Chat：可搭配 Tile 地图使用的助手。
- 内容安全策略：嵌入 Tile 所需的三项指令。