`<kaleidr-map>` 元素

<kaleidr-map> 是声明式挂载 Kaleidr 产品的方式。你在 HTML 中写入带属性的元素，它进入文档时自动挂载，离开文档时自动清理。该元素由 kaleidr.js 定义，因此页面必须加载此脚本。

<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>

这个元素是一个轻量封装：将自身属性转换为选项，并在自身上调用 Kaleidr.mount。元素能做到的事情都能通过 Kaleidr.mount 完成，反过来却不一定：元素无法接收实时地图对象，也不会暴露句柄。

适合使用元素的情况	适合使用 `Kaleidr.mount` 的情况
嵌入内容是静态 HTML。	需要通过句柄调用 `setCamera`、`setStyle`、`setTheme` 或 `destroy`。
CMS 或模板负责生成 HTML。	要把 Chat 连接到自己的地图，需要传入 `map` 选项。
希望从文档移除元素时自动清理。	由框架控制组件的挂载与卸载时机。

属性

属性名称使用 kebab-case，对应的挂载选项使用 camelCase。

属性	挂载选项	产品	必需	默认值	挂载后监听	说明
`product`	`product`	全部	是	无	否	`chat`、`viewer`、`editor` 或 `tile`。
`publishable-key`	`publishableKey`	chat、editor、tile	是，除非 Chat 使用已发布地图	无	否	你的 `kld_pk_…` 密钥。Viewer 不使用。
`share-id`	`shareId`	viewer、chat	Viewer：是	无	否	Viewer：已发布地图 ID。无密钥的 Chat：提供聊天功能的已发布地图。
`map-id`	`mapId`	viewer	否	无	否	`share-id` 的别名。
`style-id`	`styleId`	tile、editor	Tile 建议设置	组织默认底图；Editor 之后退回 `kaleidr-morning`	否	底图样式 ID 或样式 URL。
`map-target`	`mapTarget`	chat	否	无	否	CSS 选择器，指向助手要控制的 Viewer 或 Tile `<kaleidr-map>` 元素。
`contained`	`contained`	chat	否	关闭	否	将面板停靠在此元素内部，该元素需设置定位和尺寸。
`lang`	`lang`	chat	否	若 `<html lang>` 是格式正确的语言标记，则使用它，否则为英语	否	面板回答所用语言，使用 BCP 47 标记，如 `en`、`ko` 或 `pt-BR`。参阅Chat 语言。
`chat-title`	`title`	chat	否	面板自身标题	否	聊天窗口标题。属性是 `chat-title` 而不是 `title`；HTML 元素的 `title` 是悬停提示。
`placeholder`	`placeholder`	chat	否	面板自身的占位文字	否	输入框的占位提示。
`layout`	`layout`	viewer	否	`map`	否	`bar` 挂载聊天栏；聊天栏也会读取 `chat-title`、`placeholder`、`theme` 和 `lang`，但有自己的默认值，参阅 Viewer 选项。`locator` 和 `listings` 在地点资料库集合的列表旁显示地图，参阅地点布局。`guide` 在场所地图旁打开聊天，参阅导览布局。`live` 显示车辆和今天的站点，参阅实时布局。
`collection`	`collection`	viewer 门店查找、房源列表、导览和实时	否	地图绘制的第一个与布局类型相符的集合	否	要列出的集合的 ID；在 `live` 上为车辆集合的 ID。
`stops`	`stops`	viewer 实时	否	地图绘制的第一个站点集合	否	站点集合的 ID。
`filters`	`filters`	viewer 门店查找和房源列表	否	集合的全部筛选	否	要显示的访客筛选，以 `\|` 分隔：`search`、`category`、`price`、`beds`、`baths`、`open_now`。
`card`	`card`	viewer	否	`auto`	否	`compact` 地点卡片只显示标题、副标题和操作。
`prompt`	`prompt`	viewer	否	无	否	地图打开时要向地图的 Kaleidr AI 提出的问题；在聊天栏上则是输入框的预填文本。
`prompt-param`	`promptParam`	viewer	否	无	否	当访客来自同一来源的页面时，从页面 URL 的该查询参数读取 `prompt`。
`prompts`	`prompts`	viewer 聊天栏	否	无	否	示例问题，以 `\|` 分隔。
`accent`	`accent`	viewer 聊天栏	否	`#2da84a`	否	CSS 颜色。
`results-url`	`resultsUrl`	viewer 聊天栏	否	无	否	将访客带到该页面，并附带 `?q=<question>`。
`center`	`center`	viewer、tile、editor	否	产品默认值	是	`"longitude,latitude"`，例如 `"-0.1276,51.5072"`。
`zoom`	`zoom`	viewer、tile、editor	否	产品默认值	是	数字。Viewer 和 Tile 挂载时仅在同时提供 `center` 时才使用。
`pitch`	`pitch`	viewer、tile、editor	否	产品默认值	是	倾斜角，单位为度。
`bearing`	`bearing`	viewer、tile、editor	否	产品默认值	是	旋转角，单位为度。
`theme`	`theme`	chat、editor	否	无	是（仅 Chat 会应用）	JSON 对象字符串。Chat 使用 CSS 自定义属性；Editor 使用17 个主题字段。
`flag`	`enabled`	全部	否	无	否	每个元素的启用开关。
`base`	`base`	全部	否	`https://cdn.kaleidr.com`	否	产品脚本包来源。仅允许 Kaleidr CDN（`https://cdn.kaleidr.com`）、加载 `kaleidr.js` 时的来源或页面本身的来源，其他值将被忽略并记录警告。参阅基础地址覆盖规则。
`viewer-base`	`viewerBase`	viewer、tile	否	`https://map-embed.kaleidr.com`	否	iframe 加载来源。
`api-base`	`apiBase`	chat、editor、tile	否	`https://api.kaleidr.com/inference-api`	否	会话交换和产品请求的目标地址。必须包含 `/inference-api`。
`tile-base`	`tileBase`	editor	否	`https://tile.kaleidr.com`	否	样式 ID 的解析主机。

