`kaleidr.js` — loader

一个 script 标签即可安装 window.Kaleidr 并定义 <kaleidr-map> 元素：

<script src="https://cdn.kaleidr.com/embed/v1/kaleidr.js"></script>

该 façade 是一个轻量 loader。它只负责：版本、配置、脚本加载、产品注册表、密钥传递、接入方式选择、挂载生命周期、错误标准化和 dormancy flag。每个产品的实际行为都存在于其自己的 bundle 中，并在首次使用时通过 URL 延迟加载。

`Kaleidr.mount(target, options) → KaleidrHandle`

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map: myMap,
});

在产品 bundle 于后台加载期间，也会同步返回 handle；加载前的调用会进入队列，并在准备完成后执行。

选项

选项	类型	说明
`product`	`'chat' \| 'viewer' \| 'editor' \| 'tile'`	必填。选择 bundle + 默认接入方式。
`publishableKey`	`string`	Publishable 浏览器密钥（`kld_pk_live_…`）。chat/editor/tile 必填；viewer 不得接收密钥，传入密钥会以 `product_not_allowed` 拒绝。SDK 会在运行时将该密钥交换为短期、绑定 origin 的会话。
`apiKey`	`string`	`publishableKey` 的已弃用别名。也接受旧版 `kld_live_…` 密钥。
`shareId` / `mapId`	`string`	仅 Viewer。必填 — 省略时会在 bundle 加载时抛出错误。
`styleId`	`string`	Tile/editor。Tile：Kaleidr 底图 style id（默认使用 viewer 的 canvas 默认值）。Editor：style id 或完整 style URL — 省略时先应用组织保存的默认值，然后使用 `kaleidr-morning`。
`map`	map instance	Chat：要连接的页面内实时 Mapbox / MapLibre / Google 地图。
`mapTarget`	`string`	Chat：host map element 的 CSS selector（声明式路径）。
`contained`	`boolean`	仅 Chat。默认 `false`。将面板固定在 mount element 内，而不是浮动在 `document.body` 上 — 否则面板会脱离页面布局，看起来像是损坏。
`center` `zoom`		初始相机（viewer、editor、tile）。
`pitch` `bearing`		viewer、editor 和 tile 的初始相机。
`theme`	`object` or JSON object string	CSS-token 集合（例如 `{ '--kd-accent': '#2da84a' }`）。Chat 也支持通过 handle 实时更新。命名字符串 theme 不受支持；传入纯字符串会记录警告并被忽略。
`doorway`	`'iframe' \| 'attach'`	备用选项 — 覆盖产品默认值。
`base`	`string`	覆盖 bundle 加载所使用的 CDN origin（dev / self-host）。
`viewerBase`	`string`	Viewer/tile：iframe 加载的 origin。与 `base` 不同 — iframe 永远不会指向 CDN。
`tileBase`	`string`	Editor：用于解析目录中 `styleId` 值的 tile CDN。默认 `https://tile.kaleidr.com`。
`apiBase`	`string`	必须包含服务路径。默认 `https://api.kaleidr.com/inference-api`；像 `https://api.kaleidr.com` 这样的 bare origin 会在会话交换时返回 404。适用于 chat、editor 和 tile — 即任何执行会话交换的产品。
`enabled`	`boolean`	每次挂载的 dormancy 覆盖设置。

`KaleidrHandle`

handle 的结构是一个 superset — 每个产品只实现其能够支持的方法。请参阅 Handle matrix，了解每个方法在各产品中的作用。

interface KaleidrHandle {
  product: 'chat' | 'viewer' | 'editor' | 'tile';
  // Always present.
  destroy(): void;
  // Viewer, editor, tile: real. Chat: NO-OP (chat does not drive the map).
  setCamera?(camera): void;
  // Chat: live update (real). Editor: mount-time only; live update is a
  // follow-up SDK release. Viewer/tile: not applicable.
  setTheme?(theme): void;
  // Tile only. Not exposed on any other product.
  setStyle?(styleId: string): void;
}

目前调用不支持的方法会记录 [kaleidr] 警告并返回 — loader 不会抛出错误。该行为属于 v1 主版本别名的 contract。

`Kaleidr.init()`

升级 DOM 中已经存在的任何 <kaleidr-map>。加载时会自动调用；动态插入元素后请再次调用。

`Kaleidr.enable(on = true)`

SDK 默认处于启用状态 — 无需额外启用任何内容， quickstart 按照文档即可运行。

enable() 用作关闭开关：传入 false 会阻止 mount() 加载任何 bundle，因此您可以将 embed 放在同意横幅之后，或者在不移除 markup 的情况下在页面中停用它们。同一个开关也可以通过 window.__KALEIDR_EMBED_ENABLED__ = false（在 script 运行前）或每次挂载的 flag 属性 / enabled 选项使用。

`Kaleidr.version`

loader 的版本字符串。

覆盖 CDN base

对于本地开发或 self-hosting，请将 loader 指向另一个 origin：

<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn-dev.kaleidr.com';</script>

Kaleidr.mount(target, options) → KaleidrHandle​

选项​

KaleidrHandle​

Kaleidr.init()​

Kaleidr.enable(on = true)​

Kaleidr.version​

覆盖 CDN base​