# @baidumap/jsapi-ui-kit

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

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

## 安装

```bash
npm install @baidumap/jsapi-ui-kit
```

## 使用前准备

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

## 引入方式

### ESM

```javascript
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('北京');
```

### 按需引入

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

### IIFE（无构建环境）

```html
<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`）。

```javascript
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`）。

```javascript
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 }`）。

```javascript
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`（清空结果）。

```javascript
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 变量」页面。

```javascript
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