api-key 是 publishable-key 的已弃用别名。四种 …-base 属性仅用于测试其他部署，生产环境不需要。

布尔属性

flag 和 contained 会被解析为布尔值：

写法	解释结果
`contained`（不带值）、`contained=""`	true
`"true"`、`"1"`、`"yes"`、`"on"`	true
`"false"`、`"0"`、`"no"`、`"off"`	false
不存在该属性	未设置
其他任何值	忽略并在控制台警告

解析时不区分大小写，也忽略词语前后的空格，所以 flag="False" 仍会关闭元素。由于空值属性表示真值，模板输出 flag="" 会将元素启用。请显式输出 false。

数字及相机属性

zoom、pitch 和 bearing 按数字解析。center 是两个以逗号分隔的数字，经度在前。解析失败的值会被静默忽略，并使用产品默认值。

挂载后的属性

元素会在进入文档时读取一次属性。之后仅监听五个属性：

更改的属性	viewer	tile	editor	chat
`center`、`zoom`、`pitch`、`bearing`	地图立即跳转到新相机位置。	地图立即跳转到新相机位置。	地图立即跳转到新相机位置。	控制台警告，不执行操作。
`theme`	控制台警告。	控制台警告。	控制台警告，Editor 只在挂载时读取主题。	更新面板样式。
任何其他属性	无效果。	无效果。	无效果。	无效果。

通过属性更改相机永远不会产生动画。需要动画时，请通过 Kaleidr.mount 挂载并调用 handle.setCamera({ …, duration: 800 })。

修改其中一个相机属性时，元素会发送它当前拥有的所有相机属性。若只修改 zoom，而元素还设置了 center，该中心点也会重新应用。

若要更改 share-id、style-id、publishable-key、product、flag、contained、lang、chat-title 或 placeholder，应替换元素：移除后用新的属性重新插入。Tile 可调用 handle.setStyle 在原位切换样式，但仅适用于通过 Kaleidr.mount 挂载的地图。

