@yituengine/keymap 1.0.0

package/dist/types/layer/index.d.ts

@@ -0,0 +1,14 @@
+import GraphicLayer from './graphicLayer';
+import HeatmapLayer from './heatmapLayer';
+import TilesetLayer from './tilesetLayer';
+export { default as GraphicLayer } from './graphicLayer';
+export { default as HeatmapLayer } from './heatmapLayer';
+export { default as TilesetLayer } from './tilesetLayer';
+export type { HeatmapGradientStop, HeatmapLayerOptions, HeatmapPoint, HeatmapRenderUpdateOptions, HeatmapValueRange } from './heatmapLayer';
+export type LayerType = GraphicLayer | HeatmapLayer | TilesetLayer;
+declare const _default: {
+    GraphicLayer: typeof GraphicLayer;
+    HeatmapLayer: typeof HeatmapLayer;
+    TilesetLayer: typeof TilesetLayer;
+};
+export default _default;

package/dist/types/layer/tilesetLayer.d.ts

@@ -0,0 +1,107 @@
+import Flatten from '../core/Flatten';
+import Classification from '../core/Classification';
+import * as Cesium from 'cesium';
+import KeyMap from '../map';
+/** 3D Tiles 加载完成后的回调。 */
+type readyCallback = (tileset: Cesium.Cesium3DTileset) => any;
+/**
+ * 3D Tiles 图层。
+ *
+ * `TilesetLayer` 用于加载 Cesium 3D Tiles 数据，并提供定位、显隐、销毁、模型矩阵移动、
+ * `Flatten` 压平工具和 `Classification` 分层工具入口。
+ */
+export default class TilesetLayer {
+    /** 图层唯一 id，同时会写入 Cesium3DTileset 的运行时 id。 */
+    id: string;
+    /** 图层名称，默认使用 `TilesetLayer_id`。 */
+    name: string;
+    /** 图层类型标识。 */
+    type: string;
+    /** 3D Tiles tileset.json 地址。 */
+    url: string;
+    /** 当前图层所属的 `KeyMap` 实例，初始化前为 `null`。 */
+    map: KeyMap | null;
+    /** 是否优先加载叶子节点，以更高精度优先展示模型。 */
+    preferLeaves: boolean;
+    /** 当前 tileset 的压平工具，加载完成后创建。 */
+    Flatten: Flatten | null;
+    /** 当前 tileset 的分类工具，加载完成后创建。 */
+    Classification: Classification | null;
+    /** Cesium 3D Tileset 原始实例，加载完成前为 `null`。 */
+    tileset: Cesium.Cesium3DTileset | null;
+    /** @internal */
+    private _position;
+    /** @internal */
+    private ready;
+    /**
+     * 创建 3D Tiles 图层。
+     *
+     * @param opt 图层配置。
+     * @param opt.id 自定义图层 id。
+     * @param opt.url 3D Tiles tileset.json 地址。
+     * @param opt.position 初始模型位置，会在加载完成后应用到 tileset 矩阵。
+     * @param opt.preferLeaves 是否优先加载叶子节点以提升模型细节。
+     */
+    constructor(opt: {
+        id?: string;
+        url: string;
+        position?: Cesium.Cartesian3;
+        preferLeaves?: boolean;
+    });
+    /**
+     * 初始化图层并异步加载 3D Tiles。
+     *
+     * 通常由 `map.addLayer(layer)` 调用。加载完成后会创建 `Flatten`、`Classification`，
+     * 应用初始位置，登记到 `KeyMap.Assets`，并执行通过 `readyPromise()` 注册的回调。
+     *
+     * @param map 当前地图实例。
+     */
+    init(map: KeyMap): Promise<void>;
+    /** 显示图层，并把图层重新登记到全局资产管理器。 */
+    show(): void;
+    /** 隐藏图层，并从全局资产管理器中 detach。 */
+    hide(): void;
+    /** 从地图中移除 tileset，并从全局资产管理器中 detach。 */
+    destroy(): void;
+    /**
+     * 将地图视角定位到当前 tileset。
+     *
+     * 如果 tileset 尚未加载完成，会把定位动作加入加载完成回调队列。
+     */
+    zoomTo(): void;
+    /**
+     * 注册 tileset 加载完成回调。
+     *
+     * 回调会在 `Cesium3DTileset.fromUrl()` 完成并加入场景后执行。
+     *
+     * @param cb 加载完成回调。
+     */
+    readyPromise(cb: readyCallback): void;
+    /**
+     * 移动 tileset 到指定位置。
+     *
+     * 如果 tileset 尚未加载完成，会把移动动作加入加载完成回调队列。
+     *
+     * @param position 新的模型位置。
+     */
+    moveTo(position: Cesium.Cartesian3): void;
+    /**
+     * 按米为单位对 tileset 进行局部偏移。
+     *
+     * `dx` 表示东西向偏移，`dy` 表示南北向偏移，`dz` 表示高度偏移。
+     *
+     * @param dx 东西向偏移距离，单位米。
+     * @param dy 南北向偏移距离，单位米。
+     * @param dz 高度偏移距离，单位米。
+     */
+    offset(dx: number, dy: number, dz: number): void;
+    /**
+     * tileset 位置。
+     *
+     * 赋值时会调用 `moveTo()`，等价于更新 tileset 模型矩阵。
+     */
+    set position(v: Cesium.Cartesian3);
+    /** 当前 tileset 记录的位置，未设置时为 `null`。 */
+    get position(): Cesium.Cartesian3 | null;
+}
+export {};

