bigmap-plugin 1.0.4 → 1.0.6

package/dist/index.d.ts

@@ -66,9 +66,9 @@ default: boolean;
 onClick?: ((...args: any[]) => any) | undefined;
 }>, {
 type: string;
+loading: boolean;
 size: string;
 disabled: boolean;
-loading: boolean;
 block: boolean;
 }, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
 
@@ -665,12 +665,106 @@ export declare class ConfigManager {
     reset(): void;
 }
 
-/** 等高线显示配置（3D 模式"等高线"开关参数，源自官方地形示例） */
-declare interface ContourConfig {
-    /** 等高线间距（m，默认 150） */
-    spacing?: number;
-    /** 等高线线宽（px，默认 2） */
-    width?: number;
+/** 等高线高程色带节点（height 为高程米数，color 为对应颜色） */
+export declare interface ContourColorStop {
+    /** 高程（m） */
+    height: number;
+    /** 该高程对应的颜色（CSS 颜色字符串） */
+    color: string;
+}
+
+/**
+ * 等高线显示配置（3D 模式"等高线"开关参数）。
+ * 字段与随包发布的 BigemapElevationContourLayer 一一对应，未配置项使用库内置默认值。
+ */
+export declare interface ContourConfig {
+    /** 等高距（m，默认 150） */
+    contourSpacing?: number;
+    /** 彩色主线宽度（px，默认 2） */
+    contourWidth?: number;
+    /** 黑色描边宽度（px，默认 2） */
+    outlineWidth?: number;
+    /** 每隔多少条等高线显示一个高程标签（默认 5） */
+    labelEvery?: number;
+    /** 当前视区最多显示的高程标签数量（默认 28） */
+    maxLabels?: number;
+    /** 标签之间的最小屏幕间距（px，默认 140） */
+    labelMinDistance?: number;
+    /** 标签描边宽度（px，默认 3） */
+    labelOutlineWidth?: number;
+    /** 高程采样步长（px，默认 80） */
+    sampleStep?: number;
+    /** 视口扫描步长（px，默认 120） */
+    scanStep?: number;
+    /** 视口边缘留白（px，默认 48） */
+    viewportMargin?: number;
+    /** 图例色阶间隔（m，默认 500） */
+    legendColorStep?: number;
+    /** 色带最低高程（m）：未配置时取 colorStops 首个节点，或库内置默认值 */
+    minHeight?: number;
+    /** 色带最高高程（m）：未配置时取 colorStops 末个节点，或库内置默认值 */
+    maxHeight?: number;
+    /** 高程颜色节点（默认使用库内置 20 级色带；配置后默认按首尾节点推导高程范围） */
+    colorStops?: ContourColorStop[];
+}
+
+/** 等高线库加载参数（serverUrl/libsUrl 透传至 ScriptLoader 解析本地库路径） */
+declare interface ContourDeps {
+    /** 地图资源服务器地址（本地库不依赖，可省略） */
+    serverUrl?: string;
+    /** 本地库路径前缀，默认 /libs */
+    libsUrl?: string;
+}
+
+/** 高程标签清空结果 */
+export declare interface ContourLabelClearResult {
+    /** 清空状态：cleared 已清空 / empty 无标签 / busy 加载中 / destroyed 已销毁 */
+    status: 'cleared' | 'empty' | 'busy' | 'destroyed';
+    /** 清空后的标签数量（恒为 0） */
+    labelCount: number;
+}
+
+/** 高程标签加载结果 */
+export declare interface ContourLabelResult {
+    /** 加载状态 */
+    status: ContourLabelStatus;
+    /** 当前视区内的标签数量 */
+    labelCount: number;
+    /** 异常信息（status 为 error 时存在） */
+    error?: Error;
+}
+
+/** 高程标签加载状态：success 成功 / no-results 无结果 / terrain-loading 地形未就绪 / unsupported SDK 不支持 / hidden 已隐藏 / busy 加载中 / destroyed 已销毁 / error 异常 */
+export declare type ContourLabelStatus = 'success' | 'no-results' | 'terrain-loading' | 'unsupported' | 'hidden' | 'busy' | 'destroyed' | 'error';
+
+/** 高程色带图例数据（用于绘制 HTML 图例） */
+export declare interface ContourLegendData {
+    /** 色带最低高程（m） */
+    minHeight: number;
+    /** 色带最高高程（m） */
+    maxHeight: number;
+    /** 图例色阶间隔（m） */
+    legendColorStep: number;
+    /** 高程颜色节点（按高程升序） */
+    colorStops: ContourColorStop[];
+}
+
+/** 等高线公开状态（供 UI 更新按钮与提示文案） */
+export declare interface ContourState {
+    /** 等高线是否显示 */
+    enabled: boolean;
+    /** 高程标签是否正在加载 */
+    labelsLoading: boolean;
+    /** 已加载的固定高程标签数量 */
+    labelCount: number;
+    /** 等高距（m） */
+    contourSpacing: number;
+    /** 标注间隔（m，= 等高距 × labelEvery） */
+    labelSpacing: number;
+    /** 彩色主线宽度（px） */
+    contourWidth: number;
+    /** 黑色描边宽度（px） */
+    outlineWidth: number;
 }
 
 /**
@@ -696,8 +790,11 @@ export declare function createGeoServerWmtsProvider(config: GeoServerSourceConfi
  */
 export declare function createSearchShapeFromDrawEvent(event: DrawEventData | null | undefined): SearchShape | null;
 
-/** 默认等高线配置（源自官方地形示例，仅等高线不叠加高程色带，可按 contourConfig 覆盖） */
-export declare const DEFAULT_CONTOUR_CONFIG: Required<ContourConfig>;
+/** 默认等高线配置（彩色等高线 + 视区高程标签；colorStops/minHeight/maxHeight 留空由库按内置色带推导） */
+export declare const DEFAULT_CONTOUR_CONFIG: NormalizedContourConfig;
+
+/** 默认 KML 加载配置（可按 loadFromUrl / loadFromText 传入的 config 覆盖） */
+export declare const DEFAULT_KML_CONFIG: NormalizedKmlConfig;
 
 /** 默认本地库文件路径（随包发布的 bigemap-plot / circleWave 等） */
 export declare const DEFAULT_LIBS_URL = "/libs";
@@ -1264,6 +1361,194 @@ export declare interface IconTextConfig {
 /** 判断是否为合法的图标名称 */
 export declare function isIconName(name: string): name is IconName;
 
+/** KML 加载配置（全部可选，缺省值见 DEFAULT_KML_CONFIG） */
+export declare interface KmlConfig {
+    /** 默认面填充色（KML 未声明 PolyStyle 时使用），默认 #3d8bff */
+    fillColor?: string;
+    /** 默认面填充透明度（0~1），默认 0.35 */
+    fillAlpha?: number;
+    /**
+     * 填充/轮廓调色板（#rrggbb 数组），默认 []（不启用）
+     * 非空时按要素顺序轮换取色，并覆盖 KML 自身颜色，便于区分相邻区域。
+     */
+    fillPalette?: string[];
+    /** 默认线颜色，默认 #ffffff */
+    strokeColor?: string;
+    /** 默认线透明度（0~1），默认 1 */
+    strokeAlpha?: number;
+    /** 默认线宽（px），默认 2 */
+    strokeWidth?: number;
+    /** 默认点颜色，默认 #ff3b30 */
+    pointColor?: string;
+    /** 默认点像素大小，默认 8 */
+    pointPixelSize?: number;
+    /** 是否显示要素名称标签（落点取要素代表位置），默认 true */
+    showLabel?: boolean;
+    /** 名称标签文字颜色，默认 #ffffff */
+    labelColor?: string;
+    /** 名称标签字号（px），默认 13 */
+    labelFontSize?: number;
+    /** 名称标签描边颜色，默认 #000000 */
+    labelOutlineColor?: string;
+    /** 是否采用 KML 内联样式（Style/styleUrl/StyleMap），默认 true；false 时统一使用上面的默认配色 */
+    useKmlStyle?: boolean;
+    /** 是否填充面（默认 true；与 KML PolyStyle.fill 同时生效为“与”关系） */
+    showFill?: boolean;
+    /** 是否绘制面外轮廓（默认 true；与 KML PolyStyle.outline 同时生效为“与”关系） */
+    showOutline?: boolean;
+    /** 是否解析 ExtendedData 到 feature.properties，默认 true */
+    extractProperties?: boolean;
+    /** 加载成功后是否自动飞行定位到数据范围，默认 true */
+    autoFlyTo?: boolean;
+    /** 远程加载超时（ms），默认 15000 */
+    timeout?: number;
+}
+
+/** KML 加载错误 */
+export declare class KmlError extends Error {
+    code: KmlErrorCode;
+    details?: unknown;
+    constructor(message: string, code: KmlErrorCode, details?: unknown);
+}
+
+/**
+ * KML 加载错误体系
+ * 以 KmlError 统一承载"可预期的失败"（地址无效 / 文本无效 / 解析失败 / 网络失败 / 超时 / 地图未就绪），
+ * 便于调用方按 code 分支处理，并直接展示 error.message 作为用户提示。
+ */
+/** KML 加载错误码 */
+export declare enum KmlErrorCode {
+    /** 地址无效（空值、非字符串、协议不支持或无法解析） */
+    INVALID_URL = "INVALID_URL",
+    /** 文本无效（空值、非字符串或全空白） */
+    INVALID_TEXT = "INVALID_TEXT",
+    /** KML 解析失败（XML 格式错误或根节点不是 <kml>） */
+    PARSE_FAILED = "PARSE_FAILED",
+    /** KML 中未解析到任何可渲染的几何要素 */
+    NO_FEATURES = "NO_FEATURES",
+    /** 网络请求失败（断网、跨域、DNS 等） */
+    NETWORK_FAILED = "NETWORK_FAILED",
+    /** HTTP 状态异常（如 404 / 500） */
+    HTTP_ERROR = "HTTP_ERROR",
+    /** 请求超时 */
+    TIMEOUT = "TIMEOUT",
+    /** 地图未就绪（viewer/entities 或 bmgl 不可用） */
+    MAP_NOT_READY = "MAP_NOT_READY",
+    /** 其他未预期的加载失败 */
+    LOAD_FAILED = "LOAD_FAILED"
+}
+
+/** 解析后的 KML 要素（对应一个 Placemark；MultiGeometry 已展开） */
+export declare interface KmlFeature {
+    /** 要素 ID（KML Placemark 的 id，缺省时按序号生成） */
+    id: string;
+    /** 名称（<name>） */
+    name: string;
+    /** 描述（<description>） */
+    description?: string;
+    /** 是否可见（KML <visibility>0</visibility> 时为 false） */
+    visible: boolean;
+    /** ExtendedData 展开后的键值对（SchemaData/SimpleData 与 Data/value） */
+    properties: Record<string, string>;
+    /** 解析合并后的样式 */
+    style: KmlStyle;
+    /** 该要素包含的几何（已展开 MultiGeometry） */
+    geometries: KmlGeometry[];
+}
+
+/** 解析后的几何（MultiGeometry 已在解析阶段展开为多个几何，故此处不含 MultiGeometry） */
+declare type KmlGeometry = KmlPointGeometry | KmlLineStringGeometry | KmlPolygonGeometry;
+
+/** KML 线几何 */
+declare interface KmlLineStringGeometry {
+    type: 'LineString';
+    /** 折线坐标序列（至少 2 个有效点） */
+    coordinates: Coordinate[];
+}
+
+/** KML 加载成功后的结果 */
+declare interface KmlLoadResult {
+    /** 数据来源 */
+    source: 'url' | 'text';
+    /** 数据来源地址（source 为 url 时有效） */
+    url: string;
+    /** 要素（Placemark）数量 */
+    featureCount: number;
+    /** 面（Polygon）数量 */
+    polygonCount: number;
+    /** 线（LineString）数量 */
+    lineCount: number;
+    /** 点（Point）数量 */
+    pointCount: number;
+    /** 解析后的要素列表（含 ExtendedData 属性，可供弹窗等二次消费） */
+    features: KmlFeature[];
+}
+
+/** KML 点几何 */
+declare interface KmlPointGeometry {
+    type: 'Point';
+    /** 点坐标（取 KML coordinates 的首个三元组） */
+    coordinates: Coordinate;
+}
+
+/** KML 面几何 */
+declare interface KmlPolygonGeometry {
+    type: 'Polygon';
+    /** 外环坐标（对应 outerBoundaryIs） */
+    outer: Coordinate[];
+    /** 内环（洞）坐标列表（对应 innerBoundaryIs，可多个） */
+    holes: Coordinate[][];
+}
+
+/** KML 加载状态（响应式） */
+export declare interface KmlState {
+    /** 加载状态：idle 未加载 / loading 加载中 / success 成功 / error 失败 */
+    status: 'idle' | 'loading' | 'success' | 'error';
+    /** 数据来源：url 远程地址 / text 文本；未加载为 null */
+    source: 'url' | 'text' | null;
+    /** 数据来源地址（source 为 url 时有效） */
+    url: string;
+    /** 要素（Placemark）数量 */
+    featureCount: number;
+    /** 面（Polygon）数量 */
+    polygonCount: number;
+    /** 线（LineString）数量 */
+    lineCount: number;
+    /** 点（Point）数量 */
+    pointCount: number;
+    /** 是否显示中（setVisible 控制） */
+    visible: boolean;
+    /** 错误提示（status 为 error 时有效） */
+    error: string | null;
+}
+
+/**
+ * KML 样式（已归一化为 CSS 颜色 + 0~1 透明度）
+ * 由内联 Style / styleUrl 引用的 Style / StyleMap 合并而来。
+ */
+declare interface KmlStyle {
+    /** 面填充色（CSS 颜色），来自 PolyStyle.color */
+    fillColor?: string;
+    /** 面填充透明度（0~1），来自 PolyStyle.color 的 alpha 分量 */
+    fillAlpha?: number;
+    /** 线颜色（CSS 颜色），来自 LineStyle.color */
+    lineColor?: string;
+    /** 线透明度（0~1），来自 LineStyle.color 的 alpha 分量 */
+    lineAlpha?: number;
+    /** 线宽（px），来自 LineStyle.width */
+    lineWidth?: number;
+    /** 点/图标颜色，来自 IconStyle.color */
+    iconColor?: string;
+    /** 图标地址，来自 IconStyle.Icon.href */
+    iconHref?: string;
+    /** 图标缩放，来自 IconStyle.scale */
+    iconScale?: number;
+    /** PolyStyle.fill：false 表示不填充（未声明时视为填充） */
+    fill?: boolean;
+    /** PolyStyle.outline：false 表示不绘制外轮廓（未声明时视为绘制） */
+    outline?: boolean;
+}
+
 /** 图层配置 */
 export declare interface LayerConfig {
     id: string;
@@ -1345,7 +1630,7 @@ export declare const logger: {
 export declare type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
 
 /** MapView 从 MapConfig 消费的字段清单（单一来源：MapViewProps 类型与组件 config 映射均由此派生） */
-declare const MAP_VIEW_CONFIG_KEYS: readonly ["containerId", "position", "serverUrl", "accessToken", "libsUrl", "showSearch", "showControls", "showDeleteControls", "showStatus", "tools", "searchDebounceTime", "wmtsUrlProvider", "geoserver", "contourConfig", "lightingConfig"];
+declare const MAP_VIEW_CONFIG_KEYS: readonly ["containerId", "position", "serverUrl", "accessToken", "libsUrl", "mapId", "terrainId", "baseLayers", "showSearch", "showControls", "showDeleteControls", "showStatus", "tools", "searchDebounceTime", "wmtsUrlProvider", "geoserver", "contourConfig", "lightingConfig"];
 
 /** 地图实例 API（MapContainer/MapView 组件 expose 的完整能力集） */
 export declare interface MapApi {
@@ -1379,8 +1664,16 @@ export declare interface MapApi {
     deleteEntity: (id?: string) => boolean;
     /** 切换"地图名称"注记开关 */
     setMapNameVisible: (visible: boolean) => void;
-    /** 切换等高线显示（仅 3D 模式有效，2D 自动关闭） */
-    setContourVisible: (visible: boolean) => void;
+    /** 切换彩色等高线显示（仅 3D 模式有效，2D 自动关闭；首次开启时按需加载等高线库） */
+    setContourVisible: (visible: boolean) => Promise<void>;
+    /** 等高线状态（响应式：enabled/labelsLoading/labelCount/contourSpacing/labelSpacing/contourWidth/outlineWidth） */
+    contourState: Ref<ContourState>;
+    /** 加载当前视区高程标签（需先开启等高线） */
+    loadContourLabels: () => Promise<ContourLabelResult>;
+    /** 移除全部高程标签（不影响影像与等高线材质） */
+    clearContourLabels: () => ContourLabelClearResult;
+    /** 获取高程色带图例数据（未开启等高线时返回 null） */
+    getContourLegend: () => ContourLegendData | null;
     /** 轨迹回放状态（响应式：status/currentTime/duration/progress/pointCount） */
     trajectoryState: Ref<TrajectoryState>;
     /** 加载轨迹并创建可视化（2D/3D 均可用；成功且 autoPlay 时自动播放） */
@@ -1405,6 +1698,16 @@ export declare interface MapApi {
     setMaskVisible: (visible: boolean) => void;
     /** 清除遮罩并复位状态 */
     clearMask: () => void;
+    /** KML 加载状态（响应式：status/source/各类计数/visible/error） */
+    kmlState: Ref<KmlState>;
+    /** 通过 KML 文件 URL 加载并渲染（失败时 reject KmlError，并写入 kmlState.error） */
+    loadKmlFromUrl: (url: string, config?: Partial<KmlConfig>) => Promise<KmlLoadResult>;
+    /** 通过 KML 文本内容加载并渲染（失败时 reject KmlError，并写入 kmlState.error） */
+    loadKmlFromText: (text: string, config?: Partial<KmlConfig>) => Promise<KmlLoadResult>;
+    /** 切换 KML 数据显隐（保留已加载数据） */
+    setKmlVisible: (visible: boolean) => void;
+    /** 清空 KML 数据与实体并复位状态 */
+    clearKml: () => void;
     /** 天气状态（响应式：type/active） */
     weatherState: Ref<WeatherState>;
     /** 切换天气特效（clear=晴/无；rain=下雨；snow=下雪），2D/3D 通用 */
@@ -1456,6 +1759,11 @@ export declare interface MapConfig {
     mapId?: string;
     /** 地形ID */
     terrainId?: string;
+    /**
+     * 底图图层 mapId 列表（按数组顺序自下而上叠加）。
+     * 传入则按传入值加载（配置优先）；未传入时回退默认底图（卫星影像 + 街道地名）。
+     */
+    baseLayers?: string[];
     /** 是否显示加载动画 */
     showLoading?: boolean;
     /** 是否显示顶部搜索组件 */
@@ -1519,6 +1827,18 @@ libsUrl: {
 type: PropType<string | undefined>;
 default: undefined;
 };
+mapId: {
+type: PropType<string | undefined>;
+default: undefined;
+};
+terrainId: {
+type: PropType<string | undefined>;
+default: undefined;
+};
+baseLayers: {
+type: PropType<string[] | undefined>;
+default: undefined;
+};
 showSearch: {
 type: PropType<boolean | undefined>;
 default: undefined;
@@ -1600,6 +1920,18 @@ libsUrl: {
 type: PropType<string | undefined>;
 default: undefined;
 };
+mapId: {
+type: PropType<string | undefined>;
+default: undefined;
+};
+terrainId: {
+type: PropType<string | undefined>;
+default: undefined;
+};
+baseLayers: {
+type: PropType<string[] | undefined>;
+default: undefined;
+};
 showSearch: {
 type: PropType<boolean | undefined>;
 default: undefined;
@@ -1662,6 +1994,9 @@ containerId: string | undefined;
 serverUrl: string | undefined;
 accessToken: string | undefined;
 libsUrl: string | undefined;
+mapId: string | undefined;
+terrainId: string | undefined;
+baseLayers: string[] | undefined;
 showSearch: boolean | undefined;
 showControls: boolean | undefined;
 showDeleteControls: boolean | undefined;
@@ -2284,12 +2619,28 @@ export declare interface NoResultsPanelProps {
     error?: boolean;
 }
 
+/** 合并默认等高线配置（colorStops/minHeight/maxHeight 留空由库推导） */
+export declare function normalizeContourConfig(config?: Partial<ContourConfig>): NormalizedContourConfig;
+
+/**
+ * 归一化后的等高线配置。
+ * colorStops / minHeight / maxHeight 允许留空：由库按内置色带或自定义色带首尾节点推导，
+ * 因此不能填入默认值（否则会覆盖"按 colorStops 推导高程范围"的库内逻辑）。
+ */
+declare type NormalizedContourConfig = Omit<Required<ContourConfig>, 'colorStops' | 'minHeight' | 'maxHeight'> & Partial<Pick<ContourConfig, 'colorStops' | 'minHeight' | 'maxHeight'>>;
+
+/** 归一化后的 KML 配置 */
+declare type NormalizedKmlConfig = Required<KmlConfig>;
+
 /** 归一化后的遮罩配置（outerRing 可选，运行时按保留区域自动推导） */
 declare type NormalizedMaskConfig = Omit<Required<MaskConfig>, 'outerRing'> & {
     /** 遮罩覆盖范围外环：默认根据保留区域边界自动外扩推导（避开整环球无法渲染）；可显式指定更大覆盖（含全球） */
     outerRing?: Coordinate[];
 };
 
+/** 合并默认 KML 配置 */
+export declare function normalizeKmlConfig(config?: Partial<KmlConfig>): NormalizedKmlConfig;
+
 /** 合并默认遮罩配置 */
 export declare function normalizeMaskConfig(config?: Partial<MaskConfig>): NormalizedMaskConfig;
 
@@ -2772,21 +3123,30 @@ export declare function useMapCircleWave(map: Ref<MapViewer | null> | MapViewer
 };
 
 /**
- * 等高线显示控制
+ * 彩色等高线显示控制
  * @param map    地图实例引用
  * @param config 等高线配置（可选项，未配置使用默认常量）
+ * @param deps   按需加载等高线库所需参数（serverUrl / libsUrl）
  */
-export declare function useMapContour(map: Ref<MapViewer | null>, config?: Partial<ContourConfig>): UseMapContourResult;
+export declare function useMapContour(map: Ref<MapViewer | null>, config?: Partial<ContourConfig>, deps?: ContourDeps): UseMapContourResult;
 
 /** useMapContour 返回值 */
-declare interface UseMapContourResult {
-    /** 等高线开关状态 */
+export declare interface UseMapContourResult {
+    /** 等高线开关状态（响应式） */
     contourVisible: Ref<boolean>;
-    /** 切换等高线显隐（立即应用/移除材质） */
-    setContourVisible: (visible: boolean) => void;
-    /** 按当前开关状态重新应用材质（切回 3D 时恢复等高线） */
+    /** 等高线公开状态（响应式） */
+    contourState: Ref<ContourState>;
+    /** 切换等高线显隐（首次开启时按需加载彩色等高线库） */
+    setContourVisible: (visible: boolean) => Promise<void>;
+    /** 加载当前视区高程标签（需先开启等高线） */
+    loadLabels: () => Promise<ContourLabelResult>;
+    /** 移除全部高程标签（不影响影像与等高线材质） */
+    clearLabels: () => ContourLabelClearResult;
+    /** 获取高程色带图例数据（等高线库未就绪时返回 null） */
+    getLegendData: () => ContourLegendData | null;
+    /** 切回 3D 时按当前开关状态恢复等高线 */
     reapply: () => void;
-    /** 移除等高线材质（切到 2D 时调用，不改开关状态） */
+    /** 切到 2D 时移除地表材质（保留开关状态与已加载标签） */
     remove: () => void;
 }
 
@@ -2825,6 +3185,38 @@ export declare function useMapEntity(map: Ref<MapViewer | null>): {
     getCurrentEntityId: () => string;
 };
 
+/**
+ * KML 数据加载
+ *
+ * @param map    地图实例引用
+ * @param config 默认配置（可选项，loadFromUrl/loadFromText 时可按次覆盖）
+ */
+export declare function useMapKml(map: Ref<MapViewer | null>, config?: Partial<KmlConfig>): UseMapKmlResult;
+
+/** useMapKml 返回值 */
+export declare interface UseMapKmlResult {
+    /** 加载状态（响应式：status/source/各类计数/visible/error） */
+    state: Ref<KmlState>;
+    /** 通过 KML 文件 URL 加载（远程地址，支持相对地址） */
+    loadFromUrl: (url: string, config?: Partial<KmlConfig>) => Promise<KmlLoadResult>;
+    /** 通过 KML 文本内容加载 */
+    loadFromText: (text: string, config?: Partial<KmlConfig>) => Promise<KmlLoadResult>;
+    /** 取最近一次加载解析出的要素（含 ExtendedData 属性，供二次消费） */
+    getFeatures: () => KmlFeature[];
+    /** 整体显隐（保留已加载数据与实体） */
+    setVisible: (visible: boolean) => void;
+    /** 飞行定位到已加载数据的范围（无数据时为空操作） */
+    flyTo: () => void;
+    /** 移除可视化实体（保留已加载数据与状态，供卸载等场景） */
+    remove: () => void;
+    /** 清空数据与实体并复位状态 */
+    clear: () => void;
+    /** 按当前 2D/3D 模式重建可视化（模式切换后由内部自动调用，也支持手动调用） */
+    reapply: () => void;
+    /** 彻底清理（移除实体 + 取消模式监听 + 复位状态） */
+    destroy: () => void;
+}
+
 /**
  * 地图图层管理 Hook
  *
@@ -2999,10 +3391,12 @@ export declare function useMapView(props: MapViewProps, hooks: MapViewHooks): {
     onDelete: () => void;
     handleStartDrawing: (drawType: DrawType) => void;
     setMapNameVisible: (visible: boolean) => void;
-    setContourVisible: (visible: boolean) => void;
+    setContourVisible: (visible: boolean) => Promise<void>;
     contourVisible: Ref<boolean, boolean>;
+    contourState: Ref<ContourState, ContourState>;
     trajectoryState: Ref<TrajectoryState, TrajectoryState>;
     maskState: Ref<MaskState, MaskState>;
+    kmlState: Ref<KmlState, KmlState>;
     weatherState: Ref<WeatherState, WeatherState>;
     lightingState: Ref<LightingState, LightingState>;
     setTheme: (theme: Theme) => void;