// Show a different published map in the same place.
const old = document.querySelector('kaleidr-map');
const next = old.cloneNode(false);
next.setAttribute('share-id', 'ANOTHER_MAP_ID');
old.replaceWith(next);

生命周期

事件	元素的行为
进入文档	读取属性并挂载。Chat、Editor 和 Tile 会开始交换会话。
在 `kaleidr.js` 加载前已位于文档中	先不操作，脚本加载后才挂载。
离开文档	销毁挂载，清理自身添加的内容并停止会话续期。
重新进入文档	重新读取属性、挂载，并开启新的会话交换。
被移动到另一父元素下	先离开再进入：先销毁再挂载。
缺少 `product` 或值不是四种产品之一	记录 `[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"` 且不挂载。之后设置 `product` 不会产生效果。

由此产生以下注意事项：

插入元素之前先设置属性。 如果通过 JavaScript 创建元素，请先设置全部属性，再将其添加到文档。先插入的话，会使用当时已有的属性立即挂载。

const el = document.createElement('kaleidr-map');
el.setAttribute('product', 'tile');
el.setAttribute('publishable-key', 'kld_pk_live_…');
el.setAttribute('style-id', 'kaleidr-night');
el.style.cssText = 'display:block; height:480px';
document.getElementById('slot').appendChild(el); // mounts here

重新挂载不是免费的。 Tile 再挂载会多计一次地图加载，Editor 会丢失编辑结果，Chat 会开启新对话。框架中的列表重新渲染等代码可能重建或重排 DOM 节点，悄然触发这些行为。参阅框架集成。
隐藏的元素仍会挂载。 display:none 不会延迟挂载，关闭的标签面板中的 Tile 仍会启动会话。
元素会显示其子内容，直到地图替换它们。 元素内部的内容会显示；Viewer 和 Tile 加载后会以 iframe 替换这些内容，因此子内容可以充当加载占位符，挂载失败或被启用开关阻止时仍作为备用显示。Chat 和 Editor 不会移除子内容。若不需要，请保持元素为空。

尺寸

<kaleidr-map> 默认是 display:block，因此能够设置 height：

<kaleidr-map product="viewer" share-id="YOUR_MAP_ID"
             style="height:480px"></kaleidr-map>

关于此默认值的三个要点：

你的 display 设置始终优先。 内联样式、样式表规则及 hidden 属性都会覆盖默认值。如果 CSS 将元素设为 display:inline，height 就不再起作用。
无需放宽 Content Security Policy。 默认行为不是通过 <style> 标签或 style 属性提供的，因此即使没有 'unsafe-inline' 也能正常工作。
Safari 16.4 之前不支持此默认行为。 元素保持内联，并忽略 width 和 height。所以示例会保留 display:block，并将其写在 style 属性中：在支持默认值的浏览器中无害，在旧版 Safari 中则是设置尺寸所必需的。

因此，本文档使用以下写法：

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

或者在整个网站的样式表中统一设置：

kaleidr-map { display: block; height: 480px; }

产品	尺寸行为
viewer、tile	iframe 宽度占元素的 100%。若挂载时元素已有高度，iframe 高度占其 100%；否则固定为 500 像素。挂载时会设置 `position:relative`（若没有内联定位）和 `overflow:hidden`。
editor	编辑器占元素宽高的 100%；没有高度时不可见。
chat	没有 `contained` 时，面板是视口左上角的固定窗口，元素大小无关紧要。有 `contained` 时，面板位于元素内部，元素需有 `position:relative`（或其他定位方式）及尺寸。

500 像素的备用高度只在挂载时决定一次。若当时元素没有高度，即使之后设置尺寸，iframe 仍保持 500 像素高。

如果 Content Security Policy 禁止内联 style 属性，请在样式表中设置尺寸。元素自身的块级默认行为不受该策略影响。

句柄矩阵

该元素不会暴露句柄。若要调用这些方法，请使用能返回句柄的 Kaleidr.mount 进行挂载。

