本文说明如何通过手动开发或AI 辅助开发使用 @baidumap/jsapi-ui-kit。AI 开发可配合 Baidu Map JSAPI Skills 使用，让 AI 助手在对话中引用准确的 API 与示例。

一、手动开发

1. 安装

npm install @baidumap/jsapi-ui-kit

或使用 pnpm / yarn：

pnpm add @baidumap/jsapi-ui-kit
# 或
yarn add @baidumap/jsapi-ui-kit

2. 使用前准备

<!-- 2D 地图 -->
<script src="https://api.map.baidu.com/api?v=3.0&ak=你的AK"></script>

<!-- 或 WebGL 版 -->
<script src="https://api.map.baidu.com/api?v=1.0&type=webgl&ak=你的AK"></script>
  • 地图实例：PlaceSearch、PlaceAutocomplete、RoutePlan 依赖地图实例（如城市解析、投影等），请确保传入的 map 已创建；PlaceDetail 按 uid 拉取详情可不依赖 map。

3. 引入与基本用法

ESM（推荐）

import BMapUIKit from '@baidumap/jsapi-ui-kit';
import '@baidumap/jsapi-ui-kit/dist/css/jsapi-ui-kit.css';

// 假设 map 为已创建的 BMapGL.Map 或 BMap.Map
const search = new BMapUIKit.PlaceSearch('#panel', { map: map });
search.search('北京');

按需引入

import { PlaceSearch, PlaceDetail, PlaceAutocomplete, RoutePlan } from '@baidumap/jsapi-ui-kit';
import '@baidumap/jsapi-ui-kit/dist/css/jsapi-ui-kit.css';

IIFE（无构建环境）

<script src="https://api.map.baidu.com/api?v=3.0&ak=你的AK"></script>
<link rel="stylesheet" href="https://unpkg.com/@baidumap/jsapi-ui-kit/dist/css/jsapi-ui-kit.css">
<script src="https://unpkg.com/@baidumap/jsapi-ui-kit/dist/jsapi-ui-kit.iife.js"></script>
<script>
  var search = new BMapUIKit.PlaceSearch('panel', { map: map });
  search.search('天安门');
</script>

样式需单独引入，否则组件无默认样式。

4. 本地运行示例

仓库内提供示例页面，便于调试与参考：

  1. 克隆或下载本仓库，在项目根目录执行 npm install（或 pnpm install）。
  2. 在 index.html（或示例所用 HTML）中将 YOUR_BAIDU_MAP_AK 替换为你的百度地图 AK。
  3. 执行：
npm start

浏览器会打开示例页，可体验 PlaceSearch、PlaceDetail、PlaceAutocomplete、RoutePlan 及主题切换。示例使用 JSAPI GL（BMapGL），地图全屏，检索面板浮层展示；修改源码后刷新即可看到效果。

二、AI 辅助开发

通过 AI 助手（如 Claude、Cursor）开发时，可配合 Baidu Map JSAPI Skills，让 AI 在回答中引用本库与百度地图 JSAPI 的准确文档与示例，减少手查文档、提高代码正确性。

1. 什么是 JSAPI Skills

JSAPI Skills 是百度地图 JSAPI 的 AI 技能库，包含：

Skill 说明
bmap-jsapi-gl 百度地图 JSAPI WebGL（BMapGL/BMap）：地图初始化、覆盖物、事件、路线、地理编码等，适用于 2D/2.5D 地图开发。
bmap-jsapi-three 百度地图 JSAPI Three（MapVThree）：基于 three.js 的 2D/3D 地图可视化，适用于数字孪生、WebGIS 等。
jsapi-ui-kit 本 UI 组件库：PlaceSearch、PlaceDetail、PlaceAutocomplete、RoutePlan 等组件的 API 与使用说明。

AI 会根据对话内容自动加载对应 Skill 下的参考文档，生成符合官方用法的代码。

2. 注册 Skill（让 AI 能引用文档）

方式一：克隆仓库并创建符号链接（推荐）

git clone https://github.com/baidu-maps/jsapi-skills.git
cd jsapi-skills

Claude Desktop（本地）

  • 技能目录一般为：~/.claude/skills/
  • 建议用符号链接注册，便于后续拉取更新：
ln -sfn "$(pwd)/bmap-jsapi-gl" ~/.claude/skills/bmap-jsapi-gl
ln -sfn "$(pwd)/bmap-jsapi-three" ~/.claude/skills/bmap-jsapi-three
ln -sfn "$(pwd)/jsapi-ui-kit" ~/.claude/skills/jsapi-ui-kit

也可直接将上述三个文件夹复制到 ~/.claude/skills/。

Cursor

  • 技能目录一般为：~/.cursor/skills-cursor/
  • 建议用符号链接注册：
ln -sfn "$(pwd)/bmap-jsapi-gl" ~/.cursor/skills-cursor/bmap-jsapi-gl
ln -sfn "$(pwd)/bmap-jsapi-three" ~/.cursor/skills-cursor/bmap-jsapi-three
ln -sfn "$(pwd)/jsapi-ui-kit" ~/.cursor/skills-cursor/jsapi-ui-kit

或将三个文件夹复制到 ~/.cursor/skills-cursor/。

方式二：仅使用 jsapi-ui-kit

若只开发本 UI 组件库相关功能，可只注册 jsapi-ui-kit；涉及地图初始化、覆盖物、事件等时，建议同时注册 bmap-jsapi-gl。

3. 在对话中触发 Skill

在提问或描述需求时，提及与百度地图、本库相关的关键词，AI 会自动加载对应 Skill 的文档并据此回答，例如：

  • 「用 BMapGL 创建一个地图，并加上 PlaceSearch」
  • 「jsapi-ui-kit 的 PlaceDetail 怎么监听 load 事件？」
  • 「用 百度地图 JSAPI 做地点检索，并展示详情」
  • 「@baidumap/jsapi-ui-kit 的 PlaceAutocomplete 如何限制城市？」

推荐在问题中直接写出「Baidu Map」「BMapGL」「jsapi-ui-kit」「PlaceSearch」「PlaceDetail」「PlaceAutocomplete」等，以便更稳定地命中 jsapi-ui-kit 与 bmap-jsapi-gl 的 Skill。

4. 参考链接

Settings

Member Visibility

On This Page

一、手动开发二、AI 辅助开发