react-av-timeline 2.0.0 → 3.0.1

package/dist/waterfall.d.ts

@@ -0,0 +1,137 @@
+import { CSSProperties, ReactNode } from 'react';
+export interface TimelineClip {
+    /** 唯一 id */
+    id: string;
+    /** 行标签与搜索文案，缺省用 id */
+    name?: string;
+    /** 轨道号，相同 index 即同一轨 */
+    index: number;
+    /** 开始时间 */
+    start: number;
+    /** 时长，唯一结束依据 */
+    duration: number;
+    /** 条形内自定义内容，缺省用 name */
+    label?: ReactNode;
+    /** 条形颜色，缺省按轨道取 --wf-clip-N */
+    color?: string;
+    /** 条形自定义样式 */
+    style?: CSSProperties;
+    /** 原始数据，详情中展示 */
+    meta?: Record<string, unknown>;
+}
+export interface TimelineTrack {
+    /** 轨道号 */
+    index: number;
+    /** 轨道名 */
+    name?: string;
+}
+export type TimeFormat = {
+    type: 'number';
+} | {
+    type: 'clock';
+    millisecond?: boolean;
+    offset?: number;
+} | {
+    type: 'smpte';
+    fps: number;
+    offset?: number;
+};
+export interface TimelineRange {
+    start: number;
+    end: number;
+    duration: number;
+}
+export interface TimelineRow {
+    id: string;
+    index: number;
+    trackName: string;
+    label: string;
+    start: number;
+    end: number;
+    clips: TimelineClip[];
+}
+export interface TimelineLabels {
+    search: string;
+    noMatch: (query: string) => string;
+    empty: string;
+    current: string;
+    total: string;
+    track: string;
+    start: string;
+    end: string;
+    duration: string;
+    close: string;
+    zoom: string;
+    lanesColumn: string;
+    sequenceColumn: string;
+}
+export interface TraceWaterfallProps {
+    /** 数据 */
+    clips: TimelineClip[];
+    tracks?: TimelineTrack[];
+    /** 行布局，默认 lanes；followMode 非 off 时强制 sequence */
+    layout?: 'lanes' | 'sequence';
+    /** 时间单位，默认 s */
+    unit?: 'ms' | 's';
+    viewStart?: number;
+    viewDuration?: number;
+    currentTime?: number;
+    onCurrentTimeChange?: (time: number) => void;
+    formatTime?: TimeFormat | ((value: number) => string);
+    formatDuration?: (value: number) => string;
+    /** 视口 */
+    fixedPlayhead?: boolean;
+    playheadPosition?: number;
+    followMode?: 'off' | 'scroll' | 'hide';
+    zoom?: number;
+    defaultZoom?: number;
+    onZoomChange?: (zoom: number) => void;
+    /** 外观 */
+    labelWidth?: number;
+    height?: CSSProperties['height'];
+    minTickGap?: number;
+    showTime?: boolean;
+    showDetail?: boolean;
+    showSearch?: boolean;
+    showZoom?: boolean;
+    emptyText?: string;
+    labels?: Partial<TimelineLabels>;
+    onClipClick?: (clip: TimelineClip) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+export declare const DEFAULT_TIME_FORMAT: TimeFormat;
+export declare const ZOOM_LEVELS: number[];
+export declare const DEFAULT_LABELS: TimelineLabels;
+/** 片段结束时间；负时长按 0 处理 */
+export declare function getClipEnd(clip: TimelineClip): number;
+/** 计算视图范围；空数据时回退到 0 */
+export declare function resolveRange(clips: TimelineClip[], viewStart?: number, viewDuration?: number): TimelineRange;
+/** 把时间钳制到视图范围 */
+export declare function clampTime(time: number, range: TimelineRange): number;
+/** 返回该时刻所有活跃片段（闭区间），保持声明顺序 */
+export declare function getActiveAt(clips: TimelineClip[], time: number, range?: TimelineRange): TimelineClip[];
+/**
+ * 返回每轨最上层的活跃片段，按轨道号升序。
+ * 同轨重叠时取声明顺序中的最后一个。
+ */
+export declare function getTopActiveAt(clips: TimelineClip[], time: number, range?: TimelineRange): TimelineClip[];
+/** 搜索匹配 name 与 id，大小写不敏感 */
+export declare function matchClip(clip: TimelineClip, query: string): boolean;
+/** 构建行：lanes 按轨道，sequence 按 start 平铺 */
+export declare function buildRows(clips: TimelineClip[], tracks: TimelineTrack[] | undefined, layout: 'lanes' | 'sequence', labels: Pick<TimelineLabels, 'track'>): TimelineRow[];
+/** 从 1 / 2 / 5 / 10 × 10^n 中选出不小于 min 的最小步长 */
+export declare function niceStep(min: number): number;
+/** 生成整数刻度；最多 500 个 */
+export declare function buildTicks(range: TimelineRange, pxPerUnit: number, minGap?: number): {
+    step: number;
+    ticks: Array<{
+        value: number;
+        x: number;
+    }>;
+    firstOffset: number;
+};
+/** 绝对时间格式化，会应用 offset */
+export declare function formatTime(value: number, format?: TimeFormat | ((value: number) => string), unit?: 'ms' | 's'): string;
+/** 时长格式化，不应用 offset */
+export declare function formatDuration(value: number, format?: TimeFormat | ((value: number) => string), unit?: 'ms' | 's'): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-av-timeline",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "author": "ArSrNa",
   "repository": {
     "type": "git",
@@ -43,7 +43,7 @@
   "bugs": {
     "url": "https://cnb.cool/arsrna/os/react-timeline/-/issues"
   },
-  "description": "React 音视频时间线组件",
+  "description": "React 音视频时间线组件，含导播瀑布时间线",
   "files": [
     "dist",
     "image"
@@ -53,11 +53,12 @@
     "slider",
     "react",
     "timeline",
+    "waterfall",
     "audio",
     "video",
     "visualize"
   ],
-  "license": "GNU",
+  "license": "MIT",
   "scripts": {
     "build": "vite build",
     "dev": "vite",