@huyooo/file-explorer-frontend-react 0.4.2

package/dist/index.d.ts

@@ -0,0 +1,562 @@
+import * as react from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * 文件类型（使用 const object 而非 enum，更好的 tree-shaking）
+ */
+declare const FileType: {
+    readonly FOLDER: "folder";
+    readonly FILE: "file";
+    readonly IMAGE: "image";
+    readonly VIDEO: "video";
+    readonly MUSIC: "music";
+    readonly DOCUMENT: "document";
+    readonly CODE: "code";
+    readonly TEXT: "text";
+    readonly PDF: "pdf";
+    readonly ARCHIVE: "archive";
+    readonly APPLICATION: "application";
+    readonly UNKNOWN: "unknown";
+};
+type FileType = typeof FileType[keyof typeof FileType];
+/**
+ * 文件系统项
+ */
+interface FileItem {
+    /** 唯一标识（通常是完整路径） */
+    id: string;
+    name: string;
+    type: FileType;
+    size?: string;
+    dateModified?: string;
+    url?: string;
+    thumbnailUrl?: string;
+    children?: FileItem[];
+}
+/**
+ * 视图模式
+ */
+type ViewMode = 'grid' | 'list' | 'columns';
+/**
+ * 排序配置
+ */
+interface SortConfig {
+    field: 'name' | 'dateModified' | 'size' | 'type';
+    direction: 'asc' | 'desc';
+}
+/**
+ * 侧边栏项目
+ */
+interface SidebarItem {
+    id: string;
+    label: string;
+    icon?: string;
+    path?: string;
+    children?: SidebarItem[];
+}
+/**
+ * 面包屑项
+ */
+interface BreadcrumbItem {
+    id: string;
+    name: string;
+}
+/**
+ * 操作结果
+ */
+interface OperationResult<T = void> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/** 压缩格式 */
+type CompressFormat = 'zip' | 'tar' | 'tgz' | 'tarbz2';
+/** 压缩级别 */
+type CompressLevel = 'fast' | 'normal' | 'best';
+/** 压缩选项 */
+interface CompressOptions {
+    format: CompressFormat;
+    level?: CompressLevel;
+    outputName: string;
+    outputDir: string;
+    deleteSource?: boolean;
+}
+/** 解压选项 */
+interface ExtractOptions {
+    targetDir: string;
+    deleteArchive?: boolean;
+}
+/** 压缩进度 */
+interface CompressProgress {
+    currentFile: string;
+    processedCount: number;
+    totalCount: number;
+    percent: number;
+}
+/** 压缩结果 */
+interface CompressResult {
+    success: boolean;
+    outputPath?: string;
+    error?: string;
+}
+/**
+ * 文件操作适配器接口
+ */
+interface FileExplorerAdapter {
+    /** 读取目录 */
+    readDirectory(dirPath: string): Promise<FileItem[]>;
+    /** 读取系统路径目录 */
+    readSystemPath(pathId: string): Promise<FileItem[]>;
+    /** 获取系统路径 */
+    getSystemPath(pathId: string): Promise<string | null>;
+    /** 读取文件内容 */
+    readFileContent(filePath: string): Promise<string>;
+    /** 写入文件内容 */
+    writeFileContent(filePath: string, content: string): Promise<OperationResult>;
+    /** 创建文件夹 */
+    createFolder(parentDir: string, folderName: string): Promise<OperationResult<{
+        finalPath: string;
+    }>>;
+    /** 创建文件 */
+    createFile(parentDir: string, fileName: string, content?: string): Promise<OperationResult<{
+        finalPath: string;
+    }>>;
+    /** 删除文件 */
+    deleteFiles(paths: string[]): Promise<OperationResult>;
+    /** 重命名文件 */
+    renameFile(oldPath: string, newPath: string): Promise<OperationResult>;
+    /** 复制文件 */
+    copyFiles(sourcePaths: string[], targetDir: string): Promise<OperationResult<{
+        copiedPaths: string[];
+    }>>;
+    /** 移动文件 */
+    moveFiles(sourcePaths: string[], targetDir: string): Promise<OperationResult<{
+        movedPaths: string[];
+    }>>;
+    /** 使用系统默认应用打开 */
+    openPath(filePath: string): Promise<OperationResult>;
+    /** 复制文件到剪贴板 */
+    copyFilesToClipboard(filePaths: string[]): Promise<OperationResult>;
+    /** 获取剪贴板文件 */
+    getClipboardFiles(): Promise<OperationResult<{
+        files: string[];
+    }>>;
+    /** 粘贴文件 */
+    pasteFiles(targetDir: string, sourcePaths: string[]): Promise<OperationResult<{
+        pastedPaths: string[];
+    }>>;
+    /** 流式搜索文件 */
+    searchFilesStream(searchPath: string, pattern: string, searchId: string): Promise<OperationResult>;
+    /** 监听搜索结果 */
+    onSearchResults(callback: (data: {
+        searchId: string;
+        items: FileItem[];
+        done: boolean;
+    }) => void): () => void;
+    /** 压缩文件 */
+    compressFiles(sources: string[], options: CompressOptions): Promise<CompressResult>;
+    /** 解压文件 */
+    extractArchive(archivePath: string, options: ExtractOptions): Promise<CompressResult>;
+    /** 判断是否为压缩文件 */
+    isArchiveFile(filePath: string): Promise<boolean>;
+    /** 监听压缩进度 */
+    onCompressProgress(callback: (data: CompressProgress) => void): () => void;
+    /** 监听解压进度 */
+    onExtractProgress(callback: (data: CompressProgress) => void): () => void;
+    /** 监听目录变化 */
+    watchDirectory(dirPath: string, watchId: string): Promise<OperationResult>;
+    /** 停止监听目录 */
+    unwatchDirectory(watchId: string): Promise<OperationResult>;
+    /** 监听文件变化事件 */
+    onWatchEvent(callback: (data: {
+        watchId: string;
+        event: WatchEvent;
+    }) => void): () => void;
+    /** 显示文件/文件夹的系统属性窗口 */
+    showFileInfo(filePath: string): Promise<OperationResult>;
+    /** 在终端中打开目录 */
+    openInTerminal(dirPath: string): Promise<OperationResult>;
+    /** 通过 Cursor 打开 */
+    openInEditor(targetPath: string): Promise<OperationResult>;
+    /** 在新窗口中打开文件夹（使用系统文件管理器） */
+    openInNewWindow(folderPath: string): Promise<OperationResult>;
+    /** 请求窗口聚焦（用于右键打开菜单前激活窗口） */
+    requestWindowFocus(): void;
+    /** 检测媒体文件是否需要转码 */
+    mediaNeedsTranscode?(filePath: string): Promise<OperationResult<TranscodeInfo>>;
+    /** 获取可播放的媒体 URL（自动转码） */
+    mediaGetPlayableUrl?(filePath: string): Promise<{
+        success: boolean;
+        url?: string;
+        error?: string;
+    }>;
+    /** 获取媒体元数据 */
+    mediaGetMetadata?(filePath: string): Promise<OperationResult<MediaMetadata>>;
+    /** 监听转码进度 */
+    onMediaTranscodeProgress?(callback: (data: {
+        filePath: string;
+        progress: MediaTranscodeProgress;
+    }) => void): () => void;
+    /** 清理指定文件的转码缓存 */
+    mediaCleanupFile?(filePath: string): Promise<OperationResult>;
+    /** 打开媒体预览窗口（原生窗口） */
+    openMediaPreviewWindow?(filePath: string, mediaType: 'image' | 'video' | 'audio'): Promise<OperationResult>;
+    /** 关闭媒体预览窗口 */
+    closeMediaPreviewWindow?(filePath: string): Promise<OperationResult>;
+}
+/** 文件变化事件类型 */
+type WatchEventType = 'add' | 'change' | 'remove' | 'rename';
+/** 文件变化事件 */
+interface WatchEvent {
+    type: WatchEventType;
+    path: string;
+    filename: string;
+}
+/** 媒体转码方式 */
+type TranscodeMethod = 'direct' | 'remux' | 'transcode';
+/** 媒体转码状态 */
+type TranscodeStatus = 'idle' | 'checking' | 'transcoding' | 'ready' | 'error';
+/** 媒体转码信息 */
+interface TranscodeInfo {
+    type: 'video' | 'audio';
+    needsTranscode: boolean;
+    method: TranscodeMethod;
+    estimatedTime?: number;
+    targetFormat?: string;
+}
+/** 媒体转码进度 */
+interface MediaTranscodeProgress {
+    percent: number;
+    time?: number;
+    duration?: number;
+    speed?: string;
+}
+/** 媒体元数据 */
+interface MediaMetadata {
+    filePath: string;
+    type: 'video' | 'audio';
+    duration: number;
+    title?: string;
+    artist?: string;
+    album?: string;
+}
+/**
+ * 右键菜单项
+ */
+interface ContextMenuItem {
+    id: string;
+    label: string;
+    icon?: string;
+    shortcut?: string;
+    disabled?: boolean;
+    separator?: boolean;
+    danger?: boolean;
+    checked?: boolean;
+    action?: () => void;
+    children?: ContextMenuItem[];
+}
+
+interface FileListViewProps {
+    items: FileItem[];
+    viewMode?: 'grid' | 'list';
+    loading?: boolean;
+    adapter?: FileExplorerAdapter;
+    currentPath?: string;
+    getAppIconUrl?: (item: FileItem) => string | undefined;
+    onOpen?: (item: FileItem) => void;
+    onSelectionChange?: (ids: Set<string>, items: FileItem[]) => void;
+    onContextMenu?: (event: React.MouseEvent, item: FileItem) => void;
+    onContextMenuEmpty?: (event: React.MouseEvent) => void;
+    onRename?: (item: FileItem, newName: string) => void;
+    onSortChange?: (config: SortConfig) => void;
+    onMove?: (sourceIds: string[], targetId: string) => void;
+}
+interface FileListViewHandle {
+    clearSelection: () => void;
+    startRename: (id: string) => void;
+    selectAll: () => void;
+    selectedIds: Set<string>;
+    selectedItems: FileItem[];
+}
+declare const FileListView: react.ForwardRefExoticComponent<FileListViewProps & react.RefAttributes<FileListViewHandle>>;
+
+interface SidebarSection {
+    id: string;
+    title: string;
+    items: SidebarItem[];
+}
+interface FileSidebarProps {
+    sections: SidebarSection[];
+    activeId?: string;
+    onNavigate?: (item: SidebarItem) => void;
+}
+declare function FileSidebar({ sections, activeId, onNavigate }: FileSidebarProps): react_jsx_runtime.JSX.Element;
+
+interface ToolbarProps {
+    canGoBack?: boolean;
+    canGoForward?: boolean;
+    breadcrumbs?: BreadcrumbItem[];
+    viewMode?: 'grid' | 'list';
+    searchQuery?: string;
+    showSearch?: boolean;
+    showViewToggle?: boolean;
+    draggable?: boolean;
+    onBack?: () => void;
+    onForward?: () => void;
+    onBreadcrumbNavigate?: (item: BreadcrumbItem) => void;
+    onViewModeChange?: (mode: 'grid' | 'list') => void;
+    onSearchQueryChange?: (query: string) => void;
+    children?: React.ReactNode;
+    breadcrumbSlot?: React.ReactNode;
+    actionsSlot?: React.ReactNode;
+}
+declare function Toolbar({ canGoBack, canGoForward, breadcrumbs, viewMode, searchQuery, showSearch, showViewToggle, draggable, onBack, onForward, onBreadcrumbNavigate, onViewModeChange, onSearchQueryChange, children, breadcrumbSlot, actionsSlot, }: ToolbarProps): react_jsx_runtime.JSX.Element;
+
+interface BreadcrumbProps {
+    items: BreadcrumbItem[];
+    onNavigate?: (item: BreadcrumbItem, index: number) => void;
+}
+declare function Breadcrumb({ items, onNavigate }: BreadcrumbProps): react_jsx_runtime.JSX.Element;
+
+interface StatusBarProps {
+    itemCount?: number;
+    selectedCount?: number;
+    children?: React.ReactNode;
+}
+declare function StatusBar({ itemCount, selectedCount, children }: StatusBarProps): react_jsx_runtime.JSX.Element;
+
+interface FileIconProps {
+    type: FileType;
+    name?: string;
+    className?: string;
+    size?: number;
+}
+declare function FileIcon({ type, name, className, size }: FileIconProps): react_jsx_runtime.JSX.Element;
+
+interface FileGridProps {
+    items: FileItem[];
+    selectedIds: Set<string>;
+    editingId?: string | null;
+    dragOverId?: string | null;
+    getAppIconUrl?: (item: FileItem) => string | undefined;
+    onSelect?: (item: FileItem, e: React.MouseEvent) => void;
+    onOpen?: (item: FileItem) => void;
+    onContextMenu?: (item: FileItem, e: React.MouseEvent) => void;
+    onContextMenuEmpty?: (e: React.MouseEvent) => void;
+    onNameClick?: (item: FileItem, e: React.MouseEvent) => void;
+    onRename?: (item: FileItem, newName: string) => void;
+    onRenameCancel?: (item: FileItem) => void;
+    onDragStart?: (e: React.DragEvent, item: FileItem) => void;
+    onDragOver?: (e: React.DragEvent, item: FileItem) => void;
+    onDragLeave?: (e: React.DragEvent) => void;
+    onDrop?: (e: React.DragEvent, item: FileItem) => void;
+    onThumbnailError?: (item: FileItem, e: React.SyntheticEvent<HTMLImageElement, Event>) => void;
+}
+declare function FileGrid({ items, selectedIds, editingId, dragOverId, getAppIconUrl, onSelect, onOpen, onContextMenu, onContextMenuEmpty, onNameClick, onRename, onRenameCancel, onDragStart, onDragOver, onDragLeave, onDrop, onThumbnailError, }: FileGridProps): react_jsx_runtime.JSX.Element;
+
+interface FileListProps {
+    items: FileItem[];
+    selectedIds: Set<string>;
+    sortConfig?: SortConfig;
+    editingId?: string | null;
+    dragOverId?: string | null;
+    onSelect?: (item: FileItem, e: React.MouseEvent) => void;
+    onOpen?: (item: FileItem) => void;
+    onContextMenu?: (item: FileItem, e: React.MouseEvent) => void;
+    onContextMenuEmpty?: (e: React.MouseEvent) => void;
+    onNameClick?: (item: FileItem, e: React.MouseEvent) => void;
+    onRename?: (item: FileItem, newName: string) => void;
+    onRenameCancel?: (item: FileItem) => void;
+    onSort?: (field: string) => void;
+    onDragStart?: (e: React.DragEvent, item: FileItem) => void;
+    onDragOver?: (e: React.DragEvent, item: FileItem) => void;
+    onDragLeave?: (e: React.DragEvent) => void;
+    onDrop?: (e: React.DragEvent, item: FileItem) => void;
+}
+declare function FileList({ items, selectedIds, sortConfig, editingId, dragOverId, onSelect, onOpen, onContextMenu, onContextMenuEmpty, onNameClick, onRename, onRenameCancel, onSort, onDragStart, onDragOver, onDragLeave, onDrop, }: FileListProps): react_jsx_runtime.JSX.Element;
+
+interface ContextMenuProps {
+    visible: boolean;
+    x: number;
+    y: number;
+    options: ContextMenuItem[];
+    onClose?: () => void;
+    onSelect?: (option: ContextMenuItem) => void;
+}
+declare function ContextMenu({ visible, x, y, options, onClose, onSelect, }: ContextMenuProps): react.ReactPortal | null;
+
+interface SortIndicatorProps {
+    direction: 'asc' | 'desc';
+}
+declare function SortIndicator({ direction }: SortIndicatorProps): react_jsx_runtime.JSX.Element;
+
+interface WindowProps {
+    title?: string;
+    showTitleBar?: boolean;
+    showMinimize?: boolean;
+    showMaximize?: boolean;
+    draggable?: boolean;
+    resizable?: boolean;
+    width?: string | number;
+    height?: string | number;
+    minWidth?: string | number;
+    minHeight?: string | number;
+    maxWidth?: string | number;
+    maxHeight?: string | number;
+    closeOnBackdrop?: boolean;
+    fitContent?: boolean;
+    onClose?: () => void;
+    onMinimize?: () => void;
+    onMaximize?: () => void;
+    children?: React.ReactNode;
+    titleSlot?: React.ReactNode;
+    actionsSlot?: React.ReactNode;
+}
+declare function Window({ title, showTitleBar, showMinimize, showMaximize, draggable, resizable, closeOnBackdrop, width, height, minWidth, minHeight, maxWidth, maxHeight, fitContent, onClose, onMinimize, onMaximize, children, titleSlot, actionsSlot, }: WindowProps): react.ReactPortal;
+
+type CompressDialogOptions = Omit<CompressOptions, 'outputDir'>;
+interface CompressDialogProps {
+    visible: boolean;
+    /** 要压缩的文件/文件夹路径列表 */
+    filePaths: string[];
+    /** 输出目录 */
+    outputDir: string;
+    onConfirm: (options: CompressDialogOptions) => void;
+    onCancel: () => void;
+}
+/**
+ * 压缩对话框组件
+ */
+declare function CompressDialog({ visible, filePaths, outputDir, onConfirm, onCancel, }: CompressDialogProps): react.ReactPortal | null;
+
+/** 进度状态 */
+type ProgressStatus = 'pending' | 'processing' | 'success' | 'error';
+/** 进度信息 */
+interface ProgressInfo {
+    /** 操作类型 */
+    type: 'compress' | 'extract';
+    /** 状态 */
+    status: ProgressStatus;
+    /** 进度百分比 0-100 */
+    percent: number;
+    /** 当前处理的文件 */
+    currentFile?: string;
+    /** 已处理文件数 */
+    processedCount?: number;
+    /** 总文件数 */
+    totalCount?: number;
+    /** 错误信息 */
+    error?: string;
+    /** 输出路径 */
+    outputPath?: string;
+}
+interface ProgressDialogProps {
+    visible: boolean;
+    progress: ProgressInfo;
+    onCancel?: () => void;
+    onClose?: () => void;
+    /** 打开输出文件夹 */
+    onOpenFolder?: (path: string) => void;
+}
+/**
+ * 进度对话框组件
+ */
+declare function ProgressDialog({ visible, progress, onCancel, onClose, onOpenFolder, }: ProgressDialogProps): react.ReactPortal | null;
+
+interface FileInfoDialogProps {
+    /** 是否显示 */
+    visible: boolean;
+    /** 文件项 */
+    item: FileItem | null;
+    /** 关闭回调 */
+    onClose: () => void;
+}
+declare function FileInfoDialog({ visible, item, onClose }: FileInfoDialogProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * 文件选择状态管理
+ */
+declare function useSelection(): {
+    selectedIds: Set<string>;
+    lastSelectedId: string | null;
+    editingId: string | null;
+    clearSelection: () => void;
+    selectItem: (id: string | null, items: FileItem[], multi?: boolean, range?: boolean) => void;
+    selectAll: (items: FileItem[]) => void;
+    setEditing: (id: string | null) => void;
+    isSelected: (id: string) => boolean;
+};
+
+/**
+ * 拖拽操作管理
+ */
+declare function useDragAndDrop(getSelectedIds: () => Set<string>, onSelect: (id: string, multi: boolean, range: boolean) => void, onMove: (targetFolderId: string, itemIds: Set<string>) => void): {
+    dragOverId: string | null;
+    isDragging: boolean;
+    handleDragStart: (e: React.DragEvent, itemId: string) => void;
+    handleDragOver: (e: React.DragEvent, item: FileItem) => void;
+    handleDragLeave: () => void;
+    handleDrop: (e: React.DragEvent, targetItem: FileItem) => void;
+    handleDragEnd: () => void;
+};
+
+/**
+ * 媒体播放器功能管理
+ */
+declare function useMediaPlayer(mediaType: FileType, mediaRef: React.RefObject<HTMLVideoElement | HTMLAudioElement>): {
+    isPlaying: boolean;
+    progress: number;
+    currentTime: number;
+    duration: number;
+    isMuted: boolean;
+    volume: number;
+    showControls: boolean;
+    isAudio: boolean;
+    togglePlay: () => void;
+    toggleMute: () => void;
+    handleVolumeChange: (val: number) => void;
+    seekTo: (time: number) => void;
+    formatTime: (time: number) => string;
+    autoPlay: () => void;
+    updateProgress: () => void;
+};
+
+/**
+ * 窗口拖拽功能管理
+ */
+declare function useWindowDrag(): {
+    position: {
+        x: number;
+        y: number;
+    };
+    isDragging: boolean;
+    startDrag: (e: React.MouseEvent) => void;
+};
+
+type ResizeDirection = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+/**
+ * 窗口调整大小功能管理
+ */
+declare function useWindowResize(initialWidth: number, initialHeight: number, minWidth: number, minHeight: number, maxWidth: number, maxHeight: number): {
+    width: number;
+    height: number;
+    isResizing: boolean;
+    startResize: (e: React.MouseEvent, direction: ResizeDirection, currentWidth: number, currentHeight: number) => void;
+};
+
+declare global {
+    interface Window {
+        fileExplorerAPI?: {
+            getApplicationIcon?: (appPath: string) => Promise<string | null>;
+        };
+    }
+}
+/**
+ * 应用程序图标管理 hook
+ */
+declare function useApplicationIcon(items: FileItem[]): {
+    getAppIconUrl: (item: FileItem) => string | undefined;
+    loadApplicationIcon: (item: FileItem) => Promise<void>;
+};
+
+export { Breadcrumb, type BreadcrumbItem, CompressDialog, type CompressFormat, type CompressLevel, type CompressOptions, type CompressProgress, type CompressResult, ContextMenu, type ContextMenuItem, type ExtractOptions, type FileExplorerAdapter, FileGrid, FileIcon, FileInfoDialog, type FileInfoDialogProps, type FileItem, FileList, FileListView, type FileListViewHandle, FileSidebar, FileType, type MediaMetadata, type MediaTranscodeProgress, type OperationResult, ProgressDialog, type ProgressInfo, type ProgressStatus, type SidebarItem, type SortConfig, SortIndicator, StatusBar, Toolbar, type TranscodeInfo, type TranscodeMethod, type TranscodeStatus, type ViewMode, type WatchEvent, type WatchEventType, Window, useApplicationIcon, useDragAndDrop, useMediaPlayer, useSelection, useWindowDrag, useWindowResize };