@wenle_2523097/agri-map 2.0.7 → 2.0.8

package/README.md

@@ -4,6 +4,13 @@
 
 ## 更新日志
 
+### v2.0.8 (2026-06-01)
+#### 新增
+- **TrackPlayer 时间轴功能**：新增 `onTimelineUpdate` 回调，暴露完整时间轴数据
+- **useTimeline Hook**：提供时间轴数据计算逻辑（progress、时间戳、格式化时间等）
+- **时间轴 UI 交互**：Demo 支持滑块拖动跳转、实时进度显示、时间戳标签
+- **TimelineProgressInfo 类型**：完整的时间轴进度信息接口定义
+
 ### v2.0.7 (2026-05-27)
 #### 新增
 - **Panel 面板组件**：新增地图面板组件，支持在地图上渲染 React 内容
@@ -52,11 +59,6 @@ yarn add @wenle_2523097/agri-map
 ```bash
 npm install leaflet@^1.9.4 react@>=18.0.0 react-dom@>=18.0.0
 ```
-
-> ⚠️ **重要提示：**
->
-> - 本库已移除 `react-leaflet` 依赖，直接使用原生 Leaflet API，更轻量、更灵活
-
 ---
 
 ## 快速开始

package/dist/components/TrackPlayer/__tests__/index.test.d.ts

@@ -1,5 +1,5 @@
 /**
- * TrackPlayer 组件单元测试
+ * @fileoverview TrackPlayer 组件单元测试
  * @description 测试轨迹播放组件的渲染、播放控制和状态管理
  */
 export {};

package/dist/components/TrackPlayer/__tests__/useTimeline.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview useTimeline hook 单元测试
+ * @module components/TrackPlayer/__tests__/useTimeline.test
+ */
+export {};

package/dist/components/TrackPlayer/hooks/useTimeline.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview TrackPlayer 时间轴数据计算 Hook
+ * @module components/TrackPlayer/hooks/useTimeline
+ */
+import type { TrackPointWithState } from '../types';
+/** 时间轴信息 */
+export interface TimelineInfo {
+    /** 起始时间戳 */
+    startTime: number | null;
+    /** 结束时间戳 */
+    endTime: number | null;
+    /** 当前时间戳 */
+    currentTime: number | null;
+    /** 进度百分比 0-1 */
+    progress: number;
+    /** 格式化起始时间 */
+    startTimeStr: string | null;
+    /** 格式化结束时间 */
+    endTimeStr: string | null;
+    /** 格式化当前时间 */
+    currentTimeStr: string | null;
+}
+interface UseTimelineOptions {
+    allPoints: TrackPointWithState[];
+    currentIndex: number;
+}
+/**
+ * 格式化时间戳为 HH:MM:SS 字符串
+ * @param timestamp 时间戳（毫秒），可为 null
+ */
+export declare function formatTimestamp(timestamp: number | null): string | null;
+/**
+ * 计算进度对应的索引
+ * @param allPointsLength 轨迹点总数
+ * @param progress 进度 0-1
+ * @returns 对应的索引
+ */
+export declare function indexFromProgress(allPointsLength: number, progress: number): number;
+/**
+ * 计算时间轴数据
+ * @param allPoints 轨迹点数组
+ * @param currentIndex 当前索引
+ * @returns 时间轴信息
+ */
+export declare function useTimeline({ allPoints, currentIndex }: UseTimelineOptions): TimelineInfo;
+/**
+ * 计算进度信息（用于 onProgress 回调兼容）
+ */
+export declare function calcProgressInfo(allPoints: TrackPointWithState[], currentIndex: number, _distance: number): {
+    progress: number;
+    startTime: number | null;
+    endTime: number | null;
+    currentTime: number | null;
+    startTimeStr: string | null;
+    endTimeStr: string | null;
+    currentTimeStr: string | null;
+};
+export {};

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

@@ -52,6 +52,19 @@ export interface TrackPlayerProps {
     onStop?: () => void;
     onProgress?: (currentIndex: number, total: number, point: TrackPoint | null, distance: number, timestamp: number | null, time: string | null) => void;
     onComplete?: () => void;
+    /** 时间轴进度详细回调（提供完整时间轴数据） */
+    onTimelineUpdate?: (info: {
+        currentIndex: number;
+        totalPoints: number;
+        progress: number;
+        startTime: number | null;
+        endTime: number | null;
+        currentTime: number | null;
+        startTimeStr: string | null;
+        endTimeStr: string | null;
+        currentTimeStr: string | null;
+        distance: number;
+    }) => void;
 }
 declare const TrackPlayer: import("react").ForwardRefExoticComponent<TrackPlayerProps & import("react").RefAttributes<TrackPlayerHandle>>;
 export default TrackPlayer;

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

@@ -2,7 +2,7 @@
  * @fileoverview TrackPlayer 类型定义
  * @module components/TrackPlayer/types
  */
