@antv/aimapui 0.2.2 → 0.3.1

package/dist/index.d.ts

@@ -1,16 +1,10 @@
-import { BaiduMap } from '@antv/l7-maps';
 import { Component } from 'react';
 import { default as default_2 } from 'react';
-import { default as default_3 } from 'node_modules/@antv/l7-maps/es/amap-next';
-import { GoogleMap } from '@antv/l7-maps';
+import { Feature } from 'geojson';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
-import { Map as Map_2 } from '@antv/l7-maps';
-import { Mapbox } from '@antv/l7-maps';
-import { MapLibre } from '@antv/l7-maps';
 import { ReactNode } from 'react';
+import { RefObject } from 'react';
 import { Scene } from '@antv/l7';
-import { TencentMap } from '@antv/l7-maps';
-import { TMap } from '@antv/l7-maps';
 
 export declare type ActiveConfig = boolean | {
     color: string;
@@ -818,6 +812,86 @@ export declare interface AnimateConfig {
     repeat?: number;
 }
 
+export declare const AnnotationControl: default_2.ForwardRefExoticComponent<AnnotationControlProps & default_2.RefAttributes<AnnotationControlHandle>>;
+
+export declare interface AnnotationControlHandle {
+    setMode: (mode: AnnotationMode) => void;
+    addAnnotation: (feature: AnnotationFeature) => void;
+    updateAnnotation: (id: string, properties: Partial<AnnotationProperties>) => void;
+    deleteAnnotation: (id: string) => void;
+    clearAll: () => void;
+    getAnnotations: () => AnnotationFeature[];
+    selectAnnotation: (id: string | null) => void;
+}
+
+export declare interface AnnotationControlProps {
+    position?: L7ControlPosition;
+    defaultFeatures?: AnnotationFeature[];
+    features?: AnnotationFeature[];
+    tools?: AnnotationToolMode[];
+    styles?: AnnotationStyleConfig;
+    onUpload?: (file: File, type: 'image' | 'video') => Promise<string>;
+    className?: string;
+    style?: React.CSSProperties;
+    onAnnotationCreate?: (feature: AnnotationFeature) => void;
+    onAnnotationUpdate?: (feature: AnnotationFeature) => void;
+    onAnnotationDelete?: (feature: AnnotationFeature) => void;
+    onAnnotationSelect?: (feature: AnnotationFeature | null) => void;
+    onModeChange?: (mode: AnnotationMode) => void;
+    onChange?: (features: AnnotationFeature[]) => void;
+}
+
+export declare interface AnnotationFeature extends Feature {
+    id: string;
+    properties: AnnotationProperties;
+}
+
+export declare type AnnotationMode = 'marker' | 'highlighter' | 'text' | 'note' | 'link' | 'image' | 'video' | 'select' | 'none';
+
+export declare type AnnotationProperties = MarkerAnnotationProperties | HighlighterAnnotationProperties | TextAnnotationProperties | NoteAnnotationProperties | LinkAnnotationProperties | ImageAnnotationProperties | VideoAnnotationProperties;
+
+declare interface AnnotationPropertiesBase {
+    annotationType: AnnotationType;
+    color?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+
+export declare interface AnnotationStyleConfig {
+    marker?: {
+        color?: string;
+        size?: number;
+    };
+    highlighter?: {
+        color?: string;
+        width?: number;
+        opacity?: number;
+    };
+    text?: {
+        color?: string;
+        fontSize?: number;
+        fontFamily?: string;
+    };
+    note?: {
+        color?: string;
+        maxWidth?: number;
+    };
+    link?: {
+        color?: string;
+    };
+    image?: {
+        maxWidth?: number;
+        borderRadius?: number;
+    };
+    video?: {
+        maxWidth?: number;
+    };
+}
+
+export declare type AnnotationToolMode = Exclude<AnnotationMode, 'none'>;
+
+declare type AnnotationType = 'marker' | 'highlighter' | 'text' | 'note' | 'link' | 'image' | 'video';
+
 export declare function applyControlDefaults(control: ControlSchema): ControlSchema;
 
 export declare function applyLayerDefaults(layer: LayerSchema): LayerSchema;
@@ -1020,7 +1094,7 @@ declare type BubbleAnchor = 'center' | 'top' | 'right' | 'bottom' | 'left' | 'to
  * - bubbleAnchor='center', labelAnchor='center' — 标签居中覆盖气泡（适合短文本）
  * - bubbleAnchor='bottom', labelAnchor='top' — 标签在气泡上方（经典布局）
  */
-export declare function BubbleLayer({ source, sourceType, sourceConfig, labelField, labelColor, labelSize, showLabel, labelTrigger, labelOffset, sizeDomain, bubbleAnchor, labelAnchor, hoverEffect, clickEffect, tooltipEffect, tooltipFields, tooltipTemplate, semanticColorField, color, size, sizeField, sizeValues, style, active, select, onClick, onMouseMove, onMouseEnter, onMouseLeave, ...rest }: BubbleLayerProps): JSX_2.Element;
+export declare function BubbleLayer({ source, sourceType, sourceConfig, labelField, labelColor, labelSize, showLabel, labelOffset, sizeDomain, bubbleAnchor, labelAnchor, hoverEffect, clickEffect, tooltipEffect, tooltipFields, tooltipTemplate, semanticColorField, color, size, sizeField, sizeValues, style, active, select, onClick, onMouseMove, onMouseEnter, onMouseLeave, ...rest }: BubbleLayerProps): JSX_2.Element;
 
 export declare interface BubbleLayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig'> {
     source: LayerSchema['source'];
@@ -1031,8 +1105,6 @@ export declare interface BubbleLayerProps extends Omit<LayerSchema, 'type' | 'so
     labelColor?: string;
     labelSize?: number;
     showLabel?: boolean;
-    /** 文本标签触发方式：'always' 始终显示 | 'hover' 鼠标划过时显示，默认 'always' */
-    labelTrigger?: 'always' | 'hover';
     /** 文本偏移量，默认根据气泡最大半径自动计算 */
     labelOffset?: [number, number];
     /** sizeField 为离散值时，对应每个 sizeValues 的域值顺序（默认 1..N） */
@@ -1071,6 +1143,15 @@ export declare interface BusinessDataItem {
     [key: string]: unknown;
 }
 
+/** 配准阶段 */
+export declare type CalibrationPhase = 'idle' | 'calibrating' | 'confirmed';
+
+/** 配准结果 */
+export declare interface CalibrationResult {
+    corners: GeoCorners;
+    extent: [number, number, number, number];
+}
+
 /**
  * 中国行政区划图层（ChinaDistrict）
  *
@@ -1246,13 +1327,13 @@ export declare interface ControlSchema {
     options?: Record<string, unknown>;
 }
 
-export declare type ControlType = 'zoom' | 'scale' | 'fullscreen' | 'geoLocate' | 'mapTheme' | 'mouseLocation' | 'exportImage' | 'layerSwitch';
+export declare type ControlType = 'zoom' | 'scale' | 'fullscreen' | 'geoLocate' | 'mapTheme' | 'mouseLocation' | 'exportImage' | 'layerSwitch' | 'draw' | 'imageCalibration';
 
 /**
  * 底图工厂 — 根据配置创建 L7 Map 实例
  * 动态导入各底图模块，避免未使用时打包
  */
-export declare function createBasemap(schema: MapSchema): Promise<default_3 | Mapbox | TMap | TencentMap | BaiduMap | MapLibre | GoogleMap | Map_2>;
+export declare function createBasemap(schema: MapSchema): Promise<unknown>;
 
 /**
  * 创建 EventBus 实例
@@ -1325,6 +1406,156 @@ export declare const DEFAULT_PROVINCE_SOURCE = "https://mdn.alipayobjects.com/an
  */
 export declare function diffSchema(prev: AiMapSchema, next: AiMapSchema): SchemaDiffResult;
 
+/** 基础绘制模式（产生要素的模式） */
+declare type DrawBasicMode = 'point' | 'polyline' | 'polygon' | 'rectangle' | 'circle';
+
+export declare const DrawControl: default_2.ForwardRefExoticComponent<DrawControlProps & default_2.RefAttributes<DrawControlHandle>>;
+
+export declare interface DrawControlHandle {
+    setMode: (mode: DrawMode) => void;
+    addFeatures: (features: DrawFeature[]) => void;
+    deleteFeature: (id: string) => void;
+    clearAll: () => void;
+    getFeatures: () => DrawFeature[];
+    selectFeature: (id: string | null) => void;
+}
+
+/** DrawControl 组件 Props */
+export declare interface DrawControlProps {
+    /** 控件位置，默认 topright */
+    position?: L7ControlPosition;
+    /** 初始要素（非受控模式） */
+    defaultFeatures?: DrawFeature[];
+    /** 受控要素 */
+    features?: DrawFeature[];
+    /** 工具栏显示的模式，默认全部显示 */
+    modes?: DrawToolMode[];
+    /** 是否显示删除/清除按钮，默认 true */
+    showDelete?: boolean;
+    /** 自定义样式配置 */
+    styles?: DrawStyleConfig;
+    /** 吸附配置 */
+    snap?: DrawSnapConfig | boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    /** 创建要素回调 */
+    onDrawCreate?: (features: DrawFeature[]) => void;
+    /** 更新要素回调（移动/编辑顶点） */
+    onDrawUpdate?: (feature: DrawFeature) => void;
+    /** 删除要素回调 */
+    onDrawDelete?: (feature: DrawFeature) => void;
+    /** 选中/取消选中要素回调 */
+    onDrawSelect?: (feature: DrawFeature | null) => void;
+    /** 模式切换回调 */
+    onModeChange?: (mode: DrawMode) => void;
+    /** 要素集合变化回调 */
+    onChange?: (features: DrawFeature[]) => void;
+}
+
+/** 绘制中的临时图形（rubber-band）样式 */
+declare interface DrawDrawingStyle {
+    fill?: string;
+    fillOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    /** 虚线（橡皮筋引导线）颜色 */
+    dashStroke?: string;
+    /** 虚线宽度 */
+    dashWidth?: number;
+    /** 虚线 dash-array 模式 */
+    dashArray?: [number, number];
+}
+
+/** 绘制要素（扩展 GeoJSON Feature，携带 id 和 drawType） */
+export declare interface DrawFeature extends Feature {
+    id: string;
+    properties: {
+        /** 创建该要素的绘制模式 */
+        drawType: DrawGeometryMode;
+        [key: string]: unknown;
+    };
+}
+
+/** 绘制模式对应的绘制类型（仅产生要素的模式） */
+declare type DrawGeometryMode = DrawBasicMode;
+
+/** 线要素样式 */
+declare interface DrawLineStyle {
+    color?: string;
+    size?: number;
+    opacity?: number;
+}
+
+/** 绘制模式 */
+export declare type DrawMode = 'point' | 'polyline' | 'polygon' | 'rectangle' | 'circle' | 'edit' | 'split' | 'merge' | 'none';
+
+/** 点要素样式 */
+declare interface DrawPointStyle {
+    color?: string;
+    size?: number;
+    strokeColor?: string;
+    strokeWidth?: number;
+}
+
+/** 面要素样式 */
+declare interface DrawPolygonStyle {
+    fill?: string;
+    fillOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+}
+
+/** 选中要素高亮样式 */
+declare interface DrawSelectedStyle {
+    stroke?: string;
+    strokeWidth?: number;
+    fill?: string;
+    fillOpacity?: number;
+    /** 选中边框虚线模式（编辑态） */
+    dashArray?: [number, number];
+}
+
+/** 吸附配置 */
+export declare interface DrawSnapConfig {
+    /** 是否启用吸附，默认 true */
+    enabled?: boolean;
+    /** 吸附像素阈值，默认 8px */
+    threshold?: number;
+    /** 是否启用顶点吸附，默认 true */
+    vertex?: boolean;
+    /** 是否启用边吸附，默认 true */
+    edge?: boolean;
+}
+
+/** 绘制控件完整样式配置 */
+export declare interface DrawStyleConfig {
+    point?: DrawPointStyle;
+    line?: DrawLineStyle;
+    polygon?: DrawPolygonStyle;
+    drawing?: DrawDrawingStyle;
+    selected?: DrawSelectedStyle;
+    vertex?: DrawVertexStyle;
+}
+
+/** 工具栏显示的绘制模式（不含 none） */
+export declare type DrawToolMode = Exclude<DrawMode, 'none'>;
+
+/** 编辑模式顶点句柄样式 */
+declare interface DrawVertexStyle {
+    /** 固定点填充色（白色） */
+    color?: string;
+    /** 固定点半径 */
+    size?: number;
+    /** 固定点描边色 */
+    strokeColor?: string;
+    /** 固定点描边宽度 */
+    strokeWidth?: number;
+    /** 活动点（选中/拖拽）颜色 */
+    activeColor?: string;
+    /** 活动点半径 */
+    activeSize?: number;
+}
+
 /** 下钻路径节点 */
 export declare interface DrillPathNode {
     level: AdministrativeLevel;
@@ -1406,6 +1637,22 @@ export declare interface EventSchema {
     markerDragEnd?: EventIdentifier;
 }
 
+/** 导出配置 */
+export declare interface ExportConfig {
+    /** 输出图片总宽度(px)，默认原图宽度 */
+    outputWidth?: number;
+    /** 输出图片总高度(px)，默认原图高度 */
+    outputHeight?: number;
+    /** 切片列数，默认 1（不切分） */
+    cols?: number;
+    /** 切片行数，默认 1（不切分） */
+    rows?: number;
+    /** 图片格式 */
+    format?: string;
+    /** 图片质量 0-1 */
+    quality?: number;
+}
+
 export declare function ExportImageControl({ position, format, onExport, className, style, }: ExportImageControlProps): JSX_2.Element;
 
 /**
@@ -1428,6 +1675,28 @@ export declare interface ExportImageControlProps {
     onExport?: (base64: string) => void;
 }
 
+/** 导出选项（向后兼容） */
+export declare interface ExportOptions {
+    maxWidth?: number;
+    format?: string;
+    quality?: number;
+}
+
+/** 导出结果 */
+export declare interface ExportResult {
+    /** 切片列表 */
+    tiles: TileResult[];
+    /** 完整图片的总 extent */
+    extent: [number, number, number, number];
+    /** 完整图片的预览 URL */
+    previewUrl: string;
+    /** 完整图片 Blob */
+    blob: Blob;
+    /** 输出尺寸 */
+    outputWidth: number;
+    outputHeight: number;
+}
+
 declare type FillColorMapping = 'sequential' | 'diverging' | 'categorical';
 
 /**
@@ -1495,6 +1764,26 @@ export declare interface FullscreenControlProps {
  */
 export declare const GAODE_THEME_PRESETS: ThemeOption[];
 
+/** 4个角点地理坐标 [topLeft, topRight, bottomRight, bottomLeft]，每项 [lng, lat] */
+export declare type GeoCorners = [
+[
+number,
+number
+],
+[
+number,
+number
+],
+[
+number,
+number
+],
+[
+number,
+number
+]
+];
+
 export declare function GeoLocateControl({ position, transform, className, style, }: GeoLocateControlProps): JSX_2.Element;
 
 /**
@@ -1522,6 +1811,13 @@ export declare interface GestureConfig {
     dragRotate?: boolean;
 }
 
+/**
+ * 根据控件 position 计算弹出面板的初始方向
+ * - top* → 向下弹出, bottom* → 向上弹出
+ * - left* → 向右弹出, right* → 向左弹出
+ */
+export declare function getPopperDirection(pos: L7ControlPosition): string;
+
 /**
  * 字体图标标注图层（GlyphLayer）
  *
@@ -1669,6 +1965,12 @@ export { HexagonLayerProps }
  */
 export declare function hexToRgba(hex: string, alpha?: number): string;
 
+declare interface HighlighterAnnotationProperties extends AnnotationPropertiesBase {
+    annotationType: 'highlighter';
+    strokeWidth?: number;
+    strokeOpacity?: number;
+}
+
 export declare type IconAnchor = 'center' | 'top' | 'bottom' | 'left' | 'right';
 
 /** 图标锚点位置 */
@@ -1731,6 +2033,72 @@ export declare interface IconLayerProps extends Omit<LayerSchema, 'type' | 'sour
     onMouseLeave?: (payload: LayerEventPayload) => void;
 }
 
+declare interface ImageAnnotationProperties extends AnnotationPropertiesBase {
+    annotationType: 'image';
+    src: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+}
+
+export declare const ImageCalibrationControl: default_2.ForwardRefExoticComponent<ImageCalibrationControlProps & default_2.RefAttributes<ImageCalibrationHandle>>;
+
+/** ImageCalibrationControl 组件 Props */
+export declare interface ImageCalibrationControlProps {
+    /** 控件位置 */
+    position?: L7ControlPosition;
+    /** 布局方向，默认 vertical */
+    layout?: 'vertical' | 'horizontal';
+    /** 受控模式：外部传入角点 */
+    corners?: GeoCorners;
+    /** 非受控模式：初始角点 */
+    defaultCorners?: GeoCorners;
+    /** 图片来源 (URL/base64/File) */
+    imageSource?: ImageSource;
+    /** 覆盖层透明度 0-1，默认 0.7 */
+    opacity?: number;
+    /** 接受的文件类型，默认 'image/*' */
+    accept?: string;
+    /** 是否启用图片裁剪功能，默认 true */
+    enableCrop?: boolean;
+    /** 是否启用初始坐标输入功能，默认 true */
+    enableInitialCoords?: boolean;
+    /** 额外 className */
+    className?: string;
+    /** 额外 style */
+    style?: React.CSSProperties;
+    /** 角点变化回调 */
+    onCornersChange?: (corners: GeoCorners) => void;
+    /** 确认配准回调 */
+    onCalibrate?: (result: CalibrationResult) => void;
+    /** 导出完成回调 */
+    onExport?: (result: ExportResult) => void;
+    /** 图片加载完成回调 */
+    onImageLoad?: (dimensions: {
+        width: number;
+        height: number;
+    }) => void;
+    /** 裁剪预处理完成回调，返回裁剪后的尺寸和可选的初始坐标 */
+    onPreprocess?: (result: {
+        croppedDimensions: {
+            width: number;
+            height: number;
+        };
+        initialCorners: GeoCorners | null;
+    }) => void;
+    /** 清除回调 */
+    onClear?: () => void;
+}
+
+/** 命令式 Handle */
+export declare interface ImageCalibrationHandle {
+    getCorners(): GeoCorners | null;
+    setCorners(corners: GeoCorners): void;
+    setImage(source: ImageSource): void;
+    exportImage(config?: ExportConfig): Promise<ExportResult>;
+    clear(): void;
+}
+
 /**
  * 图片图层组件
  */
@@ -1743,6 +2111,9 @@ export declare interface ImageLayerProps extends Omit<LayerSchema, 'type' | 'sou
     onClick?: (payload: LayerEventPayload) => void;
 }
 
+/** 图片来源 */
+declare type ImageSource = string | File;
+
 /**
  * 独立 Map (L7 内置) 主题预设
  */
@@ -2210,6 +2581,12 @@ export declare interface LineLayerProps extends Omit<LayerSchema, 'type' | 'sour
     onLayerCreated?: (layer: any) => void;
 }
 
