tg-map-echarts 4.3.0

package/README.md

@@ -0,0 +1,43 @@
+# tg-map-echarts
+
+基于 `tg-map-core` 的 ECharts 5 地图坐标系扩展，支持 Baidu、Google 和 Talks 地图引擎。
+
+从 ECharts 官方 `bmap` 扩展迁移，请参阅[迁移指南](./docs/migration-from-bmap.md)。
+
+```ts
+import * as echarts from 'echarts'
+import { type BaseMap, CoordType, GestureHandlingOptions, loadCachedMap, TgMapType } from 'tg-map-core'
+import { TgMapExtension } from 'tg-map-echarts'
+
+// 显式安装一次扩展；包本身不会修改全局ECharts实例。
+echarts.use(TgMapExtension)
+// 必须在setOption前完成对应地图引擎的加载。
+await loadCachedMap(TgMapType.talks)
+
+const chart = echarts.init(document.getElementById('chart')!)
+chart.setOption({
+  tgMap: {
+    engine: TgMapType.talks,
+    mapOptions: {
+      center: { lng: 116.4, lat: 39.9, coord: CoordType.wgs84 },
+      zoom: 12,
+      gestureHandling: GestureHandlingOptions.greedy,
+    },
+  },
+  series: [{
+    type: 'effectScatter',
+    coordinateSystem: 'tgMap',
+    data: [[116.4, 39.9, 10]],
+  }],
+})
+```
+
+`dataCoordType` 默认为 `wgs84`。业务数据不需要预先转换为地图引擎使用的坐标系，扩展会将 ECharts 的 `[lng, lat, ...]` 数据包装为 `LatLng` 后交给 `tg-map-core` 转换。
+
+可以从组件模型取得 `tg-map-core` 地图实例：
+
+```ts
+const map: BaseMap = chart.getModel().getComponent('tgMap').getMap()
+```
+
+每个 ECharts 实例只支持一个 `tgMap`。切换 Baidu、Google、Talks 引擎时，应由 Vue 层先 `dispose()` 当前 ECharts 实例，再等待 `loadCachedMap(newEngine)` 并重新创建图表。

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