package/dist/types/main.d.ts

@@ -0,0 +1,68 @@
+import KeyMap from './map';
+export { default as KeyMap } from './map';
+export * as material from './material';
+export * as measure from './measure';
+export * as graphic from './graphic';
+export * as layer from './layer';
+export * as effect from './effect';
+export * as primitive from './primitive';
+export * as draw from './draw';
+export * as eventType from './event';
+export * from './types/public';
+/** 引擎版本号，与 package.json 保持一致；initMap 时会在控制台打印，便于确认运行时实际加载的引擎版本。 */
+export declare const ENGINE_VERSION = "1.0.0";
+export declare const initMap: (containerId: string, disablePopup?: () => boolean) => void | KeyMap;
+declare const _default: {
+    initMap: (containerId: string, disablePopup?: () => boolean) => void | KeyMap;
+    material: {
+        LightingFlow: typeof import("./material").LightingFlow;
+        PolylineDashed: typeof import("./material").PolylineDashed;
+        TextureFlow: typeof import("./material").TextureFlow;
+        Wave: typeof import("./material").Wave;
+    };
+    measure: {
+        MeasureDistance: typeof import("./measure").MeasureDistance;
+        MeasureCutFill: typeof import("./measure").MeasureCutFill;
+        MeasureHeight: typeof import("./measure").MeasureHeight;
+        MeasureArea: typeof import("./measure").MeasureArea;
+    };
+    graphic: {
+        BillboardGraphic: typeof import("./graphic").BillboardGraphic;
+        ModelGraphic: typeof import("./graphic").ModelGraphic;
+        PolylineGraphic: typeof import("./graphic").PolylineGraphic;
+        PolygonGraphic: typeof import("./graphic").PolygonGraphic;
+        CircleGraphic: typeof import("./graphic").CircleGraphic;
+        PopupGraphic: typeof import("./graphic").PopupGraphic;
+        CustomPopupGraphic: typeof import("./graphic").CustomPopupGraphic;
+    };
+    layer: {
+        GraphicLayer: typeof import("./layer").GraphicLayer;
+        HeatmapLayer: typeof import("./layer").HeatmapLayer;
+        TilesetLayer: typeof import("./layer").TilesetLayer;
+    };
+    effect: {
+        FogEffect: typeof import("./effect").FogEffect;
+        FogProEffect: typeof import("./effect").FogProEffect;
+        RainyEffect: typeof import("./effect").RainyEffect;
+        SnowCoverEffect: typeof import("./effect").SnowCoverEffect;
+        SnowFallEffect: typeof import("./effect").SnowFallEffect;
+        LensFlareEffect: typeof import("./effect").LensFlareEffect;
+        CloudEffect: typeof import("./effect").CloudEffect;
+    };
+    primitive: {
+        TubePrimitive: typeof import("./primitive").TubePrimitive;
+        WallPrimitive: typeof import("./primitive").WallPrimitive;
+    };
+    draw: {
+        DrawPoint: typeof import("./draw").DrawPoint;
+        DrawPolyline: typeof import("./draw").DrawPolyline;
+        DrawCircle: typeof import("./draw").DrawCircle;
+        DrawPolygon: typeof import("./draw").DrawPolygon;
+    };
+    eventType: {
+        MousePick: typeof import("./event").MousePick;
+        Menu: typeof import("./event").Menu;
+    };
+    KeyMap: typeof KeyMap;
+};
+export default _default;

