@antv/aimapui 0.3.3 → 0.3.5

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import { Component } from 'react';
 import { default as default_2 } from 'react';
 import { Feature } from 'geojson';
-import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 import { RefObject } from 'react';
 import { Scene } from '@antv/l7';
@@ -159,7 +158,7 @@ export declare type AdministrativeLevel = 'province' | 'city' | 'district';
  * <AiMap schema={fullSchema} />
  * ```
  */
-export declare function AiMap({ map, schema, theme, onSceneReady, onLayerClick, onLayerMouseMove, onLayerMouseEnter, onLayerMouseLeave, onMapMove, onMapZoom, autoFit, events, children, className, style, }: AiMapProps): JSX_2.Element;
+export declare function AiMap({ map, schema, theme, onSceneReady, onLayerClick, onLayerMouseMove, onLayerMouseEnter, onLayerMouseLeave, onMapMove, onMapZoom, autoFit, events, children, className, style, }: AiMapProps): default_2.JSX.Element;
 
 /**
  * JSON Schema 导出 — 供 AI / LLM 理解 Schema 结构
@@ -959,7 +958,7 @@ export declare interface ArcFlowDataItem {
  * />
  * ```
  */
-export declare function ArcFlowLayer({ source, sourceType, sourceConfig, shape, color, gradientColors, colorMode, colorField, colorValues, lineWidth, lineWidthRange, weightField, opacity, blur, animate, animateSpeed, animateTrailLength, animateDuration, showNodes, nodeColor, nodeSize, nodeSizeRange, nodePulse, showTooltip, showNodePopup, activeColor, onArcHover, onArcClick, onNodeClick, style: extraStyle, }: ArcFlowLayerProps): JSX_2.Element;
+export declare function ArcFlowLayer({ source, sourceType, sourceConfig, shape, color, gradientColors, colorMode, colorField, colorValues, lineWidth, lineWidthRange, weightField, opacity, blur, animate, animateSpeed, animateTrailLength, animateDuration, showNodes, nodeColor, nodeSize, nodeSizeRange, nodePulse, showTooltip, showNodePopup, activeColor, onArcHover, onArcClick, onNodeClick, style: extraStyle, }: ArcFlowLayerProps): default_2.JSX.Element;
 
 export declare interface ArcFlowLayerProps {
     /** OD 数据源 — JSON 数组 */
@@ -1055,7 +1054,7 @@ export declare type BasemapType = 'gaode' | 'mapbox' | 'maplibre' | 'tianditu' |
  * </BottomSheet>
  * ```
  */
-export declare function BottomSheet({ children, defaultSnap, collapsedHeight, halfRatio, expandedRatio, onSnapChange, className, showHandle, borderRadius, }: BottomSheetProps): JSX_2.Element;
+export declare function BottomSheet({ children, defaultSnap, collapsedHeight, halfRatio, expandedRatio, onSnapChange, className, showHandle, borderRadius, }: BottomSheetProps): default_2.JSX.Element;
 
 export declare interface BottomSheetProps {
     /** 子内容 */
@@ -1096,7 +1095,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, 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): default_2.JSX.Element;
 
 export declare interface BubbleLayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig'> {
     source: LayerSchema['source'];
@@ -1276,7 +1275,7 @@ declare interface ColorConfig {
  * </ControlContainer>
  * ```
  */
-export declare function ControlContainer({ children, className, style }: ControlContainerProps): JSX_2.Element;
+export declare function ControlContainer({ children, className, style }: ControlContainerProps): default_2.JSX.Element;
 
 declare interface ControlContainerProps {
     children?: ReactNode;
@@ -1314,7 +1313,7 @@ export declare const ControlRegistry: {
  * 使用 ControlContainer 包裹，按 position 自动分组排列，
  * 同一角度的多个控件自动堆叠而不会重叠
  */
-export declare function ControlRenderer({ controls, layers, onLayerToggle, containerRef }: ControlRendererProps): JSX_2.Element;
+export declare function ControlRenderer({ controls, layers, onLayerToggle, containerRef }: ControlRendererProps): default_2.JSX.Element;
 
 declare interface ControlRendererProps {
     controls: ControlSchema[];
@@ -1327,6 +1326,8 @@ export declare interface ControlSchema {
     type: ControlType;
     position?: ControlPosition;
     options?: Record<string, unknown>;
+    /** 不可序列化的回调函数（仅用于编程式 API，不出现在 JSON Schema 中） */
+    callbacks?: Record<string, unknown>;
 }
 
 export declare type ControlType = 'zoom' | 'scale' | 'fullscreen' | 'geoLocate' | 'mapTheme' | 'mouseLocation' | 'exportImage' | 'layerSwitch' | 'draw' | 'imageCalibration';
@@ -1574,7 +1575,7 @@ export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBo
     state: ErrorBoundaryState;
     static getDerivedStateFromError(error: Error): ErrorBoundaryState;
     componentDidCatch(error: Error, errorInfo: default_2.ErrorInfo): void;
-    render(): string | number | boolean | Iterable<default_2.ReactNode> | JSX_2.Element | null | undefined;
+    render(): string | number | boolean | Iterable<default_2.ReactNode> | default_2.JSX.Element | null | undefined;
 }
 
 declare interface ErrorBoundaryProps {
@@ -1617,7 +1618,7 @@ export declare class EventBus {
     clear(): void;
 }
 
-export declare function EventBusProvider({ events, children }: EventBusProviderProps): JSX_2.Element;
+export declare function EventBusProvider({ events, children }: EventBusProviderProps): default_2.JSX.Element;
 
 declare interface EventBusProviderProps {
     /** 初始事件监听（从 AiMap events prop 传入） */
@@ -1703,12 +1704,33 @@ export declare interface ExportResult {
     outputHeight: number;
 }
 
+/** 导出上传数据包 */
+declare interface ExportUploadData {
+    /** 所有瓦片切片 */
+    tiles: Array<{
+        blob: Blob;
+        row: number;
+        col: number;
+        extent: [number, number, number, number];
+        corners: GeoCorners;
+        width: number;
+        height: number;
+    }>;
+    /** 完整配准后的图片 Blob */
+    fullBlob: Blob;
+    /** 完整图片的地理范围 */
+    extent: [number, number, number, number];
+    /** 输出尺寸 */
+    outputWidth: number;
+    outputHeight: number;
+}
+
 declare type FillColorMapping = 'sequential' | 'diverging' | 'categorical';
 
 /**
  * 填充图组件（填充 + 描边 + 文字）
  */
-export declare function FillLayer({ source, sourceType, colorMapping, showStroke, strokeColor, strokeWidth, hoverEffect, clickEffect, stickySelection, tooltipEffect, tooltipFields, tooltipTemplate, regionIdField, highlightStrokeColor, highlightStrokeWidth, zoomToRegionOnClick, clickZoomPadding, clickZoomDelta, onRegionClick, onDrilldown, onLayerCreated, showLabel, labelField, labelColor, labelSize, labelAreaThreshold, labelHaloWidth, minLabelZoom, valueField, percentageField, nameField, color, colorField, colorValues, active, select, events, style, ...rest }: FillLayerProps): JSX_2.Element;
+export declare function FillLayer({ source, sourceType, colorMapping, showStroke, strokeColor, strokeWidth, hoverEffect, clickEffect, stickySelection, tooltipEffect, tooltipFields, tooltipTemplate, regionIdField, highlightStrokeColor, highlightStrokeWidth, zoomToRegionOnClick, clickZoomPadding, clickZoomDelta, onRegionClick, onDrilldown, onLayerCreated, showLabel, labelField, labelColor, labelSize, labelAreaThreshold, labelHaloWidth, minLabelZoom, valueField, percentageField, nameField, color, colorField, colorValues, active, select, events, style, ...rest }: FillLayerProps): default_2.JSX.Element;
 
 export declare interface FillLayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig'> {
     source: LayerSchema['source'];
@@ -1744,7 +1766,7 @@ export declare interface FillLayerProps extends Omit<LayerSchema, 'type' | 'sour
     nameField?: string;
 }
 
-export declare function FullscreenControl({ position, container, className, style, }: FullscreenControlProps): JSX_2.Element;
+export declare function FullscreenControl({ position, container, className, style, }: FullscreenControlProps): default_2.JSX.Element;
 
 /**
  * Fullscreen 全屏控件
@@ -1790,7 +1812,7 @@ number
 ]
 ];
 
-export declare function GeoLocateControl({ position, transform, className, style, }: GeoLocateControlProps): JSX_2.Element;
+export declare function GeoLocateControl({ position, transform, className, style, }: GeoLocateControlProps): default_2.JSX.Element;
 
 /**
  * GeoLocate 定位控件
@@ -1838,7 +1860,7 @@ export declare function getPopperDirection(pos: L7ControlPosition): string;
  * - 碰撞检测：图标始终可见，仅文本被避让
  * - 缩放适配：L1(14+) 全显示 → L2(10-13) 仅图标 → L3(<10) 降级圆点
  */
-export declare function GlyphLayer({ source, sourceType, sourceConfig, iconField, iconFontFamily, iconFontPath, iconFontMap, iconColor, iconSize, iconHaloColor, iconHaloWidth, iconStyle, iconAnchor, iconBgShape, iconBgShapeColor, iconBgShapeSize, iconBgStrokeColor, iconBgStrokeWidth, iconBgPadding, iconBgCornerRadius, showLabel, labelField, labelColor, labelSize, labelAnchor, labelOffset, labelHaloColor, labelHaloWidth, labelStyle, textAllowOverlap, iconAllowOverlap, zoomAdaption, zoomShowLabel, zoomDegradeToPoint, onClick, onMouseEnter, onMouseLeave, ...rest }: GlyphLayerProps): JSX_2.Element | null;
+export declare function GlyphLayer({ source, sourceType, sourceConfig, iconField, iconFontFamily, iconFontPath, iconFontMap, iconColor, iconSize, iconHaloColor, iconHaloWidth, iconStyle, iconAnchor, iconBgShape, iconBgShapeColor, iconBgShapeSize, iconBgStrokeColor, iconBgStrokeWidth, iconBgPadding, iconBgCornerRadius, showLabel, labelField, labelColor, labelSize, labelAnchor, labelOffset, labelHaloColor, labelHaloWidth, labelStyle, textAllowOverlap, iconAllowOverlap, zoomAdaption, zoomShowLabel, zoomDegradeToPoint, onClick, onMouseEnter, onMouseLeave, ...rest }: GlyphLayerProps): default_2.JSX.Element | null;
 
 export declare interface GlyphLayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig'> {
     source: LayerSchema['source'];
@@ -1929,7 +1951,7 @@ export declare interface H3DataItem {
     [key: string]: unknown;
 }
 
-export declare function H3Layer({ source, h3Field, color, colorField, colorValues, opacity, showStroke, strokeColor, strokeWidth, hoverEffect, clickEffect, showLabel, labelField, labelColor, labelSize, active, select, style, onClick, onMouseMove, onMouseEnter, onMouseLeave, ...rest }: H3LayerProps): JSX_2.Element;
+export declare function H3Layer({ source, h3Field, color, colorField, colorValues, opacity, showStroke, strokeColor, strokeWidth, hoverEffect, clickEffect, showLabel, labelField, labelColor, labelSize, active, select, style, onClick, onMouseMove, onMouseEnter, onMouseLeave, ...rest }: H3LayerProps): default_2.JSX.Element;
 
 export declare interface H3LayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig' | 'shape' | 'shapeField' | 'shapeValues'> {
     source: H3DataItem[];
@@ -1954,7 +1976,7 @@ export declare interface H3LayerProps extends Omit<LayerSchema, 'type' | 'source
  *
  * 支持悬停高亮交互（对齐蜂窝热力图设计规范）
  */
-export declare function HeatmapLayer({ source, sourceType, sourceConfig, onClick, onMouseMove, onMouseEnter, onMouseLeave, onLayerCreated, ...rest }: HeatmapLayerProps): JSX_2.Element | null;
+export declare function HeatmapLayer({ source, sourceType, sourceConfig, onClick, onMouseMove, onMouseEnter, onMouseLeave, onLayerCreated, ...rest }: HeatmapLayerProps): default_2.JSX.Element | null;
 
 export declare interface HeatmapLayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig'> {
     source: LayerSchema['source'];
@@ -1974,8 +1996,14 @@ export declare interface HeatmapLayerProps extends Omit<LayerSchema, 'type' | 's
 
 /**
  * 蜂窝热力图（六边形聚合）
+ *
+ * 遵循设计规范：
+ * - 2D 模式：平面正六边形，可选描边
+ * - 3D 模式：立体挤压柱体，高度映射权重
+ * - 默认 hexSize=20（屏幕空间 20-40px 范围）
+ * - 支持 hover 高亮反馈
  */
-declare function HexagonLayer({ source, sourceType, sourceConfig, hexSize, weightField, weightMethod, onClick, onMouseMove, style, ...rest }: HexagonLayerProps): JSX_2.Element;
+declare function HexagonLayer({ source, sourceType, sourceConfig, mode, hexSize, weightField, weightMethod, showStroke, strokeColor, strokeWidth, hoverEffect, activeColor, onClick, onMouseMove, onMouseEnter, onMouseLeave, style, ...rest }: HexagonLayerProps): default_2.JSX.Element;
 export { HexagonLayer as HeatmapHexagonLayer }
 export { HexagonLayer }
 
@@ -1983,15 +2011,39 @@ declare interface HexagonLayerProps extends Omit<LayerSchema, 'type' | 'shape' |
     source: LayerSchema['source'];
     sourceType?: LayerSchema['sourceType'];
     sourceConfig?: LayerSchema['sourceConfig'];
+    /** 渲染模式，默认 '3d'（立体挤压） */
+    mode?: HexagonMode;
+    /** 六边形半径（像素），默认 20（符合规范 20-40px 范围） */
     hexSize?: number;
+    /** 权重字段，默认 'value' */
     weightField?: string;
+    /** 聚合方法，默认 'sum' */
     weightMethod?: 'sum' | 'mean' | 'min' | 'max' | 'count';
+    /** 是否显示描边，默认 false（2D 模式可开启） */
+    showStroke?: boolean;
+    /** 描边颜色，默认 'rgba(255,255,255,0.3)' */
+    strokeColor?: string;
+    /** 描边宽度，默认 0.5 */
+    strokeWidth?: number;
+    /** 是否启用 hover 高亮，默认 true */
+    hoverEffect?: boolean;
+    /** hover 高亮色，默认 '#fbbf24' (secondary) */
+    activeColor?: string;
     onClick?: (payload: LayerEventPayload) => void;
     onMouseMove?: (payload: LayerEventPayload) => void;
+    onMouseEnter?: (payload: LayerEventPayload) => void;
+    onMouseLeave?: (payload: LayerEventPayload) => void;
 }
 export { HexagonLayerProps as HeatmapHexagonLayerProps }
 export { HexagonLayerProps }
 
+/**
+ * 蜂窝热力图渲染模式
+ * - 2d: 平面六边形，适合密度分布展示
+ * - 3d: 立体挤压柱体，高度映射权重，增强视觉对比
+ */
+declare type HexagonMode = '2d' | '3d';
+
 /**
  * 将十六进制颜色转为 RGBA
  */
@@ -2018,7 +2070,7 @@ declare type IconAnchor_2 = 'center' | 'top' | 'bottom' | 'left' | 'right';
  * - 缩放适配：Zoom15+ 全显示 → 10-14 仅图标 → <10 降级圆点
  * - 碰撞检测：重叠时隐藏低优先级文本
  */
-export declare function IconLayer({ source, sourceType, sourceConfig, iconField, iconMap, iconSize, iconAnchor, size, showLabel, labelField, labelColor, labelSize, labelAnchor, labelOffset, labelHaloColor, labelHaloWidth, labelStyle, textAllowOverlap, iconAllowOverlap, zoomAdaption, zoomShowLabel, zoomDegradeToPoint, onClick, onMouseEnter, onMouseLeave, ...rest }: IconLayerProps): JSX_2.Element | null;
+export declare function IconLayer({ source, sourceType, sourceConfig, iconField, iconMap, iconSize, iconAnchor, size, showLabel, labelField, labelColor, labelSize, labelAnchor, labelOffset, labelHaloColor, labelHaloWidth, labelStyle, textAllowOverlap, iconAllowOverlap, zoomAdaption, zoomShowLabel, zoomDegradeToPoint, onClick, onMouseEnter, onMouseLeave, ...rest }: IconLayerProps): default_2.JSX.Element | null;
 
 export declare interface IconLayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig'> {
     source: LayerSchema['source'];
@@ -2132,6 +2184,12 @@ export declare interface ImageCalibrationControlProps {
     onImageAdd?: (image: RegisteredImage) => void;
     /** 删除图片回调 */
     onImageRemove?: (imageId: string) => void;
+    /** 文件上传到 CDN 的回调。提供时，组件会将原始 File 传给此回调，用返回的 CDN URL 进入后续流程 */
+    onImageUpload?: OnImageUpload;
+    /** 裁剪后上传到 CDN 的回调。提供时，裁剪后的 Blob 先传给此回调，返回的 CDN URL 作为最终图片源 */
+    onCropUpload?: OnCropUpload;
+    /** 导出上传到 CDN 的回调。提供时，导出对话框中展示"上传到云端"按钮，瓦片和完整图片传给此回调 */
+    onExportUpload?: OnExportUpload;
 }
 
 /** 命令式 Handle */
@@ -2154,7 +2212,7 @@ export declare interface ImageCalibrationHandle {
 /**
  * 图片图层组件
  */
-export declare function ImageLayer({ source, sourceType, sourceConfig, onClick, ...rest }: ImageLayerProps): JSX_2.Element | null;
+export declare function ImageLayer({ source, sourceType, sourceConfig, onClick, ...rest }: ImageLayerProps): default_2.JSX.Element | null;
 
 export declare interface ImageLayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig'> {
     source: LayerSchema['source'];
@@ -2177,7 +2235,7 @@ export declare const INDEPENDENT_MAP_THEME_PRESETS: ThemeOption[];
  *
  * 参考 L7 实现：使用 mapsService.getMarkerContainer() 作为 Marker/Popup 的 DOM 容器
  */
-export declare function InteractionRenderer({ interactions }: InteractionRendererProps): JSX_2.Element;
+export declare function InteractionRenderer({ interactions }: InteractionRendererProps): default_2.JSX.Element;
 
 declare interface InteractionRendererProps {
     interactions: InteractionSchema[];
@@ -2259,7 +2317,7 @@ export declare interface LayerItem {
 /**
  * 批量渲染图层
  */
-export declare function LayerRenderer({ layers, eventHandlers }: LayerRendererProps): JSX_2.Element | null;
+export declare function LayerRenderer({ layers, eventHandlers }: LayerRendererProps): default_2.JSX.Element | null;
 
 declare interface LayerRendererProps {
     layers: LayerSchema[];
@@ -2301,7 +2359,7 @@ export declare interface LayerSchema {
     events?: LayerEventSchema;
 }
 
-export declare function LayerSwitchControl({ position, layers, onToggle, onOpacityChange, className, style, }: LayerSwitchControlProps): JSX_2.Element | null;
+export declare function LayerSwitchControl({ position, layers, onToggle, onOpacityChange, className, style, }: LayerSwitchControlProps): default_2.JSX.Element | null;
 
 export declare interface LayerSwitchControlProps {
     /** 控件位置，默认 topright */
@@ -2329,7 +2387,7 @@ export declare type LayerType = 'point' | 'line' | 'polygon' | 'heatmap' | 'rast
  *
  * @see legend.md §2 分类与枚举图例
  */
-export declare function LegendCategories({ title, labels, colors, swatchShape, grid, className, interaction, }: LegendCategoriesProps): JSX_2.Element;
+export declare function LegendCategories({ title, labels, colors, swatchShape, grid, className, interaction, }: LegendCategoriesProps): default_2.JSX.Element;
 
 declare interface LegendCategoriesProps extends LegendCategoriesSchema {
     className?: string;
@@ -2348,7 +2406,7 @@ export declare interface LegendCategoriesSchema {
     grid?: boolean;
 }
 
-export declare function LegendControl({ position, className, style, children, }: LegendControlProps): JSX_2.Element | null;
+export declare function LegendControl({ position, className, style, children, }: LegendControlProps): default_2.JSX.Element | null;
 
 export declare interface LegendControlProps {
     position?: L7ControlPosition;
@@ -2370,7 +2428,7 @@ export declare interface LegendControlProps {
  *
  * @see legend.md §4 离散与发散图例
  */
-export declare function LegendDiverging({ title, colors, labels, middleLabel, className, }: LegendDivergingProps): JSX_2.Element;
+export declare function LegendDiverging({ title, colors, labels, middleLabel, className, }: LegendDivergingProps): default_2.JSX.Element;
 
 declare interface LegendDivergingProps extends LegendDivergingSchema {
     className?: string;
@@ -2401,7 +2459,7 @@ export declare interface LegendDivergingSchema {
  *
  * @see legend.md §2 分类与枚举图例 (图标变体)
  */
-export declare function LegendIcon({ title, items, className, interaction }: LegendIconProps): JSX_2.Element;
+export declare function LegendIcon({ title, items, className, interaction }: LegendIconProps): default_2.JSX.Element;
 
 export declare interface LegendIconItem {
     icon: string;
@@ -2442,7 +2500,7 @@ export declare interface LegendInteractionCallbacks {
  *
  * @see legend.md — LineWidth 类型图例
  */
-export declare function LegendLineWidth({ title, color, items, className, interaction, }: LegendLineWidthProps): JSX_2.Element;
+export declare function LegendLineWidth({ title, color, items, className, interaction, }: LegendLineWidthProps): default_2.JSX.Element;
 
 declare interface LegendLineWidthProps extends LegendLineWidthSchema {
     className?: string;
@@ -2474,7 +2532,7 @@ export declare interface LegendLineWidthSchema {
  *
  * @see LegendSize 为新版推荐的替代组件，提供更灵活的 items 配置
  */
-export declare function LegendProportion({ title, labels, fillColor, className, }: LegendProportionProps): JSX_2.Element;
+export declare function LegendProportion({ title, labels, fillColor, className, }: LegendProportionProps): default_2.JSX.Element;
 
 declare interface LegendProportionProps extends LegendProportionSchema {
     className?: string;
@@ -2500,7 +2558,7 @@ export declare interface LegendProportionSchema {
  *
  * @see legend.md §3 连续与分级图例
  */
-export declare function LegendRamp({ title, labels, colors, isContinuous, showTicks, brushable, className, interaction, }: LegendRampProps): JSX_2.Element;
+export declare function LegendRamp({ title, labels, colors, isContinuous, showTicks, brushable, className, interaction, }: LegendRampProps): default_2.JSX.Element;
 
 declare interface LegendRampProps extends LegendRampSchema {
     className?: string;
@@ -2532,7 +2590,7 @@ export declare interface LegendRampSchema {
  *
  * @see legend.md §1 基础视觉准则
  */
-export declare function LegendRenderer({ legends, className, style, interaction, }: LegendRendererProps): JSX_2.Element | null;
+export declare function LegendRenderer({ legends, className, style, interaction, }: LegendRendererProps): default_2.JSX.Element | null;
 
 declare interface LegendRendererProps {
     legends: LegendSchema[];
@@ -2558,7 +2616,7 @@ export declare type LegendSchema = LegendCategoriesSchema | LegendRampSchema | L
  *
  * @see legend.md — Size / Proportion 类型图例
  */
-export declare function LegendSize({ title, fillColor, items, className, }: LegendSizeProps): JSX_2.Element;
+export declare function LegendSize({ title, fillColor, items, className, }: LegendSizeProps): default_2.JSX.Element;
 
 declare interface LegendSizeProps extends LegendSizeSchema {
     className?: string;
@@ -2594,7 +2652,7 @@ export declare type LegendSwatchShape = 'square' | 'circle';
  *
  * @see legend.md §3.3 Threshold 自定义分段
  */
-export declare function LegendThreshold({ title, ranges, colors, className, interaction, }: LegendThresholdProps): JSX_2.Element;
+export declare function LegendThreshold({ title, ranges, colors, className, interaction, }: LegendThresholdProps): default_2.JSX.Element;
 
 declare interface LegendThresholdProps extends LegendThresholdSchema {
     className?: string;
@@ -2620,7 +2678,7 @@ export declare interface LegendThresholdSchema {
  * </AiMap>
  * ```
  */
-export declare function LineLayer({ source, sourceType, sourceConfig, onClick, onMouseMove, onMouseEnter, onMouseLeave, onLayerCreated, ...rest }: LineLayerProps): JSX_2.Element | null;
+export declare function LineLayer({ source, sourceType, sourceConfig, onClick, onMouseMove, onMouseEnter, onMouseLeave, onLayerCreated, ...rest }: LineLayerProps): default_2.JSX.Element | null;
 
 export declare interface LineLayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig'> {
     source: LayerSchema['source'];
@@ -2639,7 +2697,7 @@ declare interface LinkAnnotationProperties extends AnnotationPropertiesBase {
     title?: string;
 }
 
-export declare function LogoControl({ logos, position, className, style, }: LogoControlProps): JSX_2.Element;
+export declare function LogoControl({ logos, position, className, style, }: LogoControlProps): default_2.JSX.Element;
 
 export declare interface LogoControlProps {
     /** Logo 列表，支持多张 */
@@ -2728,7 +2786,7 @@ export declare interface MapEventPayload {
     rotation: number;
 }
 
-export declare function MapSceneRenderer({ mapSchema, children, onSceneReady, mapEventHandlers, events, className, style, }: MapSceneRendererProps): JSX_2.Element;
+export declare function MapSceneRenderer({ mapSchema, children, onSceneReady, mapEventHandlers, events, className, style, }: MapSceneRendererProps): default_2.JSX.Element;
 
 declare interface MapSceneRendererProps {
     mapSchema: MapSchema;
@@ -2761,7 +2819,7 @@ export declare type MapStylePreset = 'light' | 'dark' | 'normal' | 'darkblue' |
 
 export declare type MapTheme = 'light' | 'dark' | 'system';
 
-export declare function MapThemeControl({ position, options: propOptions, defaultValue, onThemeChange, className, style, }: MapThemeControlProps): JSX_2.Element;
+export declare function MapThemeControl({ position, options: propOptions, defaultValue, onThemeChange, className, style, }: MapThemeControlProps): default_2.JSX.Element;
 
 export declare interface MapThemeControlProps {
     /** 控件位置，默认 topright */
@@ -2797,7 +2855,7 @@ declare interface MarkerAnnotationProperties extends AnnotationPropertiesBase {
  * - 视觉分级：小规模(2-99)、中规模(100-999)、大规模(1000+)
  * - 交互：悬停放大(scale-110)、点击缩放、最大级别蜘蛛布局展开
  */
-export declare function MarkerClusterLayer({ source, sourceType, sourceConfig, gridSize, minClusterSize, animationDuration, easing, onPointClick, onClusterClick, }: MarkerClusterLayerProps): JSX_2.Element;
+export declare function MarkerClusterLayer({ source, sourceType, sourceConfig, gridSize, minClusterSize, animationDuration, easing, onPointClick, onClusterClick, }: MarkerClusterLayerProps): default_2.JSX.Element;
 
 export declare interface MarkerClusterLayerProps {
     source: LayerSchema['source'];
@@ -2909,7 +2967,7 @@ export declare interface MobileLegendConfig {
  * - 展开时 max-h-[65vh]，收起时 max-h-14
  * - 支持所有图例类型
  */
-export declare function MobileSheetLegend({ legends, className, interaction, }: MobileSheetLegendProps): JSX_2.Element | null;
+export declare function MobileSheetLegend({ legends, className, interaction, }: MobileSheetLegendProps): default_2.JSX.Element | null;
 
 declare interface MobileSheetLegendProps {
     legends: LegendSchema[];
@@ -2920,7 +2978,7 @@ declare interface MobileSheetLegendProps {
 /**
  * 移动端底部工具栏
  */
-export declare function MobileToolbar({ config, className }: MobileToolbarProps): JSX_2.Element;
+export declare function MobileToolbar({ config, className }: MobileToolbarProps): default_2.JSX.Element;
 
 export declare interface MobileToolbarConfig {
     items: string[];
@@ -2932,7 +2990,7 @@ declare interface MobileToolbarProps {
     className?: string;
 }
 
-export declare function MouseLocationControl({ position, precision, transform, className, style, }: MouseLocationControlProps): JSX_2.Element;
+export declare function MouseLocationControl({ position, precision, transform, className, style, }: MouseLocationControlProps): default_2.JSX.Element;
 
 /**
  * MouseLocation 鼠标坐标控件
@@ -2962,6 +3020,18 @@ declare interface NoteAnnotationProperties extends AnnotationPropertiesBase {
     body?: string;
 }
 
+/** 裁剪后 Blob 上传到 CDN 的回调 */
+declare type OnCropUpload = (blob: Blob, dimensions: {
+    width: number;
+    height: number;
+}) => Promise<UploadResult>;
+
+/** 导出上传到 CDN 的回调 */
+declare type OnExportUpload = (exportData: ExportUploadData) => Promise<void>;
+
+/** 文件上传到 CDN 的回调 */
+declare type OnImageUpload = (file: File) => Promise<UploadResult>;
+
 /**
  * Mapbox / Maplibre 主题预设 — 基于 openfreemap 样式
  */
@@ -2981,7 +3051,7 @@ export declare function parseSchema(schema: AiMapSchema): AiMapSchema;
  * </AiMap>
  * ```
  */
-export declare function PointLayer({ source, sourceType, sourceConfig, onClick, onMouseMove, onMouseEnter, onMouseLeave, onLayerCreated, ...rest }: PointLayerProps): JSX_2.Element | null;
+export declare function PointLayer({ source, sourceType, sourceConfig, onClick, onMouseMove, onMouseEnter, onMouseLeave, onLayerCreated, ...rest }: PointLayerProps): default_2.JSX.Element | null;
 
 export declare interface PointLayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig'> {
     /** 数据源 — JSON 数组、GeoJSON 或 URL */
@@ -3005,7 +3075,7 @@ export declare interface PointLayerProps extends Omit<LayerSchema, 'type' | 'sou
 /**
  * 面图层组件
  */
-export declare function PolygonLayer({ source, sourceType, sourceConfig, onClick, onMouseMove, onMouseEnter, onMouseLeave, onLayerCreated, ...rest }: PolygonLayerProps): JSX_2.Element | null;
+export declare function PolygonLayer({ source, sourceType, sourceConfig, onClick, onMouseMove, onMouseEnter, onMouseLeave, onLayerCreated, ...rest }: PolygonLayerProps): default_2.JSX.Element | null;
 
 export declare interface PolygonLayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig'> {
     source: LayerSchema['source'];
@@ -3138,7 +3208,7 @@ export declare interface RampColors {
 /**
  * 栅格图层组件
  */
-export declare function RasterLayer({ source, sourceType, sourceConfig, onClick, ...rest }: RasterLayerProps): JSX_2.Element | null;
+export declare function RasterLayer({ source, sourceType, sourceConfig, onClick, ...rest }: RasterLayerProps): default_2.JSX.Element | null;
 
 export declare interface RasterLayerProps extends Omit<LayerSchema, 'type' | 'source' | 'sourceType' | 'sourceConfig'> {
     source: LayerSchema['source'];
@@ -3195,7 +3265,7 @@ declare interface ResponsiveContextValue {
     schema: ResponsiveSchema | undefined;
 }
 
-export declare function ResponsiveProvider({ responsive, children }: ResponsiveProviderProps): JSX_2.Element;
+export declare function ResponsiveProvider({ responsive, children }: ResponsiveProviderProps): default_2.JSX.Element;
 
 declare interface ResponsiveProviderProps {
     responsive?: ResponsiveSchema;
@@ -3229,7 +3299,7 @@ export declare interface ResponsiveSchema {
  * />
  * ```
  */
-export declare function RouteLayer({ path, segments, stops, routeType, onRouteQuery, onRouteResult, color, lineWidth, opacity, glow, animate, animateSpeed, stopSize, stopColor, endColor, showStopIndex, showStopName, stopNameColor, stopNameSize, stopRenderer, stopMarkerVariant, stopIconMap, stopIconField, stopIconSize, stopIconAnchor, showStopPopup, activeColor, onPathClick, onStopClick, }: RouteLayerProps): JSX_2.Element | null;
+export declare function RouteLayer({ path, segments, stops, routeType, onRouteQuery, onRouteResult, color, lineWidth, opacity, glow, animate, animateSpeed, stopSize, stopColor, endColor, showStopIndex, showStopName, stopNameColor, stopNameSize, stopRenderer, stopMarkerVariant, stopIconMap, stopIconField, stopIconSize, stopIconAnchor, showStopPopup, activeColor, onPathClick, onStopClick, }: RouteLayerProps): default_2.JSX.Element | null;
 
 export declare interface RouteLayerProps {
     /** 路径坐标 — 完整线坐标或分段 */
@@ -3367,13 +3437,64 @@ export declare const SATELLITE_PROVIDER_NAMES: Record<SatelliteProvider, string>
  * </AiMap>
  * ```
  */
-export declare function SatelliteLayer({ provider, zIndex, opacity, tiandituToken, visible, }: SatelliteLayerProps): JSX_2.Element | null;
+export declare function SatelliteLayer({ provider, zIndex, opacity, tiandituToken, visible, }: SatelliteLayerProps): default_2.JSX.Element | null;
+
+/**
+ * 卫星影像图层控件
+ *
+ * 提供卫星影像提供商切换、可见性开关和透明度调节功能。
+ * 通常与 SatelliteLayer 组件配合使用。
+ *
+ * @example
+ * ```tsx
+ * const [provider, setProvider] = useState<SatelliteProvider>('gaode');
+ * const [visible, setVisible] = useState(true);
+ * const [opacity, setOpacity] = useState(1);
+ *
+ * <AiMap map={{ basemap: 'map' }}>
+ *   <SatelliteLayer provider={provider} visible={visible} opacity={opacity} />
+ *   <SatelliteLayerControl
+ *     activeProvider={provider}
+ *     visible={visible}
+ *     opacity={opacity}
+ *     onProviderChange={setProvider}
+ *     onVisibleChange={setVisible}
+ *     onOpacityChange={setOpacity}
+ *   />
+ * </AiMap>
+ * ```
+ */
+export declare function SatelliteLayerControl({ position, activeProvider, visible, opacity, onProviderChange, onVisibleChange, onOpacityChange, providers, className, style, }: SatelliteLayerControlProps): default_2.JSX.Element;
+
+/**
+ * 卫星影像控件配置
+ */
+export declare interface SatelliteLayerControlProps {
+    /** 控件位置，默认 topright */
+    position?: L7ControlPosition;
+    /** 当前激活的提供商 */
+    activeProvider?: SatelliteProvider;
+    /** 是否可见，默认 true */
+    visible?: boolean;
+    /** 透明度 0~1，默认 1 */
+    opacity?: number;
+    /** 提供商切换回调 */
+    onProviderChange?: (provider: SatelliteProvider) => void;
+    /** 可见性切换回调 */
+    onVisibleChange?: (visible: boolean) => void;
+    /** 透明度变化回调 */
+    onOpacityChange?: (opacity: number) => void;
+    /** 支持的提供商列表，默认全部 */
+    providers?: SatelliteProvider[];
+    className?: string;
+    style?: default_2.CSSProperties;
+}
 
 /** 卫星影像图层配置 */
 export declare interface SatelliteLayerProps {
     /** 影像提供商，默认 'gaode' */
     provider?: SatelliteProvider;
-    /** 图层层级，默认 0（底层） */
+    /** 图层层级，默认 -1（最底层，确保不覆盖矢量图层） */
     zIndex?: number;
     /** 图层透明度 0~1，默认 1 */
     opacity?: number;
@@ -3386,7 +3507,7 @@ export declare interface SatelliteLayerProps {
 /** 卫星影像数据源类型 */
 export declare type SatelliteProvider = 'gaode' | 'tianditu' | 'google';
 
-export declare function ScaleControl({ position, maxWidth, metric, imperial, updateWhenIdle, className, style, }: ScaleControlProps): JSX_2.Element;
+export declare function ScaleControl({ position, maxWidth, metric, imperial, updateWhenIdle, className, style, }: ScaleControlProps): default_2.JSX.Element;
 
 /**
  * Scale 比例尺控件
@@ -3413,7 +3534,7 @@ export declare interface ScaleControlProps {
     style?: default_2.CSSProperties;
 }
 
-export declare function SceneProvider({ scene, children }: SceneProviderProps): JSX_2.Element;
+export declare function SceneProvider({ scene, children }: SceneProviderProps): default_2.JSX.Element;
 
 declare interface SceneProviderProps {
     scene: Scene | null;
@@ -3443,7 +3564,7 @@ export declare interface SchemaDiffResult {
     legendsChanged: boolean;
 }
 
-export declare function SchemaProvider({ schema, children }: SchemaProviderProps): JSX_2.Element;
+export declare function SchemaProvider({ schema, children }: SchemaProviderProps): default_2.JSX.Element;
 
 declare interface SchemaProviderProps {
     schema: AiMapSchema;
@@ -3464,7 +3585,7 @@ export declare interface ScreenPosition {
  * <SearchBar placeholder="搜索地点..." onSearch={(v) => console.log(v)} />
  * ```
  */
-export declare function SearchBar({ placeholder, onSearch, onFilter, className, trailing, }: SearchBarProps): JSX_2.Element;
+export declare function SearchBar({ placeholder, onSearch, onFilter, className, trailing, }: SearchBarProps): default_2.JSX.Element;
 
 export declare interface SearchBarProps {
     /** 占位文本 */
@@ -3547,7 +3668,7 @@ export declare interface ThemeOption {
  * - `dark`: 暗色主题
  * - `system`: 跟随系统 prefers-color-scheme
  */
-export declare function ThemeProvider({ defaultTheme, target, children, }: ThemeProviderProps): JSX_2.Element;
+export declare function ThemeProvider({ defaultTheme, target, children, }: ThemeProviderProps): default_2.JSX.Element;
 
 export declare interface ThemeProviderProps {
     /** 默认主题，默认 'light' */
@@ -3717,6 +3838,12 @@ export declare interface TooltipSchema {
  */
 export declare type TooltipVariant = 'dark' | 'glass' | 'light';
 
+/** 上传回调返回值：简单 URL 字符串或包含元数据的对象 */
+declare type UploadResult = string | {
+    url: string;
+    [key: string]: unknown;
+};
+
 export declare function useControlContainer(): boolean;
 
 export declare function useEventBus(): EventBus;
@@ -3816,7 +3943,7 @@ declare interface VisualConfig {
     style?: Record<string, unknown>;
 }
 
-export declare function ZoomControl({ position, zoomInText, zoomInTitle, zoomOutText, zoomOutTitle, showZoom, className, style, }: ZoomControlProps): JSX_2.Element;
+export declare function ZoomControl({ position, zoomInText, zoomInTitle, zoomOutText, zoomOutTitle, showZoom, className, style, }: ZoomControlProps): default_2.JSX.Element;
 
 /**
  * Zoom 控件