跳到主要内容

快速开始

只需两行即可嵌入 Kaleidr 地图。

1. 添加 loader​

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

kaleidr.js 非常轻量 — 不包含 MapLibre 或 React。它会从 cdn.kaleidr.com/embed/v1/<product>.js 按需延迟加载您实际使用的产品 bundle。

2. 放置元素​

这两种方式都可在 Free 套餐中运行。Viewer 通过 share link 控制访问（完全不需要密钥）； Tile 使用仅限 maps / tile 的 Free publishable 密钥。

<!-- A published map — no key needed (share-link gated) -->
<kaleidr-map product="viewer" share-id="abcd1234" style="height:480px"></kaleidr-map>

<!-- A designed basemap — your publishable key, maps scope -->
<kaleidr-map product="tile" publishable-key="kld_pk_live_…" style-id="kaleidr-morning"
             style="height:480px"></kaleidr-map>

浏览器不会告诉您以下两个前提条件 — 请参阅 获取 API 密钥 获取 准确步骤：

  1. 您页面的 origin 必须位于密钥的 origin allowlist 中，否则 SDK 的 会话交换会以 session_origin_mismatch 拒绝。file:// 嵌入始终失败 — 请通过 HTTP(S) 提供。
  2. 您的 CSP 必须允许 SDK loader 和地图 iframe — 请参阅 Content Security Policy。

或以命令式方式挂载​

将 AI chat 连接到页面上已有的地图。Chat 需要 ai 作用域以及 Pro 或更高套餐 — Free 密钥无法创建 Chat 会话。 contained: true 会将面板固定在挂载元素内；如果没有它， 面板会移动到 document.body。

const handle = Kaleidr.mount('#chat', {
  product: 'chat',
  publishableKey: 'kld_pk_live_…',
  map: myMap, // your live Mapbox / MapLibre / Google instance
  contained: true,
});

// later: handle.destroy();

Kaleidr.mount(target, opts) 会同步返回一个 handle；产品 bundle 在后台加载，排队的调用会在加载完成后执行。注意： handle.setCamera(...) 在 chat 上是 no-op — chat handle 不会 控制地图相机。请使用您自己的地图实例的相机 API。

下一步​