Tile 参考

product="tile" 根据样式 ID 显示 Kaleidr 底图。SDK 将可发布密钥交换为 Tile 会话，然后将挂载目标的内容替换为加载 https://map-embed.kaleidr.com/?style=<style> 的 iframe。地图在该 iframe 内绘制。

Kaleidr 通过会话验证密钥、权限范围及页面来源，统计地图加载次数，并提供组织的默认底图。会话不会传给 iframe。iframe URL 只包含样式 ID 和指定的相机参数（camera、pitch、bearing），不包含可发布密钥或会话令牌；iframe 内的地图也不会使用它们发出请求。

密钥	可发布密钥（kld_pk_live_…），必填。
权限范围	maps，新密钥默认具有此权限。
套餐	所有套餐，包括 Free。
渲染位置	来自 https://map-embed.kaleidr.com 的 iframe。
计量	每个 Tile 会话计一次地图加载。
CSP	script-src https://cdn.kaleidr.com、connect-src https://api.kaleidr.com、frame-src https://map-embed.kaleidr.com。

分步教程请参阅使用 Kaleidr 底图。

挂载

使用元素：

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>
<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             center="-0.1276,51.5072" zoom="11"
             style="display:block; height:480px"></kaleidr-map>

使用 JavaScript：

const handle = Kaleidr.mount('#basemap', {
  product: 'tile',
  publishableKey: 'kld_pk_live_…',
  styleId: 'kaleidr-morning',
  center: [-0.1276, 51.5072],
  zoom: 11,
});

选项

挂载选项	属性	类型	默认值	必需	说明
product	product	'tile'	无	是	选择 Tile 产品。
publishableKey	publishable-key	字符串	无	是	kld_pk_… 密钥，具有 maps 权限。服务器密钥（kld_sk_…）在浏览器中会被拒绝，不会发送请求。
styleId	style-id	字符串	若已设置，则为组织默认底图	建议提供	下表中的样式 ID，或样式文档的完整 https:// URL。必须符合 ^[A-Za-z0-9._:/~-]{1,200}$。
center	center	[longitude, latitude]；属性格式为 "longitude,latitude"	样式默认视图	否	初始中心点。
zoom	zoom	数字	样式默认视图	否	初始缩放级别；挂载时若没有 center 则忽略。
pitch	pitch	数字，单位为度	样式默认视图	否	初始倾斜角。
bearing	bearing	数字，单位为度	样式默认视图	否	初始旋转角。
apiBase	api-base	URL	https://api.kaleidr.com/inference-api	否	会话交换请求的目标地址。必须包含 /inference-api 路径，生产环境通常无需设置。
viewerBase	viewer-base	URL	https://map-embed.kaleidr.com	否	iframe 的加载来源；仅使用来源部分。它是地图页面的主机，而非地图数据主机。
base	base	URL	https://cdn.kaleidr.com	否	SDK 加载 tile.js 的来源。仅使用来源，且只接受基础地址覆盖规则允许的来源。
enabled	flag	布尔值	无	否	每次挂载的启用开关。

shareId、theme、map、mapTarget、contained 和 tileBase 对 Tile 挂载无效。

样式 ID

style-id	外观
kaleidr-morning	明亮：白色地面、青色水域、白色道路。
kaleidr-afternoon	中等色调地面、绿色植被和灰色道路。
kaleidr-evening	黄金时刻：温暖的沙色与橄榄色。
kaleidr-night	深海军蓝和炭黑色，配以琥珀色高速公路。
kaleidr-plain	白色画布，显示边界和地点标签。缩放级别达到 15 后显示 3D 建筑。
kaleidr-editorial	无标签的午后配色，适合小型或装饰性地图。

规则：