方法	chat	viewer	editor	tile
`destroy()`	是	是	是	是
`setCamera(camera)`	不支持	是	是	是
`setTheme(theme)`	是	不支持	不支持	不支持
`setStyle(style)`	不支持	不支持	不支持	是
`send(text)`	不支持	是	不支持	不支持
`setFilters(filters)`	不支持	是	不支持	不支持
`showVehiclesLayer(layer)`	不支持	是	不支持	不支持
`clearVehiclesLayer()`	不支持	是	不支持	不支持

每个句柄都包含所有这些方法。标记为“不支持”的方法在调用时不会执行操作，只会记录控制台警告，不会抛出异常。这属于 /embed/v1 契约的一部分。

各产品的情况：

chat：setTheme 更改面板外观。setCamera 不支持，因为 Chat 不拥有地图；助手在回答时会移动其连接的地图，而你自己的代码应使用地图库 API 来移动它。
viewer：setCamera 移动已发布地图。setFilters 设置地点布局的访客筛选。showVehiclesLayer 在地图上绘制你自己的车辆，clearVehiclesLayer 将其移除，参阅车辆图层。
editor：setCamera 移动编辑器的地图。主题和底图在挂载时确定。
tile：setCamera 移动地图，setStyle 直接切换底图。

setCamera 接收 { center, zoom, pitch, bearing, duration }。所有字段均为可选，center 是 [longitude, latitude]，duration 单位为毫秒。完整说明见 kaleidr.js。

Chat 与 `map-target`

Chat 可以控制两种地图：

你自己的地图（Mapbox GL JS、MapLibre GL JS、Google Maps 或 Leaflet）。无法在属性中直接写入地图对象，因此应使用 Kaleidr.mount，并传入 map 选项。参阅Chat 参考。

同一页面上的 Kaleidr Viewer 或 Tile 元素。 使用 CSS 选择器让 map-target 指向它：

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               style="display:block; height:480px"></kaleidr-map>

  <kaleidr-map product="chat" publishable-key="kld_pk_live_…" contained
               map-target="#basemap"
               style="display:block; position:absolute; inset:0; z-index:1; pointer-events:none"></kaleidr-map>
</div>

两个元素的顺序无关紧要。Chat 会在实际需要时查找目标。

没有 map 或 map-target 时，Chat 是不带地图的聊天面板。

容器和 Chat 元素的样式将面板放置在地图之上。各项声明见主题与布局。已发布地图上的 Chat 见已发布地图上的 Chat。

控制台消息

消息	含义
`[kaleidr] <kaleidr-map> requires product="chat\|viewer\|editor\|tile"`	`product` 缺失或拼写错误，元素不会挂载。
`[kaleidr] <attribute>="<value>" is not a recognized boolean — the attribute is IGNORED. Use <attribute>="true" / "false" (or omit it).`	`flag` 或 `contained` 的值不在允许范围内。消息会指出是哪个属性：`flag="…"` 或 `contained="…"`。
`[kaleidr] base "<value>" is IGNORED — bundles load from https://cdn.kaleidr.com. A base must be the Kaleidr CDN, the origin kaleidr.js was loaded from, or this page's own origin.`	`base` 指定了不被接受的来源。产品仍从默认 CDN 加载。
[kaleidr] embed is disabled — this mount passed `enabled: false` (or `flag="false"`). …	元素被其 `flag` 阻止挂载。移除此限制并替换元素。
`[kaleidr] setCamera() is not supported on product "chat" — the call is a no-op. …`	Chat 元素的相机属性发生变化。
`[kaleidr] setTheme() is not supported on product "<product>" — the call is a no-op. …`	Viewer、Tile 或 Editor 元素的 `theme` 属性发生变化。

挂载失败时，控制台消息格式为 [kaleidr:<product>] …。完整说明见 kaleidr.js。

不支持的功能

事件：元素不会派发 DOM 事件。
属性或方法：元素没有 setCamera 方法、handle 属性或 ready Promise。
重新读取属性：除了五个受监听属性，挂载后的变化都会被忽略。

属性​

布尔属性​

数字及相机属性​

挂载后的属性​

生命周期​

尺寸​

句柄矩阵​

Chat 与 map-target​

控制台消息​

不支持的功能​

相关文档​

属性