@@ -0,0 +1,46 @@
+import { graphic } from 'echarts/core';
+import { CoordType, type BaseMap } from 'tg-map-core';
+import type { CoordinateSystem, CoordinateSystemCreator, ExtensionAPI } from './types';
+type NumericData = [lng: number, lat: number];
+export default class TgMapCoordSys implements CoordinateSystem {
+    private map;
+    private api;
+    private dataCoordType;
+    static dimensions: string[];
+    static create: CoordinateSystemCreator['create'];
+    readonly type = "tgMap";
+    readonly dimensions: string[];
+    constructor(map: BaseMap, api: ExtensionAPI, dataCoordType: CoordType);
+    getMap(): BaseMap;
+    dataToPoint(data: NumericData, _clamp?: boolean, out?: number[]): number[];
+    pointToData(point: number[]): number[];
+    containPoint(point: number[]): boolean;
+    getViewRect(): graphic.BoundingRect;
+    getRoamTransform(): number[];
+    prepareCustoms(): {
+        coordSys: {
+            type: string;
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        api: {
+            coord: (data: NumericData, _clamp?: boolean, out?: number[]) => number[];
+            size: (dataSize: NumericData, dataItem?: NumericData) => number[];
+        };
+    };
+    private dataToCoordSize;
+    /**
+     * 创建的DOM层级:
+     * ```
+     * root/viewportParent         echarts的元素, viewportRoot原本的parent
+     * |--mapRoot                  class=ec-extension-tg-map
+     *    |--pane
+     *        |--viewportRoot      painter的viewportRoot
+     * ```
+     */
+    private static createMapRuntime;
+}
+export {};
+//# sourceMappingURL=TgMapCoordSys.d.ts.map

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

@@ -0,0 +1,51 @@
+import { ComponentModel } from 'echarts/core';
+import { CoordType, LatLng, TgMapType, type BaseMap, type ElementOverlay } from 'tg-map-core';
+import type TgMapCoordSys from './TgMapCoordSys';
+import type { ResolvedTgMapComponentOption } from './types';
+export declare const DYNAMIC_UI_OPTION_KEYS: readonly ["gestureHandling", "minZoom", "maxZoom", "mapStyle", "hideLogo", "fractionalZoom"];
+type DynamicOptionKey = typeof DYNAMIC_UI_OPTION_KEYS[number] | 'buildInMapTypeId';
+export interface TgMapRuntime {
+    map: BaseMap;
+    mapRoot: HTMLElement;
+    overlay: ElementOverlay;
+    viewportRoot: HTMLElement;
+    viewportBackup: {
+        parent: Node;
+        nextSibling: Node | null;
+        className: string;
+        position: string;
+        left: string;
+        top: string;
+        getViewportRootOffset: () => {
+            offsetLeft: number;
+            offsetTop: number;
+        };
+    };
+    syncViewportPosition: () => void;
+    applyingOptions: boolean;
+    animationFrameId?: number;
+    dynamicOptionSnapshots: Map<DynamicOptionKey, unknown>;
+}
+export default class TgMapModel extends ComponentModel<ResolvedTgMapComponentOption> {
+    static type: string;
+    readonly type: string;
+    static defaultOption: ResolvedTgMapComponentOption;
+    coordinateSystem?: TgMapCoordSys;
+    private runtime?;
+    getEngine(): TgMapType;
+    getDataCoordType(): CoordType;
+    getMapOptions(): Omit<import("tg-map-core").MapOptions, "mapStyle" | "center"> & {
+        center: import("tg-map-core").LatLngLiteral;
+        mapStyle?: string;
+    };
+    getMap(): BaseMap;
+    getRuntime(): TgMapRuntime | undefined;
+    setRuntime(runtime: TgMapRuntime | undefined): void;
+    setCenterAndZoom(center: LatLng, zoom: number): void;
+    /** 应用坐标相关选项到地图 */
+    applyCoordinateOptions(runtime: TgMapRuntime): void;
+    /** 应用UI相关选项到地图 */
+    applyUIOptions(runtime: TgMapRuntime): void;
+}
+export {};
+//# sourceMappingURL=TgMapModel.d.ts.map

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

@@ -0,0 +1,16 @@
+import { ComponentView } from 'echarts/core';
+import TgMapModel from './TgMapModel';
+import type { ExtensionAPI, GlobalModel } from './types';
+export default class TgMapView extends ComponentView {
+    static type: string;
+    readonly type: string;
+    private model?;
+    private map?;
+    private rendering;
+    private changeHandler?;
+    render(model: TgMapModel, _ecModel: GlobalModel, api: ExtensionAPI): void;
+    dispose(_ecModel: GlobalModel, api: ExtensionAPI): void;
+    private bindMapEvents;
+    private unbindMapEvents;
+}
+//# sourceMappingURL=TgMapView.d.ts.map

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

@@ -0,0 +1,21 @@
+export interface TgMapViewportPainter {
+    getViewportRoot(): HTMLElement;
+    getViewportRootOffset(): {
+        offsetLeft: number;
+        offsetTop: number;
+    };
+}
+/** 保存ECharts viewport的原始状态，并负责切换和恢复地图Overlay状态。 */
+export declare class TgMapViewportState {
+    private painter;
+    readonly root: HTMLElement;
+    private readonly parent;
+    private readonly nextSibling;
+    private readonly className;
+    private readonly style;
+    private readonly getViewportRootOffset;
+    constructor(painter: TgMapViewportPainter);
+    applyOverlayState(): void;
+    restore(): void;
+}
+//# sourceMappingURL=TgMapViewportState.d.ts.map

package/dist/src/extension/__tests__/TgMapCoordSys.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,4 @@
+export declare const TgMapExtension: {
+    install: (arg: any) => void;
+};
+//# sourceMappingURL=install.d.ts.map

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

@@ -0,0 +1,38 @@
+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>;
+/**
+ * 参考maptalks, 所有自定义的必选字段都通过`defaultOption`设置默认值, 外部设置option时, 全部字段都可选, 这样在读取的时候, 就可以省略判空
+ * 注意, 如果用户主动将字段设为null/undefined, 字段依然会读到null/undefined, 而不是默认值
+ * 故这种方式并不严谨, 但可以省略一大堆空值判断
+ */
+export interface ResolvedTgMapComponentOption extends ComponentOption {
+    mainType?: 'tgMap';
+    /**
+     * 地图引擎。SDK需要在setOption前通过loadCachedMap加载完成。
+     * @default TgMapType.google
+     */
+    engine: TgMapType;
+    mapOptions: Omit<MapOptions, 'center' | 'mapStyle'> & {
+        /** ECharts会深拷贝option，因此中心点使用可序列化的LatLngLiteral。 */
+        center: LatLngLiteral;
+        /** Echarts会深度合并option, 对于mapStyle这种大对象, 直接转成JSON, 可以避免合并 */
+        mapStyle?: string;
+    };
+    /**
+     * series中[lng, lat, ...]数据的坐标类型。
+     * @default CoordType.wgs84
+     */
+    dataCoordType: CoordType;
+}
+export type EChartsExtension = Extract<Parameters<typeof use>[0], {
+    install: unknown;
+}>;
+export type CoordinateSystemCreator = Parameters<typeof registerCoordinateSystem>[1];
+type CoordinateSystemCreatorParameters = Parameters<CoordinateSystemCreator['create']>;
+export type ExtensionAPI = CoordinateSystemCreatorParameters[1];
+export type GlobalModel = CoordinateSystemCreatorParameters[0];
+export type CoordinateSystem = SeriesModel['coordinateSystem'];
+export type ComponentOption = ComponentModel['option'];
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/index.d.ts

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

package/dist/tg-map-echarts.cjs

@@ -0,0 +1,409 @@
+'use strict';
+
+var core = require('echarts/core');
+var tgCommons = require('tg-commons');
+var tgMapCore = require('tg-map-core');
+
+const DYNAMIC_UI_OPTION_KEYS = [
+    'gestureHandling',
+    'minZoom',
+    'maxZoom',
+    'mapStyle',
+    'hideLogo',
+    'fractionalZoom',
+];
+class TgMapModel extends core.ComponentModel {
+    static type = 'tgMap';
+    type = TgMapModel.type;
+    static defaultOption = {
+        engine: tgMapCore.TgMapType.google,
+        mapOptions: {
+            center: { lat: 0, lng: 0, coord: tgMapCore.COORD_TYPE_DEFAULT },
+            zoom: tgMapCore.MapZoom.STATE,
+        },
+        dataCoordType: tgMapCore.COORD_TYPE_DEFAULT,
+    };
+    coordinateSystem;
+    runtime;
+    getEngine() {
+        return this.option.engine;
+    }
+    getDataCoordType() {
+        return this.option.dataCoordType;
+    }
+    getMapOptions() {
+        return this.option.mapOptions;
+    }
+    getMap() {
+        if (!this.runtime) {
+            throw new Error('tgMap尚未创建');
+        }
+        return this.runtime.map;
+    }
+    getRuntime() {
+        return this.runtime;
+    }
+    setRuntime(runtime) {
+        this.runtime = runtime;
+    }
+    setCenterAndZoom(center, zoom) {
+        this.option.mapOptions.center = {
+            lat: center.lat,
+            lng: center.lng,
+            coord: center.coord,
+        };
+        this.option.mapOptions.zoom = zoom;
+    }
+    /** 应用坐标相关选项到地图 */
+    applyCoordinateOptions(runtime) {
+        const options = this.getMapOptions();
+        runtime.applyingOptions = true;
+        try {
+            if (runtime.dynamicOptionSnapshots.get('buildInMapTypeId') !== options.buildInMapTypeId && options.buildInMapTypeId) {
+                runtime.map.setBuildInMapTypeId(options.buildInMapTypeId);
+                runtime.dynamicOptionSnapshots.set('buildInMapTypeId', options.buildInMapTypeId);
+            }
+            if (runtime.map.getZoom() !== options.zoom) {
+                runtime.map.setZoom(options.zoom);
+            }
+            const center = tgMapCore.LatLng.fromLiteral(options.center);
+            runtime.map.setCenterIfChanged(center);
+        }
+        finally {
+            runtime.applyingOptions = false;
+        }
+    }
+    /** 应用UI相关选项到地图 */
+    applyUIOptions(runtime) {
+        const options = this.getMapOptions();
+        runtime.applyingOptions = true;
+        try {
+            DYNAMIC_UI_OPTION_KEYS.forEach(key => {
+                const value = options[key];
+                const snapshot = typeof value !== 'object'
+                    ? value // 非对象, 可以直接缓存值
+                    : JSON.stringify(value);
+                if (runtime.dynamicOptionSnapshots.get(key) === snapshot) {
+                    return;
+                }
+                runtime.dynamicOptionSnapshots.set(key, snapshot);
+                switch (key) {
+                    case 'gestureHandling':
+                        options.gestureHandling != null && runtime.map.setGestureHandling(options.gestureHandling);
+                        break;
+                    case 'minZoom':
+                        options.minZoom != null && runtime.map.setMinZoom(options.minZoom);
+                        break;
+                    case 'maxZoom':
+                        options.maxZoom != null && runtime.map.setMaxZoom(options.maxZoom);
+                        break;
+                    case 'mapStyle':
+                        runtime.map.setMapStyle(options.mapStyle ? JSON.parse(options.mapStyle) : undefined);
+                        break;
+                    case 'hideLogo':
+                        runtime.map.setHideLogo(options.hideLogo ?? false);
+                        break;
+                    case 'fractionalZoom':
+                        runtime.map.setFractionalZoom(options.fractionalZoom ?? false);
+                        break;
+                    default:
+                        tgCommons.exhaustiveCheck(key);
+                        break;
+                }
+            });
+        }
+        finally {
+            runtime.applyingOptions = false;
+        }
+    }
+}
+
+class TgMapViewportOverlay extends tgMapCore.ElementOverlay {
+    viewportRoot;
+    onOverlayDraw;
+    constructor(map, viewportRoot, onOverlayDraw) {
+        super(map, { mapPane: tgMapCore.MapPane.overlayMouseTarget });
+        this.viewportRoot = viewportRoot;
+        this.onOverlayDraw = onOverlayDraw;
+    }
+    onCreate() {
+        return this.viewportRoot;
+    }
+    onDraw(_projection) {
+        this.onOverlayDraw();
+    }
+}
+class TgMapCoordSys {
+    map;
+    api;
+    dataCoordType;
+    static dimensions = ['lng', 'lat'];
+    static create = (ecModel, api) => {
+        let coordinateSystem;
+        ecModel.eachComponent('tgMap', (model) => {
+            if (!(model instanceof TgMapModel))
+                return;
+            if (coordinateSystem) {
+                throw new Error('一个ECharts实例只能配置一个tgMap组件');
+            }
+            let runtime = model.getRuntime();
+            if (runtime) {
+                model.applyCoordinateOptions(runtime);
+            }
+            else {
+                runtime = TgMapCoordSys.createMapRuntime(model, api);
+            }
+            console.log('TgMapCoordSys.create', runtime);
+            coordinateSystem = new TgMapCoordSys(runtime.map, api, model.getDataCoordType());
+            model.coordinateSystem = coordinateSystem;
+        });
+        ecModel.eachSeries((seriesModel) => {
+            if (seriesModel.get('coordinateSystem') === 'tgMap') {
+                if (!coordinateSystem) {
+                    throw new Error('series使用了tgMap坐标系，但option中没有配置tgMap组件');
+                }
+                seriesModel.coordinateSystem = coordinateSystem;
+            }
+        });
+        return coordinateSystem ? [coordinateSystem] : [];
+    };
+    type = 'tgMap';
+    dimensions = TgMapCoordSys.dimensions;
+    constructor(map, api, dataCoordType) {
+        this.map = map;
+        this.api = api;
+        this.dataCoordType = dataCoordType;
+    }
+    getMap() {
+        return this.map;
+    }
+    dataToPoint(data, _clamp, out = []) {
+        // bmap的实现中使用的是`overlay.getProjection()`表示的相对Pane的坐标, 再减去pane在平移时的偏移, 最终得到相对地图容器的坐标
+        // 这里直接使用containerPoint, 省得偏移来偏移去
+        const point = this.map.fromLatLngToContainerPoint(tgMapCore.LatLng.fromLngLat(data[0], data[1], this.dataCoordType));
+        out[0] = point.x;
+        out[1] = point.y;
+        return out;
+    }
+    pointToData(point) {
+        const latLng = this.map.fromContainerPointToLatLng({ x: point[0], y: point[1] }).to(this.dataCoordType);
+        return [latLng.lng, latLng.lat];
+    }
+    containPoint(point) {
+        return this.getViewRect().contain(point[0], point[1]);
+    }
+    getViewRect() {
+        return new core.graphic.BoundingRect(0, 0, this.api.getWidth(), this.api.getHeight());
+    }
+    getRoamTransform() {
+        return core.matrix.create();
+    }
+    prepareCustoms() {
+        const rect = this.getViewRect();
+        return {
+            coordSys: {
+                type: 'tgMap',
+                x: rect.x,
+                y: rect.y,
+                width: rect.width,
+                height: rect.height,
+            },
+            api: {
+                coord: this.dataToPoint.bind(this),
+                size: this.dataToCoordSize.bind(this),
+            },
+        };
+    }
+    dataToCoordSize(dataSize, dataItem = [0, 0]) {
+        return [0, 1].map(dimIndex => {
+            const value = dataItem[dimIndex];
+            const halfSize = dataSize[dimIndex] / 2;
+            const first = [dataItem[0], dataItem[1]];
+            const second = [...first];
+            first[dimIndex] = value - halfSize;
+            second[dimIndex] = value + halfSize;
+            return Math.abs(this.dataToPoint(first)[dimIndex] - this.dataToPoint(second)[dimIndex]);
+        });
+    }
+    /**
+     * 创建的DOM层级:
+     * ```
+     * root/viewportParent         echarts的元素, viewportRoot原本的parent
+     * |--mapRoot                  class=ec-extension-tg-map
+     *    |--pane
+     *        |--viewportRoot      painter的viewportRoot
+     * ```
+     */
+    static createMapRuntime(model, api) {
+        const root = api.getDom();
+        const painter = api.getZr().painter;
+        const viewportRoot = painter.getViewportRoot();
+        const viewportParent = viewportRoot.parentNode;
+        if (!viewportParent) {
+            throw new Error('无法获取ECharts viewportRoot的父节点');
+        }
+        const mapRoot = document.createElement('div');
+        mapRoot.className = 'ec-extension-tg-map';
+        mapRoot.style.cssText = 'position:absolute;left:0;top:0;width:100%;height:100%';
+        root.insertBefore(mapRoot, root.firstChild);
+        const mapOptions = model.getMapOptions();
+        const map = tgMapCore.TgMapFactory.createMap(model.getEngine(), mapRoot, {
+            ...mapOptions,
+            center: tgMapCore.LatLng.fromLiteral(mapOptions.center),
+            mapStyle: mapOptions.mapStyle ? JSON.parse(mapOptions.mapStyle) : undefined,
+        });
+        const runtime = {
+            map,
+            mapRoot,
+            overlay: tgCommons.lateinit(),
+            viewportRoot,
+            viewportBackup: {
+                parent: viewportParent,
+                nextSibling: viewportRoot.nextSibling,
+                className: viewportRoot.className,
+                position: viewportRoot.style.position,
+                left: viewportRoot.style.left,
+                top: viewportRoot.style.top,
+                getViewportRootOffset: painter.getViewportRootOffset,
+            },
+            syncViewportPosition: tgCommons.lateinit(),
+            applyingOptions: false,
+            dynamicOptionSnapshots: new Map(),
+        };
+        runtime.syncViewportPosition = () => {
+            const pane = viewportRoot.parentElement;
+            if (!pane) {
+                return;
+            }
+            // 地图平移后, pane的左上角可能变化, 这里补偿变化的值, 保证viewportRoot始终和mapRoot的左上角对齐
+            const mapRect = mapRoot.getBoundingClientRect();
+            const paneRect = pane.getBoundingClientRect();
+            viewportRoot.style.left = `${mapRect.left - paneRect.left}px`;
+            viewportRoot.style.top = `${mapRect.top - paneRect.top}px`;
+        };
+        runtime.overlay = new TgMapViewportOverlay(map, viewportRoot, runtime.syncViewportPosition);
+        viewportRoot.style.position = 'absolute';
+        viewportRoot.style.left = '0';
+        viewportRoot.style.top = '0';
+        map.addElementOverlay(runtime.overlay);
+        runtime.syncViewportPosition();
+        painter.getViewportRootOffset = () => ({ offsetLeft: 0, offsetTop: 0 });
+        model.setRuntime(runtime);
+        return runtime;
+    }
+}
+
+class TgMapView extends core.ComponentView {
+    static type = 'tgMap';
+    type = TgMapView.type;
+    model;
+    map;
+    rendering = false;
+    changeHandler;
+    render(model, _ecModel, api) {
+        this.rendering = true;
+        try {
+            this.model = model;
+            const runtime = model.getRuntime();
+            if (!runtime) {
+                throw new Error('tgMap尚未创建');
+            }
+            if (this.map !== runtime.map) {
+                this.unbindMapEvents();
+                this.map = runtime.map;
+                this.bindMapEvents(runtime, api);
+            }
+            model.applyUIOptions(runtime);
+            console.log('TgMapView.render', runtime);
+            runtime.syncViewportPosition();
+        }
+        finally {
+            this.rendering = false;
+        }
+    }
+    dispose(_ecModel, api) {
+        this.unbindMapEvents();
+        const model = this.model;
+        const runtime = model?.getRuntime();
+        if (!model || !runtime) {
+            return;
+        }
+        if (runtime.animationFrameId !== undefined) {
+            cancelAnimationFrame(runtime.animationFrameId);
+        }
+        runtime.map.removeElementOverlay(runtime.overlay);
+        const backup = runtime.viewportBackup;
+        if (backup.nextSibling?.parentNode === backup.parent) {
+            backup.parent.insertBefore(runtime.viewportRoot, backup.nextSibling);
+        }
+        else {
+            backup.parent.appendChild(runtime.viewportRoot);
+        }
+        runtime.viewportRoot.className = backup.className;
+        runtime.viewportRoot.style.position = backup.position;
+        runtime.viewportRoot.style.left = backup.left;
+        runtime.viewportRoot.style.top = backup.top;
+        runtime.mapRoot.parentNode?.removeChild(runtime.mapRoot);
+        const painter = api.getZr().painter;
+        painter.getViewportRootOffset = backup.getViewportRootOffset;
+        model.setRuntime(undefined);
+        this.model = undefined;
+    }
+    bindMapEvents(runtime, api) {
+        this.changeHandler = () => {
+            if (this.rendering || runtime.applyingOptions || runtime.animationFrameId !== undefined) {
+                return;
+            }
+            runtime.animationFrameId = requestAnimationFrame(() => {
+                runtime.animationFrameId = undefined;
+                runtime.syncViewportPosition();
+                api.dispatchAction({
+                    type: 'tgMapRoam',
+                    animation: { duration: 0 },
+                });
+            });
+        };
+        runtime.map.addEventListener('center-changed', this.changeHandler);
+        runtime.map.addEventListener('zoom-changed', this.changeHandler);
+        runtime.map.addEventListener('tilesloaded', this.changeHandler);
+    }
+    unbindMapEvents() {
+        if (!this.map || !this.changeHandler) {
+            return;
+        }
+        this.map.removeEventListener('center-changed', this.changeHandler);
+        this.map.removeEventListener('zoom-changed', this.changeHandler);
+        this.map.removeEventListener('tilesloaded', this.changeHandler);
+        this.changeHandler = undefined;
+        this.map = undefined;
+    }
+}
+
+const TgMapExtension = {
+    install(registers) {
+        registers.registerComponentModel(TgMapModel);
+        registers.registerComponentView(TgMapView);
+        registers.registerCoordinateSystem('tgMap', TgMapCoordSys);
+        // 注册地图漫游Action：dispatchAction后先将地图实际的center/zoom回写到Model，
+        // 再通过updateLayout触发完整更新，重新创建坐标系并渲染图表；event用于更新完成后的对外通知。
+        registers.registerAction({ type: 'tgMapRoam', event: 'tgMapRoam', update: 'updateLayout' }, (_payload, ecModel) => {
+            ecModel.eachComponent('tgMap', (model) => {
+                if (!(model instanceof TgMapModel))
+                    return;
+                const runtime = model.getRuntime();
+                if (runtime) {
+                    model.setCenterAndZoom(runtime.map.getCenter(), runtime.map.getZoom());
+                }
+            });
+        });
+    },
+    // {@template echarts_on_demand_import}
+    // 导入echarts, 会自动安装LineChart等常用组件, 当前包是个echarts扩展, 不需要导入那些东西, 故只导入了echarts/core;
+    //
+    // 而echarts和echarts/core的类型声明是当前是两个独立的d.ts文件, 相互没有关系, 虽然他们的类型声明类似,
+    // 但是依然TS依然会报不兼容错误, 故对于需要导出给外部使用的类型, 需要抹除详细的类型信息
+    //
+    // {@endtemplate}
+};
+
+exports.TgMapExtension = TgMapExtension;