package/dist/types/map/defaultInteractions.d.ts

@@ -0,0 +1,26 @@
+import type KeyMap from './';
+import Menu from '../event/menu';
+import MousePick from '../event/mousePick';
+export default class DefaultInteractions {
+    private readonly map;
+    private readonly disablePopup?;
+    private editPointDragHandler;
+    private graphicHoverHandler;
+    globalMenu: Menu | null;
+    globalMousePick: MousePick | null;
+    private popupLayer;
+    private isDraggingControlPoint;
+    constructor(map: KeyMap, disablePopup?: (() => boolean) | undefined);
+    init(): void;
+    destroy(): void;
+    private setupEditPointDrag;
+    private finishEditPointDrag;
+    private setupGraphicHover;
+    private setupGlobalMenu;
+    private setupGlobalMousePick;
+    private addGraphicClickHandler;
+    private addPopupHandler;
+    private togglePopup;
+    private toggleCustomPopup;
+    private addClassificationHandler;
+}

package/dist/types/map/index.d.ts

@@ -0,0 +1,254 @@
+import * as Cesium from 'cesium';
+import Assets from '../core/Assets';
+import Status from '../core/Status';
+import { GeojsonCoordinate } from '../types';
+import type { LayerType } from '../layer';
+import type { EventType } from '../event';
+import DefaultInteractions from './defaultInteractions';
+/**
+ * 创建 `KeyMap` 时使用的内部配置。
+ *
+ * 通常业务侧不需要直接构造该对象，而是通过 `initMap(containerId, disablePopup?)`
+ * 创建地图实例。
+ */
+type KeyMapOptions = {
+    /** 已创建完成的 Cesium Viewer 实例。 */
+    viewer: Cesium.Viewer;
+    /** 返回 `true` 时，默认弹窗交互会被临时禁用。 */
+    disablePopup?: () => boolean;
+};
+/**
+ * 地图核心实例。
+ *
+ * `KeyMap` 是易图引擎的运行时入口，负责持有 Cesium Viewer、业务图层、资产索引、
+ * 事件实例和默认交互。业务项目通常通过 `initMap()` 获取实例，再使用它添加图层、
+ * 注册事件、控制视角或销毁地图。
+ *
+ * @example
+ * ```ts
+ * import { initMap } from '@yituengine/keymap';
+ *
+ * const map = initMap('map');
+ * map?.flyTo({ position: [113.2644, 23.1291, 3000] });
+ * ```
+ */
+export default class KeyMap {
+    /**
+     * Cesium Viewer 原始实例。
+     *
+     * 当 SDK 没有封装某个 Cesium 能力时，可以通过该属性访问底层 Viewer。
+     */
+    viewer: Cesium.Viewer;
+    /**
+     * 当前 Viewer 的相机实例。
+     *
+     * 可用于读取相机姿态，或直接调用 Cesium Camera 的视角控制能力。
+     */
+    camera: Cesium.Camera;
+    /**
+     * 当前 Viewer 的场景实例。
+     *
+     * 可用于访问 `globe`、`primitives`、`postProcessStages` 等 Cesium 场景对象。
+     */
+    scene: Cesium.Scene;
+    /**
+     * 当前地图上已添加的业务图层列表。
+     *
+     * 一般不建议业务侧直接修改该数组，应优先使用 `addLayer()` 和 `removeLayer()`。
+     */
+    layers: LayerType[];
+    /**
+     * 全局资产管理器。
+     *
+     * 图形、绘制结果、测量对象和部分 Primitive 会登记到这里，便于按 id 查询、删除或解绑。
+     */
+    Assets: Assets;
+    /**
+     * SDK 默认使用的 Cesium 数据源。
+     *
+     * 大部分 Entity 类型图形会添加到该数据源中，由 `KeyMap.destroy()` 统一清理。
+     */
+    dataSource: Cesium.CustomDataSource;
+    /**
+     * 已注册的事件实例列表。
+     *
+     * 例如 `Menu`、`MousePick` 会通过 `map.on(event)` 注册，并在销毁时统一清理。
+     */
+    Events: EventType[];
+    /**
+     * 地图运行状态对象。
+     *
+     * 默认交互、绘制和测量流程会读取或更新这里的状态，业务侧可用于判断当前交互状态。
+     */
+    Status: Status;
+    /**
+     * 当前激活的绘制或测量实例 id。
+     *
+     * 用于保证同一时间只存在一个激活实例，并支持 `Escape` 取消当前实例。
+     */
+    measureInstanceId: import("vue").Ref<string | null>;
+    /**
+     * 是否已经完成过每像素实际距离的初始化计算。
+     *
+     * 首次瓦片加载完成后会尝试初始化 `metersPerPixel`。
+     */
+    isMetersPerPixelInit: boolean;
+    /**
+     * 当前视图中每个屏幕像素对应的地表距离，单位为米。
+     *
+     * 该值会在相机变化或瓦片首次加载完成后更新，可用于比例尺、距离相关 UI 或屏幕尺寸换算。
+     */
+    metersPerPixel: import("vue").Ref<number>;
+    /** @internal */
+    private lastMaxCount;
+    /**
+     * 当前场景瓦片加载进度，范围为 `0` 到 `100`。
+     *
+     * 可用于业务侧显示地图加载进度条。没有待加载瓦片时值为 `100`。
+     */
+    tilesLoadingProgress: import("vue").Ref<number>;
+    /**
+     * 鼠标当前位置的经纬高。
+     *
+     * 鼠标在地球表面移动时更新，字段分别为经度 `longitude`、纬度 `latitude` 和高度 `height`。
+     */
+    mousePostion: {
+        longitude: number;
+        latitude: number;
+        height: number;
+    };
+    /** @internal */
+    private isDestroyed;
+    /** @internal */
+    private middleRotateIconHandler;
+    /**
+     * 默认交互管理器。
+     *
+     * 负责注册图形悬停、弹窗、右键菜单、编辑拖拽等 SDK 内置交互。
+     *
+     * @internal
+     */
+    defaultInteractions: DefaultInteractions;
+    /**
+     * 创建地图核心实例。
+     *
+     * 构造时会挂载默认数据源，注册鼠标位置、瓦片加载进度、每像素距离、中键旋转图标和默认交互。
+     * 业务侧通常不直接调用该构造函数，而是使用 `initMap()`。
+     *
+     * @param option KeyMap 初始化配置。
+     */
+    constructor(option: KeyMapOptions);
+    /**
+     * 添加一个可挂载到地图的对象。
+     *
+     * 传入对象需要实现 `add(map)` 方法。图层、部分 Primitive 或其他 SDK 资产可以通过该方法接入地图。
+     *
+     * @param data 需要添加到当前地图的对象。
+     */
+    add(data: {
+        add: (map: KeyMap) => void;
+    }): void;
+    /**
+     * 从地图中移除一个可销毁对象。
+     *
+     * 传入对象需要实现 `destroy(map)` 方法。对于图层和图形，更推荐使用它们自己的 `destroy()`
+     * 或 `map.removeLayer(layer)`，语义会更明确。
+     *
+     * @param data 需要从当前地图移除的对象。
+     */
+    remove(data: {
+        destroy: (map: KeyMap) => void;
+    }): void;
+    /**
+     * 将相机定位到指定对象。
+     *
+     * 传入对象需要实现 `zoomTo(map)` 方法。常用于对图层、图形或业务封装对象执行统一定位。
+     *
+     * @param data 需要定位的对象。
+     */
+    zoomTo(data: {
+        zoomTo: (map: KeyMap) => void;
+    }): void;
+    /**
+     * 注册事件对象。
+     *
+     * 事件对象需要实现 `register(map)` 方法。`Menu` 和 `MousePick` 等事件能力通过该方法接入地图。
+     *
+     * @param fn 需要注册的事件对象。
+     */
+    on(fn: {
+        register: (map: KeyMap) => void;
+    }): void;
+    /**
+     * 注销事件对象。
+     *
+     * 事件对象需要实现 `destroy()` 方法，用于移除 Cesium 事件监听、DOM 监听或其他资源。
+     *
+     * @param fn 需要注销的事件对象。
+     */
+    off(fn: {
+        destroy: () => void;
+    }): void;
+    /**
+     * 添加图层到地图。
+     *
+     * 调用后图层会持有当前 `KeyMap` 和 `Cesium.Viewer` 引用，并登记到 `layers` 列表。
+     *
+     * @param layer 要添加的图层实例。
+     */
+    addLayer(layer: LayerType): void;
+    /**
+     * 从地图中移除图层。
+     *
+     * 调用后会执行图层的 `destroy()`，图层内图形也会被同步清理。
+     *
+     * @param layer 要移除的图层实例。
+     */
+    removeLayer(layer: LayerType): void;
+    /**
+     * 激活绘制或测量实例。
+     *
+     * 如果已经存在其他激活实例，会先通过 `Assets.removeById()` 移除旧实例，保证绘制和测量互斥。
+     * 激活期间会监听 `Escape` 键，用于取消当前实例。
+     *
+     * @param id 当前绘制或测量实例 id。
+     * @internal
+     */
+    activateMeasureInstance(id: string): void;
+    /**
+     * 取消当前绘制或测量实例的激活状态。
+     *
+     * 只有传入 id 与当前激活实例一致时才会生效。
+     *
+     * @param id 当前绘制或测量实例 id。
+     * @internal
+     */
+    deactivateMeasureInstance(id: string): void;
+    /**
+     * 将相机飞行到指定经纬高位置。
+     *
+     * 默认视角朝北，并以 `-50` 度俯视目标点。
+     *
+     * @param opt 飞行参数。
+     * @param opt.position 目标经纬高，格式为 `[lng, lat, alt?]`。
+     * @param opt.duration 飞行时长，单位为秒，默认 `3`。
+     */
+    flyTo(opt: {
+        position: GeojsonCoordinate;
+        duration?: number;
+    }): void;
+    /**
+     * 销毁地图实例并释放资源。
+     *
+     * 该方法会清理默认交互、事件监听、图层、资产、默认数据源和 Cesium Viewer。
+     * 多次调用是安全的，后续调用会直接返回。
+     */
+    destroy(): void;
+    private destroyDefaultInteractions;
+    private updateMousePositon;
+    private cancelMeasureInstanceByEsc;
+    private updateTilesLoadingProgress;
+    private updateMetersPerPixel;
+    private changeMiddleRotateIcon;
+}
+export {};