-import type { TrackData, TrackPoint, IconConfig } from '../../types';
+import type { TrackData, TrackPoint, IconConfig, PathOptions } from '../../types';
 export type PlayStatus = 'idle' | 'playing' | 'paused' | 'stopped';
 /** 轨迹播放控制方法 */
 export interface TrackPlayerHandle {
@@ -32,6 +32,10 @@ export interface TrackPlayerProps {
     trailLength?: number;
     /** 显示轨迹线（完整路径） */
     showTrack?: boolean;
+    /** 播放前轨迹样式（未走过的路径），默认 TRACKPLAYER_STYLE.default */
+    path?: PathOptions | null | false;
+    /** 播放后轨迹样式（已走过的路径），默认 TRACKPLAYER_STYLE.played */
+    playPath?: PathOptions | null | false;
     /** 当前时刻图标配置，默认使用 TRACKPLAYER_DEFAULT_ICON */
     icon?: IconConfig | null | false;
     /** 图标默认朝向角度（度），默认 -90 */
@@ -44,6 +48,31 @@ export interface TrackPlayerProps {
     onStop?: () => void;
     onProgress?: (currentIndex: number, total: number, point: TrackPoint | null, distance: number, timestamp: number | null, time: string | null) => void;
     onComplete?: () => void;
+    /** 时间轴进度详细回调（提供完整时间轴数据） */
+    onTimelineUpdate?: (info: TimelineProgressInfo) => void;
+}
+/** 时间轴进度信息 */
+export interface TimelineProgressInfo {
+    /** 当前索引 */
+    currentIndex: number;
+    /** 总点数 */
+    totalPoints: number;
+    /** 进度百分比 0-1 */
+    progress: number;
+    /** 起始时间戳 */
+    startTime: number | null;
+    /** 结束时间戳 */
+    endTime: number | null;
+    /** 当前时间戳 */
+    currentTime: number | null;
+    /** 格式化起始时间 */
+    startTimeStr: string | null;
+    /** 格式化结束时间 */
+    endTimeStr: string | null;
+    /** 格式化当前时间 */
+    currentTimeStr: string | null;
+    /** 已行进距离（米） */
+    distance: number;
 }
 /** 内部使用的轨迹点（含 state） */
 export interface TrackPointWithState extends TrackPoint {

package/dist/index.esm.js

@@ -25601,7 +25601,8 @@ var TrackPlayer = /*#__PURE__*/forwardRef(function (_ref, ref) {
     onPause = _ref.onPause,
     onStop = _ref.onStop,
     onProgress = _ref.onProgress,
-    onComplete = _ref.onComplete;
+    onComplete = _ref.onComplete,
+    onTimelineUpdate = _ref.onTimelineUpdate;
   var map = useMap();
   // ==================== 字段名合并 ====================
   var mergedFieldNames = useMemo(function () {
@@ -25736,7 +25737,31 @@ var TrackPlayer = /*#__PURE__*/forwardRef(function (_ref, ref) {
     var timestamp = currentPoint[2];
     var formattedTime = timestamp !== null ? formatTime(timestamp) : null;
     onProgress === null || onProgress === void 0 || onProgress(currentIndex, totalPoints, currentPoint, distance, timestamp, formattedTime);
-  }, [map, currentIndex, allPoints, createMarkerIcon, onProgress, totalPoints]);
+    // 时间轴进度详细回调
+    if (onTimelineUpdate) {
+      var _allPoints$, _allPoints$at;
+      var startTime = (_allPoints$ = allPoints[0]) === null || _allPoints$ === void 0 ? void 0 : _allPoints$[2];
+      var endTime = (_allPoints$at = allPoints.at(-1)) === null || _allPoints$at === void 0 ? void 0 : _allPoints$at[2];
+      var progress = totalPoints > 1 ? currentIndex / (totalPoints - 1) : 0;
+      var formatTimeStr = function formatTimeStr(ts) {
+        if (ts === null) return null;
+        var d = new Date(ts);
+        return "".concat(String(d.getHours()).padStart(2, '0'), ":").concat(String(d.getMinutes()).padStart(2, '0'), ":").concat(String(d.getSeconds()).padStart(2, '0'));
+      };
+      onTimelineUpdate({
+        currentIndex: currentIndex,
+        totalPoints: totalPoints,
+        progress: progress,
+        startTime: startTime,
+        endTime: endTime,
+        currentTime: timestamp,
+        startTimeStr: formatTimeStr(startTime),
+        endTimeStr: formatTimeStr(endTime),
+        currentTimeStr: formattedTime,
+        distance: distance
+      });
+    }
+  }, [map, currentIndex, allPoints, createMarkerIcon, onProgress, onTimelineUpdate, totalPoints]);
   // 轨迹线（已走过部分用 playPath，未走到部分用 path）
   useEffect(function () {
     if (!map || !showTrack || allPoints.length === 0) return;