tg-map-echarts 4.3.0 → 4.3.1

package/README.md

@@ -6,8 +6,17 @@
 
 ```ts
 import * as echarts from 'echarts'
+import type { ComposeOption, EffectScatterSeriesOption } from 'echarts'
 import { type BaseMap, CoordType, GestureHandlingOptions, loadCachedMap, TgMapType } from 'tg-map-core'
-import { TgMapExtension } from 'tg-map-echarts'
+import {
+  TgMapExtension,
+  type TgMapComponentOption,
+  type TgMapSeriesOption,
+} from 'tg-map-echarts'
+
+type ECOption = ComposeOption<
+  TgMapComponentOption | TgMapSeriesOption<EffectScatterSeriesOption>
+>
 
 // 显式安装一次扩展；包本身不会修改全局ECharts实例。
 echarts.use(TgMapExtension)
@@ -29,7 +38,7 @@ chart.setOption({
     coordinateSystem: 'tgMap',
     data: [[116.4, 39.9, 10]],
   }],
-})
+} satisfies ECOption)
 ```
 
 `dataCoordType` 默认为 `wgs84`。业务数据不需要预先转换为地图引擎使用的坐标系，扩展会将 ECharts 的 `[lng, lat, ...]` 数据包装为 `LatLng` 后交给 `tg-map-core` 转换。

package/dist/src/extension/TgMapModel.d.ts

@@ -34,7 +34,7 @@ export default class TgMapModel extends ComponentModel<ResolvedTgMapComponentOpt
     private runtime?;
     getEngine(): TgMapType;
     getDataCoordType(): CoordType;
