tg-map-echarts 4.3.0

package/docs/migration-from-bmap.md

@@ -0,0 +1,508 @@
+# 从 ECharts `bmap` 迁移到 `tgMap`
+
+本文介绍如何把使用 ECharts 官方 `bmap` 扩展的图表迁移到 `tg-map-echarts`。迁移后，ECharts 的热力图、散点图和自定义图形仍由 ECharts 渲染，底图则通过 `tg-map-core` 创建，可以在 Baidu、Google 和 Talks 三种地图引擎之间复用同一份图表配置和业务坐标。
+
+## 迁移要点
+
+| `bmap` | `tgMap` |
+| --- | --- |
+| `import 'echarts/extension/bmap/bmap'` | `echarts.use(TgMapExtension)` |
+| 业务代码手动加载百度地图 SDK | `await loadCachedMap(engine)` |
+| 顶层 `bmap` 配置 | 顶层 `tgMap` 配置 |
+| `coordinateSystem: 'bmap'` | `coordinateSystem: 'tgMap'` |
+| `center: [lng, lat]` | `mapOptions.center: { lng, lat, coord }` |
+| `zoom` | `mapOptions.zoom` |
+| `roam` | `mapOptions.gestureHandling` |
+| 业务数据提前转换为 BD-09 | 保留原始坐标，并设置 `dataCoordType` |
+| `getBMap()` | `getMap()`，返回 `tg-map-core` 的统一地图对象 |
+| `bmaproam` | `tgmaproam` |
+
+`heatmap`、`effectScatter`、`scatter`、`lines` 和 `custom` 等 series 的数据结构及样式配置通常不需要改变，只需替换 `coordinateSystem`。
+
+## 1. 安装依赖
+
+```sh
+pnpm add echarts tg-map-core tg-map-echarts
+```
+
+`tg-map-echarts` 的版本号与 `tg-map-core` 保持一致，建议安装相同的明确版本，避免加载两份不同版本的 `tg-map-core`。以 `4.2.12` 为例：
+
+```sh
+pnpm add tg-map-core@4.2.12 tg-map-echarts@4.2.12
+```
+
+如果项目使用的 tg-map Vue 组件库已经重新导出了同一版本的 `tg-map-core`，可以继续从 Vue 组件库导入公共地图类型和工具；但 `tg-map-echarts` 仍需单独安装。可以通过 `pnpm why tg-map-core` 确认项目只解析到兼容版本；如果存在多个模块实例，从 Vue 插件写入的地图配置可能无法被 `tg-map-echarts` 依赖的实例读取。
+
+## 2. 注册扩展
+
+`bmap` 通过副作用导入自动注册：
+
+```ts
+import * as echarts from 'echarts'
+import 'echarts/extension/bmap/bmap'
+```
+
+`tg-map-echarts` 不会自动修改 ECharts，需要显式安装一次：
+
+```ts
+import * as echarts from 'echarts'
+import { TgMapExtension } from 'tg-map-echarts'
+
+echarts.use(TgMapExtension)
+```
+
+可以在应用入口统一调用 `echarts.use`，也可以放在使用地图图表的模块顶层。ECharts 会对同一个扩展去重，不需要在组件实例创建时重复注册。
+
+如果使用 `echarts/core` 按需引入，需要同时安装用到的图表、组件和渲染器：
+
+```ts
+import * as echarts from 'echarts/core'
+import { EffectScatterChart, HeatmapChart } from 'echarts/charts'
+import { TooltipComponent, VisualMapComponent } from 'echarts/components'
+import { CanvasRenderer } from 'echarts/renderers'
+import { TgMapExtension } from 'tg-map-echarts'
+
+echarts.use([
+  EffectScatterChart,
+  HeatmapChart,
+  TooltipComponent,
+  VisualMapComponent,
+  CanvasRenderer,
+  TgMapExtension,
+])
+```
+
+## 3. 配置并加载地图引擎
+
+在创建图表前，先配置 `tg-map-core`。如果应用已经通过 tg-map 的 Vue 插件传入地图配置，则不需要重复调用 `setTgMapConfig`。
+
+```ts
+import { setTgMapConfig } from 'tg-map-core'
+
+setTgMapConfig({
+  baidu: {
+    key: 'BAIDU_MAP_KEY',
+    version: '3.0',
+  },
+  google: {
+    key: 'GOOGLE_MAP_KEY',
+    language: 'zh-CN',
+  },
+  talks: {
+    layerIds: ['bing'],
+  },
+})
+```
+
+把页面中手写的 `<script>`、JSONP 加载以及用于等待 SDK 的延时替换为 `loadCachedMap`：
+
+```ts
+import { loadCachedMap, TgMapType } from 'tg-map-core'
+
+const engine = TgMapType.baidu
+await loadCachedMap(engine)
+
+const chart = echarts.init(chartElement)
+chart.setOption(option)
+```
+
+必须在 `chart.setOption()` 前等待加载完成。`loadCachedMap` 会缓存同一种引擎的加载结果，多次调用不会重复加载 SDK。Talks 引擎不依赖厂商 SDK，也使用同一个入口：
+
+```ts
+await loadCachedMap(TgMapType.talks)
+```
+
+## 4. 替换组件配置
+
+原来的 `bmap` 配置：
+
+```ts
+const option = {
+  bmap: {
+    center: [113.2644, 23.1291],
+    zoom: 14,
+    roam: true,
+  },
+}
+```
+
+迁移为：
+
+```ts
+import {
+  CoordType,
+  GestureHandlingOptions,
+  TgMapType,
+} from 'tg-map-core'
+import type { TgMapComponentOption } from 'tg-map-echarts'
+
+const tgMap: TgMapComponentOption = {
+  engine: TgMapType.baidu,
+  mapOptions: {
+    center: {
+      lng: 113.2644,
+      lat: 23.1291,
+      coord: CoordType.wgs84,
+    },
+    zoom: 14,
+    gestureHandling: GestureHandlingOptions.greedy,
+  },
+  dataCoordType: CoordType.wgs84,
+}
+
+const option = { tgMap }
+```
+
+中心点使用可序列化的 `LatLngLiteral`，不要把 `LatLng` 类实例直接放进 ECharts option。`coord` 表示传入中心点的坐标类型，`tg-map-core` 会在内部将其转换为当前地图引擎需要的坐标。
+
+### `roam` 的迁移
+
+`tgMap` 不再提供独立的 `roam` 字段，交互选项统一放在 `mapOptions` 中：
+
+| 原配置 | 新配置 |
+| --- | --- |
+| `roam: true` | `gestureHandling: GestureHandlingOptions.greedy` |
+| `roam: false` | `gestureHandling: GestureHandlingOptions.none` |
+| 页面滚动时希望按住 Ctrl 或使用双指缩放 | `gestureHandling: GestureHandlingOptions.cooperative` |
+| 按地图和页面环境选择默认行为 | `gestureHandling: GestureHandlingOptions.auto` |
+
+ECharts `bmap` 的 `roam: 'move'` 和 `roam: 'scale'` 可以分别只开放平移或缩放；统一的 `gestureHandling` 当前不表达这两个细粒度组合，无法一比一迁移。如果项目使用了它们，需要根据产品交互选择最接近的模式，或者通过 `map.innerMap` 保留引擎特有的控制逻辑。
+
+### 地图样式
+
+`mapStyle` 属于 `mapOptions`。因为 ECharts 会深度合并 option，而地图样式通常是很大的对象，`tgMap` 要求先将样式序列化为 JSON 字符串。
+
+百度样式：
+
+```ts
+tgMap: {
+  engine: TgMapType.baidu,
+  mapOptions: {
+    // 省略center和zoom
+    mapStyle: JSON.stringify({
+      baidu: { styleJson: baiduStyle },
+    }),
+  },
+}
+```
+
+Google 或 Talks 样式使用同一结构中的对应字段：
+
+```ts
+mapStyle: JSON.stringify({
+  google: { styles: googleStyles },
+  talks: { theme: 'dark' },
+})
+```
+
+因此，迁移后不必再在初始化完成后调用 `bmap.setMapStyleV2()`。
+
+`mapOptions.hideLogo` 目前只有 Talks 引擎支持，Baidu 和 Google 引擎会忽略该选项。原页面中用于隐藏百度地图元素的 `.anchorBL` 样式不会被扩展自动替代；是否保留应根据实际页面及地图厂商要求决定。
+
+## 5. 替换 series 坐标系
+
+将所有使用百度地图坐标系的 series：
+
+```ts
+{
+  type: 'heatmap',
+  coordinateSystem: 'bmap',
+  data: points,
+}
+```
+
+改为：
+
+```ts
+{
+  type: 'heatmap',
+  coordinateSystem: 'tgMap',
+  data: points,
+}
+```
+
+每个 ECharts 实例只能配置一个 `tgMap` 组件。所有声明 `coordinateSystem: 'tgMap'` 的 series 会共享这张地图。
+
+### `effectScatter` 是否需要重写
+
+不需要。`effectScatter` 是带涟漪动画的散点图，常用于突出 Top N 站点、告警车辆或其他重点位置。它仍由 ECharts 绘制，迁移时只替换坐标系：
+
+```ts
+{
+  name: 'Top 10',
+  type: 'effectScatter',
+  coordinateSystem: 'tgMap',
+  data: [
+    { name: '站点 A', value: [113.2644, 23.1291, 95] },
+  ],
+  encode: { value: 2 },
+  symbolSize: value => 8 + Number(value[2]) / 10,
+  rippleEffect: { brushType: 'stroke' },
+}
+```
+
+`value` 的前两项始终是 `[lng, lat]`，第三项及后续项仍可作为客流、权重或业务字段。`symbolSize`、`rippleEffect`、`label`、`itemStyle` 等配置不受地图引擎变化影响。
+
+`custom` series 中的 `api.coord([lng, lat])` 也保持不变：
+
+```ts
+renderItem(_params, api) {
+  const point = api.coord([api.value(0), api.value(1)])
+  return {
+    type: 'image',
+    style: {
+      image: carIcon,
+      x: point[0] - 16,
+      y: point[1] - 16,
+      width: 32,
+      height: 32,
+    },
+  }
+}
+```
+
+## 6. 移除业务层坐标转换
+
+这是迁移中最重要的变化之一。旧 `bmap` 扩展直接接收百度地图坐标，因此 WGS-84 数据通常需要先转为 BD-09：
+
+```ts
+const points = source.map(item => {
+  const point = LatLng
+    .fromLngLat(item[0], item[1], CoordType.wgs84)
+    .toBaidu(CoordType.bd09)
+  return [point.lng, point.lat, item[2]]
+})
+```
+
+使用 `tgMap` 后应保留业务数据的原始坐标：
+
+```ts
+const points = source.map(item => [item[0], item[1], item[2]])
+
+const option = {
+  tgMap: {
+    engine: TgMapType.baidu,
+    mapOptions: {
+      center: { lng: 113.2644, lat: 23.1291, coord: CoordType.wgs84 },
+      zoom: 14,
+    },
+    dataCoordType: CoordType.wgs84,
+  },
+  series: [{
+    type: 'heatmap',
+    coordinateSystem: 'tgMap',
+    data: points,
+  }],
+}
+```
+
+`dataCoordType` 描述该 ECharts 实例中地图 series 的 `[lng, lat, ...]` 数据坐标类型，默认为 `CoordType.wgs84`。扩展会创建带坐标类型的 `LatLng`，再由 `tg-map-core` 根据当前引擎完成转换。
+
+如果接口原本返回 GCJ-02 或 BD-09，则不要先转成 WGS-84，只需准确声明：
+
+```ts
+dataCoordType: CoordType.gcj02
+// 或
+dataCoordType: CoordType.bd09
+```
+
+同一个 `tgMap` 坐标系只有一个 `dataCoordType`。如果多个 series 的源数据坐标类型不同，应先在业务层把它们统一为同一种坐标，而不是为每个 series 分别设置。
+
+## 7. 获取地图与监听漫游
+
+原来的代码直接取得百度原生地图：
+
+```ts
+const bmap = chart.getModel().getComponent('bmap').getBMap()
+```
+
+迁移后取得 `tg-map-core` 的统一地图对象：
+
+```ts
+import type { BaseMap } from 'tg-map-core'
+
+const map: BaseMap = chart.getModel().getComponent('tgMap').getMap()
+
+const center = map.getCenter()
+const zoom = map.getZoom()
+map.setCenter(center)
+map.setZoom(15)
+```
+
+应优先使用统一 API，以便同一页面切换地图引擎。确实需要调用厂商特有能力时，可以使用 `map.innerMap` 取得当前引擎的原生地图，但这会让代码重新依赖具体引擎。
+
+地图中心或缩放变化后，扩展会触发 `tgMapRoam` action。ECharts 事件名称会被规范为小写，推荐按下面的方式监听：
+
+```ts
+chart.off('tgmaproam')
+chart.on('tgmaproam', () => {
+  const map = model.getMap()
+  const center = map.getCenter().to(CoordType.wgs84)
+
+  saveViewport({
+    center: { lng: center.lng, lat: center.lat },
+    zoom: map.getZoom(),
+  })
+})
+```
+
+也可以从 `chart.getOption()` 读取回写后的状态。注意 `tgMap` 是组件数组，中心点位于 `mapOptions` 内：
+
+```ts
+const option = chart.getOption() as any
+const { center, zoom } = option.tgMap[0].mapOptions
+```
+
+## 8. 完整迁移示例
+
+迁移前：
+
+```ts
+import * as echarts from 'echarts'
+import 'echarts/extension/bmap/bmap'
+import { CoordType, LatLng } from '@transcodegroup/tg-map'
+
+await loadBaiduByJsonp()
+
+const points = source.map(item => {
+  const point = LatLng
+    .fromLngLat(item.lng, item.lat, CoordType.wgs84)
+    .toBaidu(CoordType.bd09)
+  return [point.lng, point.lat, item.value]
+})
+
+const chart = echarts.init(chartElement)
+chart.setOption({
+  bmap: {
+    center: [113.2644, 23.1291],
+    zoom: 14,
+    roam: true,
+  },
+  series: [
+    {
+      type: 'heatmap',
+      coordinateSystem: 'bmap',
+      data: points,
+      pointSize: 5,
+      blurSize: 10,
+    },
+    {
+      type: 'effectScatter',
+      coordinateSystem: 'bmap',
+      data: top10,
+      rippleEffect: { brushType: 'stroke' },
+    },
+  ],
+})
+
+const bmap = chart.getModel().getComponent('bmap').getBMap()
+bmap.setMapStyleV2({ styleJson: baiduStyle })
+```
+
+迁移后：
+
+```ts
+import * as echarts from 'echarts'
+import {
+  CoordType,
+  GestureHandlingOptions,
+  loadCachedMap,
+  TgMapType,
+} from 'tg-map-core'
+import { TgMapExtension } from 'tg-map-echarts'
+
+echarts.use(TgMapExtension)
+
+const engine = TgMapType.baidu
+await loadCachedMap(engine)
+
+// 接口返回WGS-84，因此不再转为BD-09。
+const points = source.map(item => [item.lng, item.lat, item.value])
+
+const chart = echarts.init(chartElement)
+chart.setOption({
+  tgMap: {
+    engine,
+    mapOptions: {
+      center: {
+        lng: 113.2644,
+        lat: 23.1291,
+        coord: CoordType.wgs84,
+      },
+      zoom: 14,
+      gestureHandling: GestureHandlingOptions.greedy,
+      mapStyle: JSON.stringify({
+        baidu: { styleJson: baiduStyle },
+      }),
+    },
+    dataCoordType: CoordType.wgs84,
+  },
+  series: [
+    {
+      type: 'heatmap',
+      coordinateSystem: 'tgMap',
+      data: points,
+      pointSize: 5,
+      blurSize: 10,
+    },
+    {
+      type: 'effectScatter',
+      coordinateSystem: 'tgMap',
+      data: top10,
+      rippleEffect: { brushType: 'stroke' },
+    },
+  ],
+})
+```
+
+## 9. Vue 组件生命周期与引擎切换
+
+ECharts 容器必须具有明确宽高：
+
+```css
+.chart {
+  width: 100%;
+  height: 100%;
+}
+```
+
+组件销毁时释放 ECharts 实例：
+
+```ts
+beforeDestroy() {
+  this.chart?.dispose()
+  this.chart = null
+}
+```
+
+容器尺寸变化后仍调用标准的 `chart.resize()`。
+
+不要只通过 `setOption` 修改 `tgMap.engine`。地图引擎切换会改变 SDK、DOM 结构和地图实例，应由 Vue 层执行完整重建：
+
+```ts
+async function switchEngine(engine: TgMapType) {
+  chart?.dispose()
+  chart = undefined
+
+  await loadCachedMap(engine)
+  chart = echarts.init(chartElement)
+  chart.setOption(createOption(engine))
+}
+```
+
+## 10. 迁移检查清单
+
+- 删除 `echarts/extension/bmap/bmap` 的副作用导入。
+- 在模块顶层调用一次 `echarts.use(TgMapExtension)`。
+- 在 `setOption` 前等待 `loadCachedMap(engine)`。
+- 将顶层 `bmap` 改为 `tgMap`，并补充 `engine`、`mapOptions` 和 `dataCoordType`。
+- 将所有 `coordinateSystem: 'bmap'` 改为 `'tgMap'`。
+- 删除 `.toBaidu(CoordType.bd09)` 等仅为百度底图准备的坐标转换。
+- 将 `roam` 改为 `mapOptions.gestureHandling`。
+- 将地图样式放入 `mapOptions.mapStyle` 并使用 `JSON.stringify`。
+- 将 `getBMap()` 改为 `getMap()`，业务代码优先调用统一地图 API。
+- 将 `bmaproam` 监听改为 `tgmaproam`。
+- 切换引擎时销毁并重新创建 ECharts 实例。
+- Vue 组件销毁时调用 `chart.dispose()`，尺寸变化时调用 `chart.resize()`。
+
+完成以上修改后，原有 `heatmap`、`effectScatter` 和 `custom` series 一般不需要进一步改写。

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "tg-map-echarts",
+  "version": "4.3.0",
+  "author": "ipcjs",
+  "description": "基于 tg-map-core 的 ECharts 地图坐标系扩展",
+  "keywords": [
+    "echarts",
+    "google-map",
+    "baidu-map",
+    "here-map",
+    "maptalks"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TranscodeGroup/tg-map/tree/master/packages/tg-map-echarts"
+  },
+  "homepage": "https://github.com/TranscodeGroup/tg-map/issues",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/tg-map-echarts.cjs",
+  "module": "./dist/tg-map-echarts.mjs",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/tg-map-echarts.mjs",
+      "require": "./dist/tg-map-echarts.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "!dist/**/*.map",
+    "!dist/tsconfig.tsbuildinfo"
+  ],
+  "dependencies": {
+    "tg-commons": "^1.2.12",
+    "tg-map-core": "4.3.0"
+  },
+  "peerDependencies": {
+    "echarts": "^5.2.1"
+  },
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-replace": "^6.0.2",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "rollup": "^4.37.0",
+    "tslib": "^2.8.1",
+    "typescript": "~5.8.3"
+  },
+  "scripts": {
+    "dev": "rollup -c --watch --no-watch.clearScreen",
+    "build": "rollup -c"
+  }
+}