@wenle_2523097/agri-map 1.0.2 → 1.0.4

package/dist/components/PlotLayer/toolbar.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 地块编辑工具栏组件
+ */
+import type { PlotEditToolbarProps } from '../../types';
+declare const PlotEditToolbar: ({ visible, selectedPlotId, currentMode, enabledButtons, hintMessage, showHint, warningHint, color, size, iconOnly, children, onEdit, onRedraw, onClip, onMove, onCreate, onCancel, onSave, onDelete, }: PlotEditToolbarProps) => import("react/jsx-runtime").JSX.Element;
+export default PlotEditToolbar;

package/dist/components/PlotLayer/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview PlotLayer 组件内部类型定义
+ * @module components/PlotLayer/types
+ */
+/** 虚拟化配置解析结果 */
+export interface ParsedVirtualizationConfig {
+    isVirtualized: boolean;
+    virtualMinZoom: number;
+    virtualMaxZoom: number;
+}

package/dist/components/PlotLayer/usePlotCommands.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview PlotLayer 命令式方法 hook
+ * @description 将 useImperativeHandle 中的方法逻辑提取为独立 hook
+ * @module components/PlotLayer/usePlotCommands
+ */
+import L from 'leaflet';
+import type { PlotData, PlotRef } from '../../types';
+interface UsePlotCommandsOptions {
+    map: L.Map;
+    selectedPlotId: string | number | null;
+    selectedIds: (string | number)[];
+    isControlled: boolean;
+    virtualMaxZoom: number;
+    normalizedDataSourceRef: React.MutableRefObject<PlotData[]>;
+    groupIndexRef: React.MutableRefObject<Map<string, (string | number)[]>>;
+    highlightedGroupRef: React.MutableRefObject<string | null>;
+    normalizePlot: (plot: PlotData) => {
+        boundaries: any[];
+        bounds: number[];
+    } & PlotData;
+    updateLayerSelectionStyles: () => void;
+    rebuildGeoJSONLayer: () => void;
+    onSelectRef: React.MutableRefObject<((selectedIds: (string | number)[], plotId?: string | number) => void) | undefined>;
+    setInternalSelectedIds: React.Dispatch<React.SetStateAction<(string | number)[]>>;
+    startEdit: (editType: 'redraw' | 'clip' | 'move', plotId?: string | number) => boolean;
+    startCreate: () => void;
+    clearTempLayer: () => void;
+}
+/**
+ * PlotLayer 命令式方法 hook
+ */
+export declare function usePlotCommands(ref: React.Ref<PlotRef>, options: UsePlotCommandsOptions): void;
+export {};

package/dist/components/PlotLayer/usePlotData.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview PlotLayer 数据处理 hook
+ * @description 负责数据标准化、GeoJSON 转换、分组索引构建
+ * @module components/PlotLayer/usePlotData
+ */
+import type { PlotData, PlotFieldNames, Coordinate } from '../../types';
+interface UsePlotDataOptions {
+    fieldNames?: Partial<PlotFieldNames>;
+    dataSource: PlotData[] | undefined;
+    groupKey?: string;
+}
+interface UsePlotDataResult {
+    /** 合并后的字段名配置 */
+    mergedFieldNames: Required<PlotFieldNames>;
+    /** 标准化后的数据源 */
+    normalizedDataSource: PlotData[];
+    /** 标准化地块数据：统一 boundaries 为二维数组 */
+    normalizePlot: (plot: PlotData) => PlotData & {
+        boundaries: Coordinate[];
+        bounds: number[];
+    };
+    /** 从原始数据中推导孔洞坐标 */
+    getHoles: (plot: PlotData) => Coordinate[][];
+    /** 将 PlotData[] 转换为 GeoJSON FeatureCollection */
+    convertToGeoJSON: (plotData: PlotData[]) => GeoJSON.FeatureCollection;
+    /** 分组索引 ref（fieldValue → id[]） */
+    groupIndexRef: React.MutableRefObject<Map<string, (string | number)[]>>;
+    /** 当前高亮分组 ref */
+    highlightedGroupRef: React.MutableRefObject<string | null>;
+}
+export declare function usePlotData({ fieldNames, dataSource, groupKey }: UsePlotDataOptions): UsePlotDataResult;
+export {};