+declare interface LinkAnnotationProperties extends AnnotationPropertiesBase {
+    annotationType: 'link';
+    url: string;
+    title?: string;
+}
+
 export declare function LogoControl({ logos, position, className, style, }: LogoControlProps): JSX_2.Element;
 
 export declare interface LogoControlProps {
@@ -2312,7 +2689,10 @@ declare interface MapSceneRendererProps {
 }
 
 export declare interface MapSchema {
-    basemap: BasemapType;
+    /** 底图类型（与 engine 二选一，传 engine 时可省略） */
+    basemap?: BasemapType;
+    /** 外部注入的地图引擎构造函数，跳过动态 import */
+    engine?: new (opts: Record<string, unknown>) => unknown;
     token?: string;
     style?: MapStylePreset | string;
     center?: [number, number];
@@ -2346,6 +2726,12 @@ export declare interface MapThemeControlProps {
 
 export declare function Marker({ longitude, latitude, variant, color, icon, label, content, children, draggable, className, overlayContainer, onClick, onMouseEnter, onMouseLeave, onDoubleClick, onDragEnd, onDragging, onDragStart, selected, inactive, anchor, offsets, overflowHide, }: MarkerProps): null;
 
+declare interface MarkerAnnotationProperties extends AnnotationPropertiesBase {
+    annotationType: 'marker';
+    icon?: string;
+    label?: string;
+}
+
 /**
  * Marker 聚合图层（基于 supercluster）
  *
@@ -2518,6 +2904,12 @@ export declare interface MouseLocationControlProps {
     style?: default_2.CSSProperties;
 }
 
+declare interface NoteAnnotationProperties extends AnnotationPropertiesBase {
+    annotationType: 'note';
+    title: string;
+    body?: string;
+}
+
 /**
  * Mapbox / Maplibre 主题预设 — 基于 openfreemap 样式
  */
@@ -3035,6 +3427,12 @@ declare interface SourceOutput {
 
 export declare type SourceType = 'geojson' | 'json' | 'csv' | 'raster' | 'rasterTile' | 'image';
 
+declare interface TextAnnotationProperties extends AnnotationPropertiesBase {
+    annotationType: 'text';
+    text: string;
+    fontSize?: number;
+}
+
 declare interface ThemeContextValue {
     /** 当前解析后的实际主题（light 或 dark） */
     resolvedTheme: 'light' | 'dark';
@@ -3150,6 +3548,24 @@ export declare interface TiffRasterLayerProps {
     mask?: boolean;
 }
 
+/** 单个切片结果 */
+export declare interface TileResult {
+    blob: Blob;
+    previewUrl: string;
+    /** 切片在网格中的行位置（从0开始） */
+    row: number;
+    /** 切片在网格中的列位置（从0开始） */
+    col: number;
+    /** 该切片对应的地理范围 [minLng, minLat, maxLng, maxLat] */
+    extent: [number, number, number, number];
+    /** 四角地理坐标 [TL, TR, BR, BL] */
+    corners: GeoCorners;
+    /** 切片像素宽度 */
+    width: number;
+    /** 切片像素高度 */
+    height: number;
+}
+
 export declare function Tooltip({ content, variant, longitude, latitude, targetElement, placement, offset, trigger, visible: visibleProp, title, items, overlayContainer, className, }: TooltipProps): default_2.ReactPortal | null;
 
 /**
@@ -3259,6 +3675,19 @@ export declare function useMapControl(position?: L7ControlPosition): {
  */
 export declare function useMapPosition(scene: Scene | null, longitude: number, latitude: number, onPositionUpdate: PositionCallback_2): void;
 
+/**
+ * Popper 弹出方向 Hook —— 根据控件 position 给出初始方向，
+ * 弹出后检测视口溢出并自动翻转。
+ *
+ * 返回 { popperRef, popperClass }
+ * - popperRef：挂到弹出容器 div 上
+ * - popperClass：当前计算出的 CSS class 字符串
+ */
+export declare function usePopperPosition(position: L7ControlPosition, open: boolean, anchorRef: React.RefObject<HTMLElement | null>): {
+    popperRef: RefObject<HTMLDivElement>;
+    popperClass: string;
+};
+
 export declare function useResponsive(): ResponsiveContextValue;
 
 export declare function useScene(): Scene | null;
@@ -3290,6 +3719,13 @@ export declare interface ValidationError {
     severity: 'error' | 'warning';
 }
 
+declare interface VideoAnnotationProperties extends AnnotationPropertiesBase {
+    annotationType: 'video';
+    url: string;
+    thumbnailUrl?: string;
+    title?: string;
+}
+
 declare interface VisualConfig {
     color?: ColorConfig;
     size?: SizeConfig;