package/dist/types/material/LightingFlow.d.ts

@@ -0,0 +1,63 @@
+import { EMaterialName } from '../types';
+import * as Cesium from 'cesium';
+/** `LightingFlow` 流光线材质传入 Cesium shader 的 uniforms。 */
+export interface LightingFlowUniforms {
+    /** 流光带宽度。 */
+    uLineWidth: number;
+    /** 默认透明度底值。 */
+    uDefaultOpc: number;
+    /** 流光颜色。 */
+    uColor: Cesium.Color;
+}
+/**
+ * 线状流光材质。
+ *
+ * 实现 Cesium `MaterialProperty`，用于在线或面边界上生成沿纹理坐标移动的高亮流光效果。
+ */
+export default class LightingFlow implements Cesium.MaterialProperty {
+    private static registered;
+    /** Cesium MaterialProperty 标识，当前材质会随 uniforms 变化。 */
+    readonly isConstant = false;
+    /** Cesium 材质类型名称。 */
+    name: EMaterialName;
+    /** 当前材质 uniforms 状态。 */
+    uniforms: LightingFlowUniforms;
+    /** uniforms 变化时通知 Cesium 重新取值。 */
+    definitionChanged: Cesium.Event<(...args: any[]) => void>;
+    /**
+     * 创建流光线材质。
+     *
+     * @param opt 材质配置。
+     * @param opt.lineWidth 流光带宽度，默认 `1`。
+     * @param opt.opacity 默认透明度底值，默认 `0`。
+     * @param opt.color 流光颜色，默认蓝色。
+     */
+    constructor(opt?: {
+        lineWidth?: number;
+        opacity?: number;
+        color?: Cesium.Color;
+    });
+    private static registerMaterial;
+    /** 流光带宽度。赋值时会触发 `definitionChanged`。 */
+    get uLineWidth(): number;
+    set uLineWidth(w: number);
+    /** 默认透明度底值。赋值时会触发 `definitionChanged`。 */
+    get uDefaultOpc(): number;
+    set uDefaultOpc(o: number);
+    /** 流光颜色。赋值时会触发 `definitionChanged`。 */
+    get uColor(): Cesium.Color;
+    set uColor(c: Cesium.Color);
+    /** 返回 Cesium 材质类型名称。 */
+    getType(_time: Cesium.JulianDate): EMaterialName;
+    /**
+     * 返回当前 uniforms 值。
+     *
+     * Cesium 渲染管线会在需要材质值时调用该方法。
+     *
+     * @param _time Cesium 当前时间。
+     * @param result 可复用的结果对象。
+     */
+    getValue(_time: Cesium.JulianDate, result?: LightingFlowUniforms): LightingFlowUniforms;
+    /** 比较另一个 Cesium Property 是否与当前材质等价。 */
+    equals(other?: Cesium.Property): boolean;
+}