package/dist/components/PlotLayer/usePlotEditMode.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview PlotLayer 编辑模式 hook
+ * @description 管理编辑模式的完整状态机：
+ * - 绘制事件监听（pm:drawvertex, pm:create, pm:cut）
+ * - 编辑模式切换（create, redraw, clip, move）
+ * - 保存/取消/删除等操作处理
+ * - 剪切碎片选择
+ * - 编辑面积标签
+ * @module components/PlotLayer/usePlotEditMode
+ */
+import L from 'leaflet';
+import type { PlotData, PlotEditMode, PlotEditResult, PlotClipResult, PlotMoveResult, PlotCreateResult, PlotDeleteResult, Coordinate, AreaUnit } from '../../types';
+import type { PlotLayer as PlotLayerType } from './leaflet-types';
+/** usePlotEditMode 输入参数 */
+export interface UsePlotEditModeOptions {
+    map: L.Map;
+    selectedPlotId: string | number | null;
+    enabledButtons: string[];
+    areaUnit: AreaUnit;
+    /** 编辑路径样式（绘制图层、剪切图层使用此样式） */
+    editPath: L.PathOptions;
+    /** 编辑模式 ref（指向 editMode state 的最新值） */
+    editModeStateRef: React.MutableRefObject<PlotEditMode>;
+    /** 编辑中的图层 ref（与主组件共享） */
+    editingLayerRef: React.MutableRefObject<PlotLayerType | null>;
+    /** 选中地块 ID ref */
+    selectedPlotIdRef: React.MutableRefObject<string | number | null>;
+    /** 标准化数据源 ref（用于 handleEdit 查找地块数据） */
+    normalizedDataSourceRef: React.MutableRefObject<PlotData[]>;
+    /** 图层 ID 映射 ref（用于 idle 清理和 startEdit） */
+    layerByIdRef: React.MutableRefObject<Record<string | number, PlotLayerType>>;
+    /** 图层重建函数 ref（clearTempLayer 使用） */
+    rebuildGeoJSONLayerRef: React.MutableRefObject<(() => void) | null>;
+    /** 编辑回调（通过 ref 传入避免闭包过期） */
+    onRedrawRef: React.MutableRefObject<((result: PlotEditResult) => void) | undefined>;
+    onClipRef: React.MutableRefObject<((result: PlotClipResult) => void) | undefined>;
+    onMoveRef: React.MutableRefObject<((result: PlotMoveResult) => void) | undefined>;
+    onCreateRef: React.MutableRefObject<((result: PlotCreateResult) => void) | undefined>;
+    onSaveRef: React.MutableRefObject<((result: PlotEditResult) => void) | undefined>;
+    onDeleteRef: React.MutableRefObject<((result: PlotDeleteResult) => void) | undefined>;
+    onEditRef: React.MutableRefObject<((result: {
+        plotId: string | number;
+        plot: PlotData;
+    }) => void) | undefined>;
+}
+/** usePlotEditMode 返回值 */
+export interface UsePlotEditModeResult {
+    /** 当前编辑模式 */
+    editMode: PlotEditMode;
+    /** 设置编辑模式 */
+    setEditMode: React.Dispatch<React.SetStateAction<PlotEditMode>>;
+    /** 是否处于预览模式（新建绘制完成但未保存） */
+    isPreviewMode: boolean;
+    /** 剪切提示信息 */
+    clipHintMessage: string;
+    /** 绘制中的坐标 ref */
+    drawingCoordinatesRef: React.MutableRefObject<Coordinate[] | Coordinate[][]>;
+    /** 是否保留临时图层 ref */
+    preserveTempLayerRef: React.MutableRefObject<boolean>;
+    /** 移除编辑面积标签 */
+    removeEditAreaMarker: () => void;
+    /** 清理编辑事件 */
+    cleanupEditEvents: (layer: L.Layer | null) => void;
+    /** 清理剪切碎片图层 */
+    cleanupFragmentLayers: () => void;
+    /** 保存 */
+    handleSave: () => void;
+    /** 取消 */
+    handleCancel: () => void;
+    /** 重绘 */
+    handleRedraw: () => void;
+    /** 剪切 */
+    handleClip: () => void;
+    /** 移动 */
+    handleMove: () => void;
+    /** 新建 */
+    handleCreate: () => void;
+    /** 编辑属性 */
+    handleEdit: () => void;
+    /** 删除 */
+    handleDelete: () => void;
+    /** 命令式：进入编辑模式 */
+    startEdit: (editType: 'redraw' | 'clip' | 'move', plotId?: string | number) => boolean;
+    /** 命令式：进入新建模式 */
+    startCreate: () => void;
+    /** 命令式：清除临时图层并刷新 */
+    clearTempLayer: () => void;
+}
+/**
+ * PlotLayer 编辑模式管理 hook
+ */
+export declare function usePlotEditMode(options: UsePlotEditModeOptions): UsePlotEditModeResult;