• ID 必须完全匹配且区分大小写，没有简写别名。
• 若省略 styleId，嵌入内容使用通过会话返回的组织默认底图。若未设置默认底图，iframe 显示“Couldn't find a map id in the URL.”。建议显式设置 styleId，避免依赖账户配置。
• 显式传入的 styleId 始终优先于组织默认设置。
• 不存在的 ID 会导致 iframe 空白，并发送kaleidr-embed:error 消息，错误代码为 maplibre_error。
• 值中包含不允许的字符时不会挂载。控制台显示 [kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.。因此样式 URL 不能包含查询字符串。

相机

初始相机以样式默认视图为基础，传入的每个字段分别覆盖样式中的对应值。若样式没有默认视图，则显示整个世界：中心点 [0, 20]、缩放级别 2、无倾斜、无旋转。

• center 的经度在前：[-0.1276, 51.5072] 表示伦敦。
• 挂载时，仅在提供 zoom 时同时包含 center 才会生效。
• pitch 和 bearing 不依赖 center。

尺寸

• iframe 宽度为挂载目标的 100%，无边框且带圆角。
• 若挂载时目标已有高度，iframe 高度为其 100%；否则固定为 500 像素。
• 挂载过程会替换目标的子元素，并设置 position:relative（目标没有内联定位时）及 overflow:hidden。
• <kaleidr-map> 默认使用 display:block，因此可以设置 height。请明确指定高度。示例仍写有 display:block，以兼容 Safari 16.4 之前无法自动采用块级布局的情况。

句柄

Kaleidr.mount 同步返回句柄。所有产品的情况请查看句柄矩阵。

成员	Tile 中的行为
handle.product	'tile'
handle.setCamera(camera)	移动地图相机。
handle.setStyle(style)	原地切换底图。
handle.setTheme(theme)	不支持；记录警告且不执行操作。
handle.destroy()	移除 iframe 并停止续期会话。

setStyle(style)

handle.setStyle('kaleidr-night');

接受样式 ID 或完整的样式 URL，解析方式与挂载时的 styleId 相同。iframe 不重新加载，相机位置保持不变，也不会新增地图加载计数。只有 Tile 支持 setStyle。

setCamera(camera)

handle.setCamera({
  center: [2.3522, 48.8566], // [longitude, latitude]
  zoom: 12,
  pitch: 45,
  bearing: -20,
  duration: 1200,            // milliseconds
});

字段	类型	说明
center	[number, number]	经度、纬度。
zoom	数字	缩放级别。与挂载时不同，这里 zoom 不需要同时提供 center。
pitch	数字	倾斜角，单位为度。
bearing	数字	旋转角，单位为度。
duration	数字	动画时长，单位为毫秒。省略或设为 0 时立即跳转。

所有字段均可选；未提供的字段保留当前值。

调用时机

你随时都可以调用 setCamera 和 setStyle，只要 Kaleidr.mount 已返回，甚至可以紧接着在下一行调用。地图尚未就绪时的调用会按顺序暂存，并在 iframe 内地图报告就绪后执行。最多保留最近 256 次调用。若在有限等待时间内仍未收到就绪报告（通常是 iframe 加载后 10 秒），暂存调用仍会发出，同时出现一条控制台警告。不必先等待 kaleidr-embed:ready。若要指定地图打开时的视图和样式，直接使用挂载选项效果更好，可避免加载后再次切换。

挂载后的元素属性

对于已挂载的 <kaleidr-map product="tile">，更改 center、zoom、pitch 或 bearing 会无动画地移动地图。更改 style-id、publishable-key 或任何其他属性均无效果。

iframe 消息

// The basemap drew for the first time.
{ type: 'kaleidr-embed:ready', id: string, source: 'tile' }

// Something failed to draw.
{ type: 'kaleidr-embed:error', id: string, code: 'maplibre_error', message: string }

// No style: none was passed, and the organization has no default basemap.
{ type: 'kaleidr-embed:error', id: null, code: 'no_id', message: string }

id 是传入的样式 ID 或 URL。若为 no_id，其值为 null，iframe 显示“Couldn't find a map id in the URL.”，且不会发送 ready。

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://map-embed.kaleidr.com') return;
  if (event.source !== target.querySelector('iframe')?.contentWindow) return;
  const msg = event.data;
  if (msg?.type === 'kaleidr-embed:ready') onReady(msg);
  if (msg?.type === 'kaleidr-embed:error') onError(msg);
});

• 地图绘制完成后只发送一次 ready；执行 setStyle 后不会再次发送。
• maplibre_error 可能在 ready 之前或之后多次出现。
• iframe 使用 loading="lazy"，因此只有接近可视区域后才会加载并发送消息。
• 会话被拒绝时不会创建 iframe，所以也不会发送消息；请查看控制台错误。
• iframe 还会发送 type 以 kaleidr-embed: 开头的其他消息。SDK 利用这些消息将 Chat 连接到地图，但它们不属于公开契约。

会话与计量

