@baidumap/jsapi-ui-kit

百度地图 JavaScript API 的 UI 组件库，提供地点检索、地点详情、路径规划等能力。仅面向浏览器，通过 JS 调用（非 Web Component）。

• 官方文档：https://bmap-uikit.bj.bcebos.com/docs/index.html

安装

npm install @baidumap/jsapi-ui-kit

使用前准备

• 页面需先加载 百度地图 JavaScript API 或 JSAPI GL（WebGL 版）。
• PlaceSearch 检索依赖地图实例（用于城市/投影等），请确保传入的 map 已创建；若使用 JSAPI GL，需确保 window.BMapGL 已就绪。
• PlaceAutocomplete 地点自动补全依赖地图实例（用于城市 ID 解析等），map 必传；组件不与地图做视野/打点联动。
• PlaceDetail 按 uid 拉取详情不依赖地图实例，map 为扩展预留。
• RoutePlan 路径规划依赖地图实例，当前一期仅对外开放驾车能力。

引入方式

ESM

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

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>

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

组件

PlaceSearch（地点检索）

在指定容器内展示检索列表，数据通过内部 service 直接请求。组件不与地图做视野/打点联动，可由开发者监听事件后自行联动。

支持的事件：load（检索完成，payload 为 PlaceSearchEventPoi[]）、select（用户点击某条结果，payload 为 PlaceSearchEventPoi）。

const search = new BMapUIKit.PlaceSearch('#panel', {
  map: map,
  pageCapacity: 10,
});

search.on('load', (list) => console.log(list));   // list: PlaceSearchEventPoi[]
search.on('select', (poi) => console.log(poi));   // poi: PlaceSearchEventPoi

search.search('北京');
search.searchNearby('餐厅', new BMapGL.Point(116.404, 39.915), 1000);
search.searchInBounds('酒店', { sw: new BMapGL.Point(116.3, 39.8), ne: new BMapGL.Point(116.5, 40) });

// 分页（仅 API，无内置翻页 UI）
search.prevPage();
search.nextPage();
search.goToPage(2);

search.destroy();

事件 payload：load 为 PlaceSearchEventPoi[]，select 为 PlaceSearchEventPoi（字段：title、address、uid、point、tel）。类型可从包内引入：import type { PlaceSearchEventPoi } from '@baidumap/jsapi-ui-kit'。

PlaceDetail（地点详情）

在指定容器内展示地点详情；按 uid 拉取详情使用内部 service。

支持的事件：load（详情加载并渲染完成，payload 为 PlaceDetailEventData）。

const detail = new BMapUIKit.PlaceDetail('#detail', { map: map });

detail.on('load', (data) => console.log(data));   // data: PlaceDetailEventData

detail.setPlace(poi);   // poi 来自检索结果（含 title/address/uid 等）
detail.setPlace('uid'); // 或传入 uid 字符串，内部拉取详情
detail.clear();
detail.destroy();

事件 payload：load 为 PlaceDetailEventData（字段：title、address、uid、point、tel）。类型可从包内引入：import type { PlaceDetailEventData } from '@baidumap/jsapi-ui-kit'。

PlaceAutocomplete（地点自动补全）

在指定容器内展示输入框与自动补全建议下拉列表，数据通过内部 service 直接请求。组件不与地图做视野/打点联动，由开发者监听事件后自行实现。

支持的事件：suggest（建议列表更新，payload 为 PlaceAutocompleteEventSuggestion[]）、select（用户选中某条建议，payload 为 PlaceAutocompleteEventSuggestion）、highlight（键盘导航高亮切换，payload 为 { from, to }）。

const ac = new BMapUIKit.PlaceAutocomplete('#autocomplete-container', {
  map: map,
  placeholder: '搜索地点',
  location: '北京',
  suggestionCount: 5, // 最多显示 5 条建议
});

ac.on('suggest', (list) => console.log(list));
ac.on('select', (item) => {
  console.log('选中:', item.name, item.point);
  if (item.point) {
    map.centerAndZoom(item.point, 16);
  }
});

// 手动触发检索
ac.search('百度大厦');

// 动态配置
ac.setLocation('上海');
ac.setCitylimit(true);

ac.destroy();

事件 payload：suggest 为 PlaceAutocompleteEventSuggestion[]，select 为 PlaceAutocompleteEventSuggestion（字段：name、address、city、district、point、uid、tag）。类型可从包内引入：import type { PlaceAutocompleteEventSuggestion } from '@baidumap/jsapi-ui-kit'。

RoutePlan（路径规划）

在指定容器内展示路径规划列表（一期仅对外开放驾车）。组件会基于内部服务请求路线，并返回归一化结果，便于开发者绘制路线或扩展交互。

支持的事件：result（搜索成功，payload 为 RoutePlanEventData）、error（搜索失败，payload 为 Error）、planselect（方案选中，payload 为 { type, planIndex, plan }）、clear（清空结果）。

const routePlan = new BMapUIKit.RoutePlan('#route-plan', {
  map: map,
  drivingOptions: { policy: DrivingPolicy.DEFAULT, alternatives: 1 },
});

routePlan.on('result', (data) => console.log(data));

routePlan.search({
  start: new BMapGL.Point(116.404, 39.915),
  end: new BMapGL.Point(116.305, 39.982),
});

事件 payload：result 为 RoutePlanEventData（字段：type、start、end、plans）。类型可从包内引入：import type { RoutePlanEventData } from '@baidumap/jsapi-ui-kit'。

主题系统

UI Kit 基于 CSS 自定义属性（CSS Variables）实现全局主题切换，通过 applyTheme() / registerTheme() 使用。内置预设：default（默认浅色）、dark（深色）、warm（暖色）、cool（冷色）。自定义主题只需覆盖部分变量，未指定的将沿用 :root 默认值。各变量含义、组件支持及完整说明见生成文档中的「主题系统与 CSS 变量」页面。

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

BMapUIKit.applyTheme('dark');        // 内置预设
BMapUIKit.applyTheme('default');     // 切回默认
BMapUIKit.registerTheme('brand', { '--bmap-ui-primary': '#7c3aed', /* ... */ });
BMapUIKit.applyTheme('brand');

License

MIT