package/dist/components/Road/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 田间道路组件
+ */
+import '@geoman-io/leaflet-geoman-free';
+import 'leaflet-ant-path';
+import type { RoadProps, RoadRef } from '../../types';
+declare const Road: import("react").ForwardRefExoticComponent<RoadProps<Record<string, unknown>> & import("react").RefAttributes<RoadRef>>;
+export default Road;

package/dist/components/Road/toolbar.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 道路编辑工具栏组件
+ */
+import type { RoadEditToolbarProps } from '../../types';
+declare const RoadEditToolbar: ({ visible, selectedRoadId, currentMode, enabledButtons, pointCount, hintMessage, showHint, color, size, iconOnly, children, onEdit, onRedraw, onCreate, onCancel, onSave, onDelete, }: RoadEditToolbarProps) => import("react/jsx-runtime").JSX.Element;
+export default RoadEditToolbar;

package/dist/components/TianDiTuLayer/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 天地图图层组件
+ * @description 封装天地图的矢量图层和标注图层，支持多种图层风格和自定义瓦片URL
+ */
+import type { TianDiTuLayerProps } from '../../types';
+export declare const LAYER_TYPES: {
+    readonly VECTOR: "vector";
+    readonly SATELLITE: "satellite";
+    readonly TERRAIN: "terrain";
+};
+/**
+ * 天地图图层组件
+ */
+export declare function TianDiTuLayer({ apiKey, showAnnotation, layerType: layerTypeProp, tileUrl, annotationUrl, overlayUrl, subdomains, maxZoom, minZoom, attribution, theme: themeProp, showLayerSelector, onLayerTypeChange, }: TianDiTuLayerProps): JSX.Element;
+export default TianDiTuLayer;

package/dist/components/Track/ClusterView.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview 聚合模式渲染子组件
+ * @module components/Track/ClusterView
+ */
+import React from 'react';
+import L from 'leaflet';
+import Supercluster from 'supercluster';
+import type { ClusterIconConfig } from '../../types';
+import type { MiniMapProps } from '../../types';
+interface ClusterViewProps {
+    clusterResults: Supercluster.ClusterFeature<any>[];
+    markerIcon: L.DivIcon;
+    showTooltip: boolean;
+    clusterIconConfig?: ClusterIconConfig;
+    miniMapConfig: MiniMapProps | null;
+    onClusterClick: (feature: Supercluster.ClusterFeature<Supercluster.AnyProps>) => void;
+    onMarkerClick: (trackKey: string) => void;
+}
+declare const _default: React.NamedExoticComponent<ClusterViewProps>;
+export default _default;

package/dist/components/Track/TrackView.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview 轨迹模式渲染子组件
+ * @module components/Track/TrackView
+ */
+import React from 'react';
+import type { MiniMapProps } from '../../types';
+interface TrackViewProps {
+    sortedVisibleTracks: any[];
+    simplifiedTrackMap: Map<string, Record<string, [number, number][]>> | null;
+    hoveredTrack: string | null;
+    miniMapConfig: MiniMapProps | null;
+    checkIsSelected: (key: string) => boolean;
+    isTrackVisible: (key: string) => boolean;
+    getStyles: (state: number, isSelected: boolean, isHovered: boolean) => any;
+    handleTrackClick: (trackKey: string) => void;
+    handleTrackHover: (trackKey: string, isHovered: boolean) => void;
+    renderStartEndMarkers: (trackKey: string, points: Array<{
+        position: [number, number];
+        state: number;
+    }>) => React.ReactNode | null;
+    polylineRefs: React.MutableRefObject<Map<string, any>>;
+}
+declare const _default: React.NamedExoticComponent<TrackViewProps>;
+export default _default;

