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 不支持的句柄方法。 |
不支持的功能
- 点击、相机移动或选择事件，包括地点卡片和地点操作。
- 读取地图的相机、图层或数据。
- 向嵌入的地图添加自己的标记或图层，车辆图层除外。
- 通过嵌入内容更改底图或主题。