@huyooo/file-explorer-core 0.3.0 → 0.4.2

package/dist/index.d.ts

@@ -260,6 +260,115 @@ declare function exists(filePath: string): Promise<boolean>;
  */
 declare function isDirectory(filePath: string): Promise<boolean>;
 
+/**
+ * Shell 操作
+ *
+ * 系统级操作：显示简介、在新窗口打开等
+ */
+/**
+ * 显示文件/文件夹的系统属性窗口
+ *
+ * - macOS: 打开 Finder 的"显示简介"窗口
+ * - Windows: 打开"属性"窗口
+ * - Linux: 尝试使用文件管理器的属性功能
+ */
+declare function showFileInfo(filePath: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * 在系统文件管理器中显示文件（选中状态）
+ *
+ * 注意：这个功能在 Electron 中可以用 shell.showItemInFolder 实现
+ * 这里提供一个纯 Node.js 的替代实现
+ */
+declare function revealInFileManager(filePath: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * 在终端中打开目录
+ * macOS: 优先 iTerm2，回退到 Terminal.app
+ */
+declare function openInTerminal(dirPath: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * 通过 Cursor 打开
+ * 优先 Cursor，回退到 VSCode
+ */
+declare function openInEditor(targetPath: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+
+/**
+ * 压缩/解压操作
+ *
+ * 支持格式：zip, tar, tar.gz (tgz), tar.bz2
+ */
+/** 压缩格式 */
+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;
+}
+/** 进度回调 */
+type ProgressCallback$1 = (progress: CompressProgress) => void;
+/**
+ * 根据文件扩展名检测格式
+ */
+declare function detectArchiveFormat(filePath: string): CompressFormat | null;
+/**
+ * 判断文件是否为支持的压缩文件
+ */
+declare function isArchiveFile(filePath: string): boolean;
+/**
+ * 压缩文件/目录
+ */
+declare function compressFiles(sources: string[], options: CompressOptions, onProgress?: ProgressCallback$1): Promise<CompressResult>;
+/**
+ * 解压文件
+ */
+declare function extractArchive(archivePath: string, options: ExtractOptions, onProgress?: ProgressCallback$1): Promise<CompressResult>;
+
 /**
  * 获取系统路径
  */
@@ -302,13 +411,13 @@ declare function searchFilesSync(searchPath: string, pattern?: string, maxDepth?
 
 /**
  * 计算文件的快速 hash（使用文件大小和修改时间）
+ * 使用 xxHash64 算法，专为非加密场景设计，性能极快
  * 这比计算完整文件 hash 快得多，适合用于缓存判断
+ *
+ * @param filePath - 文件路径
+ * @param stats - 可选的文件状态（如果已获取，避免重复调用 stat）
  */
-declare function getFileHash(filePath: string): Promise<string>;
-/**
- * 批量计算文件 hash
- */
-declare function getFileHashes(filePaths: string[]): Promise<Map<string, string>>;
+declare function getFileHash(filePath: string, stats?: Stats): Promise<string>;
 
 /**
  * 剪贴板文件操作接口
@@ -347,6 +456,61 @@ declare function pasteFiles(targetDir: string, sourcePaths: string[]): Promise<O
  */
 declare function getApplicationIcon(appPath: string): Promise<string | null>;
 
+/**
+ * 文件系统监听服务
+ *
+ * 监听目录变化，当文件增删改时触发回调
+ */
+/** 文件变化类型 */
+type WatchEventType = 'add' | 'change' | 'remove' | 'rename';
+/** 文件变化事件 */
+interface WatchEvent {
+    type: WatchEventType;
+    path: string;
+    filename: string;
+}
+/** 监听回调 */
+type WatchCallback = (event: WatchEvent) => void;
+/** 监听器实例 */
+interface Watcher {
+    /** 停止监听 */
+    close: () => void;
+    /** 监听的目录路径 */
+    path: string;
+}
+/**
+ * 监听目录变化
+ *
+ * @param dirPath 要监听的目录路径
+ * @param callback 变化回调
+ * @returns Watcher 实例
+ */
+declare function watchDirectory(dirPath: string, callback: WatchCallback): Watcher;
+/**
+ * 监听管理器
+ * 用于管理多个监听器，确保同一目录只有一个监听器
+ */
+declare class WatchManager {
+    private watchers;
+    private callbacks;
+    /**
+     * 开始监听目录
+     */
+    watch(dirPath: string, callback: WatchCallback): () => void;
+    /**
+     * 停止监听
+     */
+    private unwatch;
+    /**
+     * 关闭所有监听器
+     */
+    closeAll(): void;
+}
+/**
+ * 获取全局监听管理器
+ */
+declare function getWatchManager(): WatchManager;
+
 /**
  * 缩略图数据库接口
  */
@@ -417,13 +581,13 @@ declare class ThumbnailService {
      */
     generateThumbnail(filePath: string, fileHash: string, mtime: number): Promise<string | null>;
     /**
-     * 批量生成缩略图
+     * 批量生成缩略图（带并发限制，避免资源耗尽）
      */
     generateThumbnailsBatch(files: Array<{
         path: string;
         hash: string;
         mtime: number;
-    }>): Promise<void>;
+    }>, concurrency?: number): Promise<void>;
     /**
      * 删除缩略图
      */
@@ -448,13 +612,36 @@ declare function getThumbnailService(): ThumbnailService | null;
  * 需要安装 better-sqlite3：npm install better-sqlite3
  */
 
+interface SqliteThumbnailDatabaseOptions {
+    /**
+     * 缩略图存储目录（绝对路径）。如果提供，则优先使用该目录。
+     * 适用于将本库嵌入到其他应用时，自定义缩略图缓存位置。
+     */
+    thumbnailDir?: string;
+    /**
+     * 缩略图子目录名（相对 userDataPath）。默认：`thumbnails`
+     * 仅在未提供 thumbnailDir 时生效。
+     */
+    dirName?: string;
+    /**
+     * 缩略图数据库文件名（默认：`thumbnails.db`）
+     * 仅在未提供 dbPath 时生效。
+     */
+    dbFileName?: string;
+    /**
+     * 缩略图数据库文件路径（绝对路径）。如果提供，则优先使用该路径。
+     * 注意：缩略图 jpg 仍然会写入 thumbnailDir（若未显式提供，则使用 dbPath 所在目录）。
+     */
+    dbPath?: string;
+}
 /**
  * SQLite 缩略图数据库实现
  */
 declare class SqliteThumbnailDatabase implements ThumbnailDatabase {
     private db;
     private cacheDir;
-    constructor(userDataPath: string);
+    private dbPath;
+    constructor(userDataPath: string, options?: SqliteThumbnailDatabaseOptions);
     /**
      * 初始化数据库
      */
@@ -474,11 +661,21 @@ declare class SqliteThumbnailDatabase implements ThumbnailDatabase {
 /**
  * 创建 SQLite 缩略图数据库
  */
-declare function createSqliteThumbnailDatabase(userDataPath: string): SqliteThumbnailDatabase;
+/**
+ * 创建 SQLite 缩略图数据库（统一入口：仅支持 options 对象）
+ * 说明：不再支持“传 dbPath 当作参数”的用法；宿主需要显式传入 userDataPath（以及可选的目录/文件覆盖）。
+ */
+declare function createSqliteThumbnailDatabase(options: {
+    userDataPath: string;
+} & SqliteThumbnailDatabaseOptions): SqliteThumbnailDatabase;
 /**
  * 获取缩略图数据库实例
  */
 declare function getSqliteThumbnailDatabase(): SqliteThumbnailDatabase | null;
+/**
+ * 关闭缩略图数据库（应在应用退出时调用）
+ */
+declare function closeThumbnailDatabase(): void;
 
 /**
  * 缩略图处理器工厂函数
@@ -492,12 +689,14 @@ declare function getSqliteThumbnailDatabase(): SqliteThumbnailDatabase | null;
  * Sharp 类型定义（宽松类型，兼容 sharp 模块）
  */
 interface SharpInstance {
-    resize(width: number, height: number, options?: {
-        fit?: string;
+    resize(options?: {
+        width?: number;
+        height?: number;
         withoutEnlargement?: boolean;
     }): SharpInstance;
     jpeg(options?: {
         quality?: number;
+        optimiseCoding?: boolean;
     }): SharpInstance;
     toFile(outputPath: string): Promise<unknown>;
 }
@@ -531,4 +730,220 @@ declare function createSharpImageProcessor(sharp: SharpModule): ImageProcessor;
  */
 declare function createFfmpegVideoProcessor(ffmpegPath: string): VideoProcessor;
 
-export { APP_PROTOCOL_HOST, APP_PROTOCOL_PREFIX, APP_PROTOCOL_SCHEME, type ClipboardAdapter, type DeleteOptions, type FileInfo, type FileItem, type FileOperationOptions, FileType, type ImageProcessor, type OperationResult, type PlatformAdapter, type ReadDirectoryOptions, type RenameOptions, SqliteThumbnailDatabase, type SystemPathId, type ThumbnailDatabase, ThumbnailService, type ThumbnailServiceOptions, type UrlEncoder, type VideoProcessor, copyFiles, copyFilesToClipboard, createFfmpegVideoProcessor, createFile, createFolder, createSharpImageProcessor, createSqliteThumbnailDatabase, decodeFileUrl, deleteFiles, encodeFileUrl, exists, formatDate, formatDateTime, formatFileSize, getAllSystemPaths, getApplicationIcon, getClipboardFiles, getFileHash, getFileHashes, getFileInfo, getFileType, getHomeDirectory, getPlatform, getSqliteThumbnailDatabase, getSystemPath, getThumbnailService, initThumbnailService, isAppProtocolUrl, isDirectory, isMediaFile, isPreviewable, moveFiles, pasteFiles, readDirectory, readFileContent, readImageAsBase64, renameFile, searchFiles, searchFilesStream, searchFilesSync, writeFileContent };
+/**
+ * 媒体类型
+ */
+type MediaType = 'video' | 'audio';
+/**
+ * 转码方式
+ * - direct: 直接播放，无需转换
+ * - remux: 转封装，只改变容器格式，不重新编码（快速）
+ * - transcode: 转码，重新编码（较慢）
+ */
+type TranscodeMethod = 'direct' | 'remux' | 'transcode';
+/**
+ * 转码状态
+ */
+type TranscodeStatus = 'idle' | 'checking' | 'transcoding' | 'ready' | 'error';
+/**
+ * 媒体格式信息
+ */
+interface MediaFormatInfo {
+    /** 媒体类型 */
+    type: MediaType;
+    /** 容器格式 (mp4, mkv, avi...) */
+    container: string;
+    /** 视频编码 (h264, h265, vp9...) */
+    videoCodec?: string;
+    /** 音频编码 (aac, mp3, flac...) */
+    audioCodec?: string;
+    /** 时长（秒） */
+    duration?: number;
+    /** 宽度 */
+    width?: number;
+    /** 高度 */
+    height?: number;
+    /** 比特率 */
+    bitrate?: number;
+}
+/**
+ * 转码检测结果
+ */
+interface TranscodeInfo {
+    /** 媒体类型 */
+    type: MediaType;
+    /** 是否需要转码 */
+    needsTranscode: boolean;
+    /** 转码方式 */
+    method: TranscodeMethod;
+    /** 预估时间（秒），仅转码时有值 */
+    estimatedTime?: number;
+    /** 原始格式信息 */
+    formatInfo?: MediaFormatInfo;
+    /** 目标格式 */
+    targetFormat?: string;
+}
+/**
+ * 转码进度
+ */
+interface TranscodeProgress {
+    /** 进度百分比 0-100 */
+    percent: number;
+    /** 当前处理时间（秒） */
+    time?: number;
+    /** 总时长（秒） */
+    duration?: number;
+    /** 速度（如 "2.5x"） */
+    speed?: string;
+}
+/**
+ * 转码结果
+ */
+interface TranscodeResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 可播放的 URL（成功时） */
+    url?: string;
+    /** 输出文件路径（成功时） */
+    outputPath?: string;
+    /** 错误信息（失败时） */
+    error?: string;
+}
+/**
+ * 媒体元数据
+ */
+interface MediaMetadata {
+    /** 文件路径 */
+    filePath: string;
+    /** 媒体类型 */
+    type: MediaType;
+    /** 时长（秒） */
+    duration: number;
+    /** 格式信息 */
+    format: MediaFormatInfo;
+    /** 标题 */
+    title?: string;
+    /** 艺术家 */
+    artist?: string;
+    /** 专辑 */
+    album?: string;
+    /** 年份 */
+    year?: string;
+}
+/**
+ * 进度回调函数
+ */
+type ProgressCallback = (progress: TranscodeProgress) => void;
+/**
+ * 媒体服务配置
+ */
+interface MediaServiceOptions {
+    /** ffmpeg 路径 */
+    ffmpegPath: string;
+    /** ffprobe 路径（可选，默认与 ffmpeg 同目录） */
+    ffprobePath?: string;
+    /** 临时文件目录 */
+    tempDir?: string;
+    /** URL 编码器 */
+    urlEncoder?: (filePath: string) => string;
+}
+
+/**
+ * 媒体格式检测
+ *
+ * 判断媒体文件是否需要转码，以及使用何种转码方式
+ */
+
+/**
+ * 从文件扩展名判断媒体类型
+ */
+declare function getMediaTypeByExtension(filePath: string): MediaType | null;
+/**
+ * 使用 ffprobe 获取媒体格式信息
+ */
+declare function getMediaFormat(filePath: string, ffprobePath: string): Promise<MediaFormatInfo | null>;
+/**
+ * 检测媒体文件的转码需求
+ */
+declare function detectTranscodeNeeds(filePath: string, ffprobePath: string): Promise<TranscodeInfo>;
+
+/**
+ * 媒体转码器
+ *
+ * 使用 ffmpeg 进行媒体格式转换
+ */
+
+/**
+ * 执行媒体转码
+ */
+declare function transcodeMedia(ffmpegPath: string, inputPath: string, transcodeInfo: TranscodeInfo, tempDir?: string, onProgress?: ProgressCallback): Promise<TranscodeResult>;
+/**
+ * 清理临时转码文件
+ */
+declare function cleanupTranscodedFile(filePath: string): Promise<void>;
+/**
+ * 清理所有临时转码文件
+ */
+declare function cleanupAllTranscodedFiles(tempDir?: string): Promise<void>;
+
+/**
+ * 统一媒体服务
+ *
+ * 提供媒体格式检测、转码、元数据获取等功能
+ */
+
+/**
+ * 媒体服务类
+ */
+declare class MediaService {
+    private ffmpegPath;
+    private ffprobePath;
+    private tempDir?;
+    private urlEncoder?;
+    private transcodeInfoCache;
+    private transcodedFiles;
+    constructor(options: MediaServiceOptions);
+    /**
+     * 检测文件是否需要转码
+     */
+    needsTranscode(filePath: string): Promise<TranscodeInfo>;
+    /**
+     * 执行转码并返回可播放的 URL
+     */
+    transcode(filePath: string, onProgress?: ProgressCallback): Promise<TranscodeResult>;
+    /**
+     * 获取媒体元数据
+     */
+    getMetadata(filePath: string): Promise<MediaMetadata | null>;
+    /**
+     * 获取可播放的 URL
+     * 如果文件需要转码，则执行转码；否则直接返回文件 URL
+     */
+    getPlayableUrl(filePath: string, onProgress?: ProgressCallback): Promise<string | null>;
+    /**
+     * 清理指定文件的转码缓存
+     */
+    cleanupFile(filePath: string): Promise<void>;
+    /**
+     * 清理所有转码缓存
+     */
+    cleanup(): Promise<void>;
+    /**
+     * 清除缓存（不删除文件）
+     */
+    clearCache(): void;
+}
+/**
+ * 初始化媒体服务
+ */
+declare function initMediaService(options: MediaServiceOptions): MediaService;
+/**
+ * 获取媒体服务实例
+ */
+declare function getMediaService(): MediaService | null;
+/**
+ * 创建媒体服务（不设为全局实例）
+ */
+declare function createMediaService(options: MediaServiceOptions): MediaService;
+
+export { APP_PROTOCOL_HOST, APP_PROTOCOL_PREFIX, APP_PROTOCOL_SCHEME, type ClipboardAdapter, type CompressFormat, type CompressLevel, type CompressOptions, type CompressProgress, type CompressResult, type DeleteOptions, type ExtractOptions, type FileInfo, type FileItem, type FileOperationOptions, FileType, type ImageProcessor, type MediaFormatInfo, type MediaMetadata, type ProgressCallback as MediaProgressCallback, MediaService, type MediaServiceOptions, type MediaType, type OperationResult, type PlatformAdapter, type ProgressCallback$1 as ProgressCallback, type ReadDirectoryOptions, type RenameOptions, SqliteThumbnailDatabase, type SystemPathId, type ThumbnailDatabase, ThumbnailService, type ThumbnailServiceOptions, type TranscodeInfo, type TranscodeMethod, type TranscodeProgress, type TranscodeResult, type TranscodeStatus, type UrlEncoder, type VideoProcessor, type WatchCallback, type WatchEvent, type WatchEventType, WatchManager, type Watcher, cleanupAllTranscodedFiles, cleanupTranscodedFile, closeThumbnailDatabase, compressFiles, copyFiles, copyFilesToClipboard, createFfmpegVideoProcessor, createFile, createFolder, createMediaService, createSharpImageProcessor, createSqliteThumbnailDatabase, decodeFileUrl, deleteFiles, detectArchiveFormat, detectTranscodeNeeds, encodeFileUrl, exists, extractArchive, formatDate, formatDateTime, formatFileSize, getAllSystemPaths, getApplicationIcon, getClipboardFiles, getFileHash, getFileInfo, getFileType, getHomeDirectory, getMediaFormat, getMediaService, getMediaTypeByExtension, getPlatform, getSqliteThumbnailDatabase, getSystemPath, getThumbnailService, getWatchManager, initMediaService, initThumbnailService, isAppProtocolUrl, isArchiveFile, isDirectory, isMediaFile, isPreviewable, moveFiles, openInEditor, openInTerminal, pasteFiles, readDirectory, readFileContent, readImageAsBase64, renameFile, revealInFileManager, searchFiles, searchFilesStream, searchFilesSync, showFileInfo, transcodeMedia, watchDirectory, writeFileContent };