package/dist/components/Track/commands.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Track 组件命令式方法（useImperativeHandle）的纯工具逻辑
+ * @module components/Track/commands
+ */
+import L from 'leaflet';
+import type { FilterResult } from './types';
+/**
+ * 根据 filter 字符串筛选轨迹
+ * 支持 imei、date、imei|date 格式
+ */
+export declare function filterTracksByString<T extends {
+    key: string;
+    imei: string;
+    date: string;
+}>(tracks: T[], filter?: string): T[];
+/**
+ * 从轨迹列表计算统计信息
+ */
+export declare function computeTrackStats<T extends {
+    key: string;
+    imei: string;
+    date: string;
+    allPoints?: any[];
+    bounds?: any;
+}>(tracks: T[]): {
+    imeis: string[];
+    dates: string[];
+    totalPoints: number;
+    totalTracks: number;
+    bounds: [number, number, number, number] | null;
+};
+/**
+ * 从轨迹列表中提取 bounds 并安全构建 latLngBounds
+ */
+export declare function safeLatLngBounds(tracks: Array<{
+    bounds?: any;
+}>): L.LatLngBounds | null;
+/**
+ * 飞行到指定 bounds（带动画时长计算）
+ */
+export declare function flyToBounds(map: L.Map, bounds: L.LatLngBounds, options?: {
+    padding?: [number, number];
+}): void;
+/**
+ * 构建 filter 方法的返回结果
+ */
+export declare function buildFilterResult<T extends {
+    key: string;
+    imei: string;
+    date: string;
+    allPoints?: any[];
+    bounds?: any;
+}>(filteredTracks: T[]): FilterResult;

package/dist/components/Track/constants.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Track 组件内部常量和工具函数
+ * @module components/Track/constants
+ */
+import type { BBox } from '../../utils/spatialIndex';
+import type { TrackMeta } from './types';
+/**
+ * 默认的轨迹样式配置
+ */
+export declare const DEFAULT_STYLES: {
+    working: {
+        color: string;
+        weight: number;
+        opacity: number;
+    };
+    nonWorking: {
+        color: string;
+        weight: number;
+        opacity: number;
+        dashArray: string;
+    };
+    selected: {
+        weight: number;
+        opacity: number;
+    };
+    hover: {
+        weight: number;
+        opacity: number;
+    };
+};
+/** 从 [[number, number], [number, number]] 转换为 [minLat, minLng, maxLat, maxLng] */
+export declare function toBBox(bounds: [[number, number], [number, number]]): BBox;
+/** 比较两个 TrackMeta Map 是否相等 */
+export declare function areMapsEqual(a: Map<string, TrackMeta>, b: Map<string, TrackMeta>): boolean;