-    getMapOptions(): Omit<import("tg-map-core").MapOptions, "mapStyle" | "center"> & {
+    getMapOptions(): Omit<import("tg-map-core").MapOptions, "center" | "mapStyle"> & {
         center: import("tg-map-core").LatLngLiteral;
         mapStyle?: string;
     };

package/dist/src/extension/types.d.ts

@@ -1,6 +1,10 @@
 import type { ComponentModel, registerCoordinateSystem, SeriesModel, use } from 'echarts/core';
 import type { CoordType, DeepPartial, LatLngLiteral, MapOptions, TgMapType } from 'tg-map-core';
 export type TgMapComponentOption = DeepPartial<ResolvedTgMapComponentOption>;
+/** 将使用tgMap坐标系的Series类型适配为coordinateSystem: 'tgMap'。 */
+export type TgMapSeriesOption<Option extends SeriesOption> = Option extends SeriesOption ? Omit<Option, 'coordinateSystem'> & {
+    coordinateSystem: 'tgMap';
+} : never;
 /**
  * 参考maptalks, 所有自定义的必选字段都通过`defaultOption`设置默认值, 外部设置option时, 全部字段都可选, 这样在读取的时候, 就可以省略判空
  * 注意, 如果用户主动将字段设为null/undefined, 字段依然会读到null/undefined, 而不是默认值
@@ -34,5 +38,6 @@ export type ExtensionAPI = CoordinateSystemCreatorParameters[1];
 export type GlobalModel = CoordinateSystemCreatorParameters[0];
 export type CoordinateSystem = SeriesModel['coordinateSystem'];
 export type ComponentOption = ComponentModel['option'];
+export type SeriesOption = SeriesModel['option'];
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/src/index.d.ts

@@ -1,3 +1,3 @@
 export { TgMapExtension } from './extension/install';
-export type { TgMapComponentOption } from './extension/types';
+export type { TgMapComponentOption, TgMapSeriesOption } from './extension/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/tg-map-echarts.cjs

@@ -153,7 +153,6 @@ class TgMapCoordSys {
             else {
                 runtime = TgMapCoordSys.createMapRuntime(model, api);
             }
-            console.log('TgMapCoordSys.create', runtime);
             coordinateSystem = new TgMapCoordSys(runtime.map, api, model.getDataCoordType());
             model.coordinateSystem = coordinateSystem;
         });
@@ -314,7 +313,6 @@ class TgMapView extends core.ComponentView {
                 this.bindMapEvents(runtime, api);
             }
             model.applyUIOptions(runtime);
-            console.log('TgMapView.render', runtime);
             runtime.syncViewportPosition();
         }
         finally {

package/dist/tg-map-echarts.mjs

@@ -151,7 +151,6 @@ class TgMapCoordSys {
             else {
                 runtime = TgMapCoordSys.createMapRuntime(model, api);
             }
-            console.log('TgMapCoordSys.create', runtime);
             coordinateSystem = new TgMapCoordSys(runtime.map, api, model.getDataCoordType());
             model.coordinateSystem = coordinateSystem;
         });
@@ -312,7 +311,6 @@ class TgMapView extends ComponentView {
                 this.bindMapEvents(runtime, api);
             }
             model.applyUIOptions(runtime);
-            console.log('TgMapView.render', runtime);
             runtime.syncViewportPosition();
         }
         finally {

package/docs/migration-from-bmap.md

@@ -25,10 +25,10 @@
 pnpm add echarts tg-map-core tg-map-echarts
 ```
 
-`tg-map-echarts` 的版本号与 `tg-map-core` 保持一致，建议安装相同的明确版本，避免加载两份不同版本的 `tg-map-core`。以 `4.2.12` 为例：
+`tg-map-echarts` 的版本号与 `tg-map-core` 保持一致，建议安装相同的明确版本，避免加载两份不同版本的 `tg-map-core`。以 `4.3.1` 为例：
 
 ```sh
-pnpm add tg-map-core@4.2.12 tg-map-echarts@4.2.12
+pnpm add tg-map-core@4.3.1 tg-map-echarts@4.3.1
 ```
 
 如果项目使用的 tg-map Vue 组件库已经重新导出了同一版本的 `tg-map-core`，可以继续从 Vue 组件库导入公共地图类型和工具；但 `tg-map-echarts` 仍需单独安装。可以通过 `pnpm why tg-map-core` 确认项目只解析到兼容版本；如果存在多个模块实例，从 Vue 插件写入的地图配置可能无法被 `tg-map-echarts` 依赖的实例读取。
@@ -72,6 +72,49 @@ echarts.use([
 ])
 ```
 
+### TypeScript 类型提示
+
+使用 ECharts 官方的 `ComposeOption` 组合实际用到的组件和系列类型。`TgMapComponentOption` 描述顶层 `tgMap` 组件；`TgMapSeriesOption<T>` 将内置系列的 `coordinateSystem` 适配为 `'tgMap'`：
+
+```ts
+import * as echarts from 'echarts'
+import type {
+  ComposeOption,
+  EffectScatterSeriesOption,
+  HeatmapSeriesOption,
+} from 'echarts'
+import { CoordType, TgMapType } from 'tg-map-core'
+import {
+  TgMapExtension,
+  type TgMapComponentOption,
+  type TgMapSeriesOption,
+} from 'tg-map-echarts'
+
+type ECOption = ComposeOption<
+  | TgMapComponentOption
+  | TgMapSeriesOption<HeatmapSeriesOption | EffectScatterSeriesOption>
+>
+
+echarts.use(TgMapExtension)
+
+chart.setOption({
+  tgMap: {
+    engine: TgMapType.baidu,
+    mapOptions: {
+      center: { lng: 113.2644, lat: 23.1291, coord: CoordType.wgs84 },
+      zoom: 14,
+    },
+  },
+  series: [{
+    type: 'heatmap',
+    coordinateSystem: 'tgMap',
+    data: points,
+  }],
+} satisfies ECOption)
+```
+
+`TgMapSeriesOption<T>` 是分布式条件类型，可以一次传入多个系列类型。使用 `echarts/core` 按需引入时写法相同，只需从 `echarts/charts` 和 `echarts/components` 导入对应的 option 类型。
+
 ## 3. 配置并加载地图引擎
 
 在创建图表前，先配置 `tg-map-core`。如果应用已经通过 tg-map 的 Vue 插件传入地图配置，则不需要重复调用 `setTgMapConfig`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tg-map-echarts",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "author": "ipcjs",
   "description": "基于 tg-map-core 的 ECharts 地图坐标系扩展",
   "keywords": [
@@ -35,7 +35,7 @@
   ],
   "dependencies": {
     "tg-commons": "^1.2.12",
-    "tg-map-core": "4.3.0"
+    "tg-map-core": "4.3.1"
   },
   "peerDependencies": {
     "echarts": "^5.2.1"