package/dist/types/material/PolylineDashed.d.ts

@@ -0,0 +1,68 @@
+import { EMaterialName } from '../types';
+import * as Cesium from 'cesium';
+/** `PolylineDashed` 虚线材质传入 Cesium shader 的 uniforms。 */
+export interface PolylineDashedUniforms {
+    /** 虚线密度，值越大线段重复越密。 */
+    uDensity: number;
+    /** 虚线间隔比例。 */
+    uSpacing: number;
+    /** 虚线颜色。 */
+    uColor: Cesium.Color;
+}
+/**
+ * 自适应虚线材质。
+ *
+ * 实现 Cesium `MaterialProperty`，会根据相机高度调整虚线密度，使不同视距下的虚线视觉更稳定。
+ */
+export default class PolylineDashed implements Cesium.MaterialProperty {
+    private static registered;
+    /** Cesium MaterialProperty 标识，当前材质会随 uniforms 变化。 */
+    readonly isConstant = false;
+    /** 相机高度匹配档位，单位为千米。 */
+    distances: number[];
+    /** 当前材质 uniforms 状态。 */
+    uniforms: PolylineDashedUniforms;
+    /** uniforms 变化时通知 Cesium 重新取值。 */
+    definitionChanged: Cesium.Event<(...args: any[]) => void>;
+    /** 当前材质用于读取相机高度的 Viewer。 */
+    viewer: Cesium.Viewer;
+    /**
+     * 创建自适应虚线材质。
+     *
+     * @param opt 材质配置。
+     * @param opt.density 虚线密度，默认 `50`。
+     * @param opt.spacing 虚线间隔比例，默认 `0.5`。
+     * @param opt.color 虚线颜色 CSS 字符串。
+     * @param opt.viewer 当前 Cesium Viewer，用于根据相机高度动态匹配虚线密度。
+     */
+    constructor(opt: {
+        density: number;
+        spacing: number;
+        color: string;
+        viewer: Cesium.Viewer;
+    });
+    private static registerMaterial;
+    /** 虚线密度。赋值时会触发 `definitionChanged`。 */
+    get uDensity(): number;
+    set uDensity(d: number);
+    /** 虚线间隔比例。赋值时会触发 `definitionChanged`。 */
+    get uSpacing(): number;
+    set uSpacing(s: number);
+    /** 虚线颜色。赋值时会触发 `definitionChanged`。 */
+    get uColor(): Cesium.Color;
+    set uColor(c: Cesium.Color);
+    /** 返回 Cesium 材质类型名称。 */
+    getType(): EMaterialName;
+    /**
+     * 返回当前 uniforms 值。
+     *
+     * 该方法会根据当前相机高度动态放大 `uDensity`。
+     *
+     * @param _time Cesium 当前时间。
+     * @param result 可复用的结果对象。
+     */
+    getValue(_time: Cesium.JulianDate, result?: PolylineDashedUniforms): PolylineDashedUniforms;
+    /** 比较另一个 Cesium Property 是否与当前材质等价。 */
+    equals(other?: Cesium.Property): boolean;
+    private matchDistance;
+}