package/dist/components/Track/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Track 农机轨迹组件
+ * @description 用于在地图上显示农机作业轨迹，支持轨迹绘制、状态分段、轨迹动画、虚拟化渲染等功能
+ * @module components/Track
+ *
+ * ## 核心架构
+ *
+ * 本组件采用 **双模式渲染** 架构：
+ * - **Marker 模式** (`displayMode === 'marker'`): 小缩放级别下，将每条轨迹显示为一个 Marker 点
+ *   支持聚合（supercluster）以提升大量轨迹时的渲染性能和视觉可读性
+ * - **Track 模式** (`displayMode === 'track'`): 大缩放级别下，绘制完整的轨迹折线，支持状态分段着色
+ *
+ * 模式切换由 `currentZoom` 和 `markerZoomThreshold` 共同决定：
+ *   currentZoom <= markerZoomThreshold → Marker 模式
+ *   currentZoom >  markerZoomThreshold → Track 模式
+ *
+ * ## 数据流
+ *
+ * 1. `dataSource` → `parsedTracks` (解析原始数据，提取 imei/date/bounds/allPoints)
+ * 2. `parsedTracks` → `trackMetaMap` (计算每条轨迹的元数据：中心点、边界)
+ * 3. `trackMetaMap` → `spatialIndexRef` (构建空间索引，用于视口裁剪)
+ * 4. `parsedTracks` + `trackMetaMap` → `visibleTracksInView` (视口裁剪 + 虚拟化过滤)
+ * 5. `visibleTracksInView` → `sortedVisibleTracks` (选中轨迹优先排序)
+ * 6. `sortedVisibleTracks` → `TrackView` (渲染轨迹折线)
+ *
+ * ## 受控 / 非受控模式
+ *
+ * - 受控模式: `value !== undefined` 时，选中值完全由外部控制，内部通过 `onChange` 通知变更
+ * - 非受控模式: `value === undefined` 时，使用 `internalValue` 管理内部状态，支持 `defaultValue`
+ * - `mode === 'single'`: value 为 string，点击切换选中/取消
+ * - `mode === 'multiple'`: value 为 string[]，点击追加/移除
+ *
+ * ## 性能优化
+ *
+ * - **虚拟化渲染**: 仅渲染视口范围内的轨迹 (GridSpatialIndex 空间查询)
+ * - **轨迹简化**: Douglas-Peucker 算法减少折线点数
+ * - **冗余点过滤**: 移除距离过近的重复坐标点
+ * - **聚合模式**: 小缩放级别下将相近轨迹聚合为气泡显示
+ */
+import type { TrackProps, TrackRef } from '../../types';
+/**
+ * 农机轨迹组件
+ * @description 用于在地图上显示农机作业轨迹，支持：
+ * - 轨迹分段显示（路上/作业中不同颜色）
+ * - 轨迹选中高亮
+ * - 轨迹动画播放
+ * - 虚拟化渲染（视口裁剪）
+ * - 双模式显示：Marker 模式（小缩放级别）和轨迹模式（大缩放级别）
+ * - 聚合气泡（supercluster）
+ * - 小地图（鹰眼图）
+ * - 命令式 API（通过 ref 调用 fitBounds / flyToTrack / query 等方法）
+ */
+declare const Track: import("react").ForwardRefExoticComponent<TrackProps & import("react").RefAttributes<TrackRef>>;
+export default Track;

package/dist/components/Track/parseConfig.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Track 组件配置解析
+ * @description 将 boolean | ObjectConfig 三态配置解析为统一的配置对象
+ * @module components/Track/parseConfig
+ */
+import type { PerformanceConfig, MarkerModeConfig, ClusterIconConfig, MarkerIconConfig } from '../../types';
+export interface ParsedPerformanceConfig {
+    isVirtualized: boolean;
+    virtualMinZoom: number;
+    virtualMaxZoom: number;
+    simplifyTolerance: number;
+    duplicateTolerance: number;
+}
+export interface ParsedMarkerModeConfig {
+    markerZoomThreshold: number;
+    markerZoomToLevel: number;
+    enableCluster: boolean;
+    clusterOptions: {
+        radius?: number;
+        maxZoom?: number;
+        minPoints?: number;
+        icon?: ClusterIconConfig;
+    } | undefined;
+    clusterIconConfig: ClusterIconConfig | undefined;
+    markerIconConfig: MarkerIconConfig | undefined;
+}
+/**
+ * 解析 performance 配置
+ * - undefined / false → 关闭所有优化
+ * - true → 启用虚拟化（默认参数）
+ * - object → 自定义参数
+ */
+export declare function parsePerformanceConfig(performanceConfig: boolean | PerformanceConfig | undefined): ParsedPerformanceConfig;
+/**
+ * 解析 markerMode 配置
+ * - undefined / false → 关闭 Marker 模式
+ * - true → 启用 Marker 模式 + 聚合
+ * - object → 自定义参数
+ */
+export declare function parseMarkerModeConfig(markerModeConfig: boolean | MarkerModeConfig | undefined): ParsedMarkerModeConfig;

package/dist/components/Track/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Track 组件内部类型定义
+ * @module components/Track/types
+ */
+import type { BoundedItem } from '../../utils/spatialIndex';
+/** 轨迹元数据，用于 Marker 模式和空间索引 */
+export interface TrackMeta {
+    key: string;
+    imei: string;
+    date: string;
+    center: [number, number];
+    bounds: [[number, number], [number, number]];
+}
+/** 带边界框的轨迹索引项 */
+export interface BoundedTrackItem extends BoundedItem {
+    key: string;
+}
+/** 轨迹点的自定义属性 */
+export interface TrackPointProperties {
+    key: string;
+    imei: string;
+    date: string;
+}
+/** 筛选结果类型 */
+export interface FilterResult {
+    tracks: Array<{
+        key: string;
+        imei: string;
+        date: string;
+        bounds: any;
+        pointCount: number;
+    }>;
+    imeis: string[];
+    dates: string[];
+    totalTracks: number;
+    totalPoints: number;
+    bounds: [number, number, number, number] | null;
+}