每次 Tile 挂载时，SDK 会发送

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
x-api-key: kld_pk_live_…
content-type: application/json

{"product":"tile"}

并接收

{
  "session_token": "kld_sess_live_…",
  "expires_in": 900,
  "product": "tile",
  "basemap_style_id": "kaleidr-morning"
}

basemap_style_id 表示组织默认底图；如果未设置，则为 null。

每次成功交换 "product":"tile" 会为组织统计一次地图加载。交换发生在以下时机：

时机	计数
首次挂载	1
只要持续挂载，会话到期前 90 秒	每次 1
标签页重新可见，且会话已经到期或将在 90 秒内到期	1
调用 destroy() 后重新挂载，或重新插入被移除的元素	1

注意：

• 续期失败后每 30 秒重试一次；已经显示的地图不会被移除。
• 首次交换失败则挂载失败，不会自动重试。需要重新挂载。
• destroy() 会停止会话续期。
• 相机移动、切换样式和访问者交互均不计入地图加载。

Tile 会话交换会因为下列第一项适用原因而被拒绝：

状态	detail	原因
403	publishable_key_required	密钥不是可发布密钥。
403	origin_required	请求未携带来源。
403	origin_not_allowed	页面来源不在密钥允许的来源列表中。
403	product_not_allowed	密钥仅允许其他产品。
403	tier_capability_not_allowed	当前套餐不允许此产品。
403	insufficient_scope	密钥缺少 maps 权限。
429	map_load_quota_exceeded	组织的地图加载配额已用尽。

在上述检查之前，若平台关闭了会话交换，会返回 404 sessions_disabled；若平台出现故障，可能返回 503 sessions_not_configured。两者均不是密钥造成的。全部错误代码见错误参考。

与 Chat 配合使用

Chat 挂载可以控制 Tile 元素。给 Tile 元素分配一个 id，并将 Chat 的 map-target 属性（挂载选项 mapTarget）指向它：

<div style="position:relative">
  <kaleidr-map id="basemap" product="tile" publishable-key="kld_pk_live_…"
               style-id="kaleidr-morning"
               style="display:block; height:560px"></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>

在 Tile 地图中，助手可添加带弹窗的图钉、将相机调整到地点范围，并绘制路线、城市等区域的轮廓以及实时车辆位置。操作指南请参阅使用 Kaleidr 底图，布局见主题与布局，Chat 选项见Chat 参考。

控制台消息

消息	含义
[kaleidr] <kaleidr-map> requires product="chat|viewer|editor|tile"	元素缺少有效的 product，不会挂载。
[kaleidr:tile] kaleidr session exchange failed (<status>)	会话交换遭拒。原因在网络面板的响应中：403 时查看 detail，map_load_quota_exceeded 也在其中；429 时查看 error，例如 rate_limited。
…/sdk/sessions 出现 CORS 错误，随后出现 [kaleidr:tile] 请求错误	密钥未知或已撤销，或来源不被允许。来源遭拒时，响应不包含 CORS 头，浏览器会向 SDK 隐藏响应。
[kaleidr:tile] Kaleidr: a server key (kld_sk_…) must never be used in the browser — it is a standing secret. Use your publishable key (kld_pk_…) here and keep the server key server-side.	传入了服务器密钥；不会发送请求。
[kaleidr:tile] Kaleidr tile: invalid style "…" — must match ^[A-Za-z0-9._:\/~-]{1,200}$.	styleId 包含非法字符。
[kaleidr:tile] mount target not found: <selector>	Kaleidr.mount 没有找到匹配选择器的元素。
[kaleidr:tile] [kaleidr] failed to load https://cdn.kaleidr.com/embed/v1/tile.js	无法加载 Tile 脚本包。
[kaleidr] setTheme() is not supported on product "tile" — the call is a no-op. …	调用了 Tile 不支持的句柄方法。
[kaleidr] setStyle() IS supported on product "tile", but this mount did not expose it, so the call did nothing. …	浏览器缓存了旧版 tile.js。请绕过缓存重新加载。

不支持的功能

• 向地图添加自己的标记、图层或弹窗。
• 点击、相机移动或选择事件。
• 读取当前相机参数。
• 不使用 iframe 直接运行地图。

相关文档

• 使用 Kaleidr 底图
• <kaleidr-map> 元素
• 加载器 kaleidr.js
• 配额与速率限制