package/dist/components/Track/useMarkerIcon.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Marker 图标创建 hook
+ * @module components/Track/useMarkerIcon
+ */
+import L from 'leaflet';
+import type { MarkerIconConfig } from '../../types';
+/**
+ * 根据 MarkerIconConfig 创建 Leaflet DivIcon
+ */
+export declare function createMarkerIcon(config?: MarkerIconConfig): L.DivIcon;
+/**
+ * 自定义 hook：缓存 markerIcon 的创建结果
+ */
+export declare function useMarkerIcon(config?: MarkerIconConfig): L.DivIcon;

package/dist/components/Track/useTrackCommands.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Track 组件命令式方法 hook
+ * @description 将 useImperativeHandle 中的方法逻辑提取为独立 hook，便于维护
+ * @module components/Track/useTrackCommands
+ */
+import { type MutableRefObject } from 'react';
+import type L from 'leaflet';
+import type { TrackRef } from '../../types';
+import type { FilterResult } from './types';
+interface UseTrackCommandsOptions {
+    map: L.Map | null;
+    parsedTracks: any[];
+    isControlled: boolean;
+    mode: 'single' | 'multiple';
+    currentValue: string | string[];
+    onChange?: (value: string | string[]) => void;
+    onClickRef: MutableRefObject<((key: string, track: any) => void) | undefined>;
+    setInternalValue: (value: string | string[]) => void;
+    visibleTracksRef: MutableRefObject<Set<string>>;
+    setVisibleTracksVersion: React.Dispatch<React.SetStateAction<number>>;
+}
+export interface TrackCommands {
+    /** 查询匹配的轨迹（纯查询，不修改任何状态） */
+    query: (filter?: string, callback?: (result: FilterResult) => void) => void;
+    /** 获取当前可见轨迹的 key 数组 */
+    getVisibleTracks: () => string[];
+    /** 获取当前选中轨迹的 key 数组 */
+    getSelectedTracks: () => string[];
+    /** 即时跳转视图到指定轨迹范围（无动画） */
+    fitBounds: (filter?: string, callback?: () => void) => void;
+    /** 带动画飞行到指定轨迹范围（callback 在飞行动画结束后触发） */
+    flyTo: (filter?: string, callback?: () => void) => void;
+    /** 设置可见轨迹（仅显示匹配的轨迹，隐藏其它） */
+    setVisibleTracks: (filter?: string) => void;
+    /** 恢复所有轨迹可见（清除可见性筛选，不影响选中状态） */
+    clearVisibleFilter: () => void;
+    /** 选中匹配的轨迹（修改 value + 触发 onClick，不移动地图） */
+    select: (filter?: string, callback?: () => void) => void;
+    /** 清除选中状态（不影响可见性筛选） */
+    deselect: () => void;
+    /** 全量重置（清除选中 + 恢复所有轨迹可见） */
+    reset: (callback?: () => void) => void;
+    /**
+     * @deprecated 请使用 query + setVisibleTracks 替代
+     */
+    filter: (filter?: string, callback?: (result: FilterResult) => void) => void;
+    /**
+     * @deprecated 请使用 select + flyTo + setVisibleTracks 组合替代
+     */
+    flyToTrack: (filter?: string, filterVisible?: boolean, onComplete?: () => void) => void;
+}
+/**
+ * Track 组件命令式方法 hook
+ */
+export declare function useTrackCommands(ref: React.Ref<TrackRef>, options: UseTrackCommandsOptions): void;
+export {};

package/dist/components/shared/BaseEditToolbar.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 通用编辑工具栏组件
+ * @description 用于统一各编辑组件的工具栏实现
+ */
+import type { ReactNode } from 'react';
+/** 按钮样式变体 */
+export type ButtonVariant = 'default' | 'primary' | 'danger';
+/** 预设色板（参照 Ant Design 5.x PresetColors） */
+export type ToolbarPresetColors = 'success' | 'warning' | 'error' | 'magenta' | 'volcano' | 'gold' | 'orange' | 'cyan' | 'geekblue' | 'purple';
+/** 按钮 color 属性类型（支持预设色和自定义颜色如 #ff0000、rgba(255,0,0,0.5)） */
+export type ToolbarColor = 'default' | 'primary' | 'danger' | ToolbarPresetColors | string;
+/** 预设颜色集合（用于区分预设色和自定义颜色） */
+export declare const PRESET_COLOR_SET: Set<string>;
+/** 单个按钮配置 */
+export interface ToolbarButton<T extends string> {
+    /** 按钮操作类型 */
+    action: T;
+    /** 显示文本 */
+    label: string;
+    /** 图标组件 */
+    icon?: ReactNode;
+    /** 提示文本 */
+    tooltip?: string;
+    /** 按钮样式变体（兼容，优先使用 color） */
+    variant?: ButtonVariant;
+    /** 按钮颜色 */
+    color?: ToolbarColor;
+    /** 是否需要选中项才能点击 */
+    needsSelection?: boolean;
+    /** 编辑模式下是否显示 */
+    showInEdit?: boolean;
+    /** 是否禁用 */
+    disabled?: boolean;
+}
+/** 工具栏尺寸（支持预设尺寸和自定义数字，单位 px） */
+export type ToolbarSize = 'large' | 'middle' | 'small' | number;
+/** 工具栏属性 */
+export interface BaseEditToolbarProps<T extends string> {
+    /** 是否可见 */
+    visible: boolean;
+    /** 工具栏尺寸 */
+    size?: ToolbarSize;
+    /** 当前选中ID */
+    selectedId: string | number | null;
+    /** 当前模式 */
+    currentMode: string;
+    /** 启用的按钮 */
+    enabledButtons: T[];
+    /** 按钮配置 */
+    buttons: ToolbarButton<T>[];
+    /** 编辑模式判断函数（默认 mode !== 'idle'） */
+    isEditingFn?: (mode: string) => boolean;
+    /** 模式提示信息 */
+    modeHints?: Record<string, string>;
+    /** 类名前缀 */
+    classPrefix: string;
+    /** 保存按钮是否禁用 */
+    saveDisabled?: boolean;
+    /** 是否显示编辑模式提示 */
+    showHint?: boolean;
+    /** 警告提示信息（不受 showHint 控制，始终显示） */
+    warningHint?: string;
+    /** 内置按钮的统一颜色（覆盖各按钮自身的 variant/color），支持预设色和自定义颜色 */
+    color?: ToolbarColor;
+    /** 是否仅显示图标（不显示文字） */
+    iconOnly?: boolean;
+    /** 额外内容（自定义工具栏按钮） */
+    children?: ReactNode;
+    /** 标准动作：取消 */
+    onCancel?: () => void;
+    /** 标准动作：保存（自动传入 selectedId） */
+    onSave?: (id?: string | number | null) => void;
+    /** 标准动作：新建 */
+    onCreate?: () => void;
+    /** 标准动作：删除（自动传入 selectedId） */
+    onDelete?: (id?: string | number | null) => void;
+    /** 自定义动作映射表，key 为 action 名称，value 为回调（自动传入 selectedId） */
+    actionHandlers?: Partial<Record<T, (id?: string | number | null) => void>>;
+}
+/** 工具栏上下文 */
+export interface ToolbarContextValue {
+    /** 类名前缀 */
+    classPrefix: string;
+}
+/** 工具栏上下文 */
+export declare const ToolbarContext: import("react").Context<ToolbarContextValue | null>;
+/**
+ * 获取工具栏上下文
+ */
+export declare function useToolbarContext(): ToolbarContextValue;
+/** 工具栏 ref 方法 */
+export interface BaseEditToolbarRef {
+    showNotification: (message: string, title?: string) => void;
+    clearNotification: () => void;
+}
+/**
+ * 通用编辑工具栏
+ */
+declare const BaseEditToolbar: import("react").ForwardRefExoticComponent<BaseEditToolbarProps<string> & import("react").RefAttributes<BaseEditToolbarRef>>;
+export default BaseEditToolbar;