@lynker-desktop/electron-sdk 0.0.9-alpha.81 → 0.0.9-alpha.85

package/main/downloader.d.ts

@@ -52,11 +52,13 @@ export interface DownloadOptions {
 export interface DownloadResult {
     /** 是否成功 */
     success: boolean;
-    /** 下载的文件路径 */
+    /** 下载的文件路径（成功时返回） */
     filePath?: string;
-    /** 错误信息 */
+    /** 错误信息（失败时返回，包含错误类型和详细描述） */
     error?: string;
-    /** 文件大小（字节） */
+    /** 错误类型（失败时返回，用于区分不同类型的错误） */
+    errorType?: 'NETWORK' | 'FILE_SYSTEM' | 'PERMISSION' | 'VALIDATION' | 'USER_CANCEL' | 'UNKNOWN';
+    /** 文件大小（字节，成功时返回） */
     size?: number;
 }
 /**
@@ -67,13 +69,25 @@ export declare class Downloader {
     private _downloadingUrls;
     /** 上一次选择的保存文件夹路径 */
     private _lastSelectedDir;
+    /**
+     * 构造函数：初始化下载器并注册 IPC 处理器
+     * 注册 `core:downloader` IPC 处理器，用于从渲染进程接收下载请求
+     */
     constructor();
     /**
      * 下载文件
-     * @param url 要下载的 URL
-     * @param options 下载选项
+     *
+     * 主要流程：
+     * 1. 检查是否正在下载（避免重复下载）
+     * 2. 确定输出路径（支持弹窗选择或自动解析）
+     * 3. 验证并准备输出目录
+     * 4. 处理 base64 data URL 或普通 HTTP 下载
+     * 5. 使用临时文件下载，完成后重命名为最终文件
+     *
+     * @param url 要下载的 URL（支持 HTTP/HTTPS 和 base64 data URL）
+     * @param options 下载选项（输出路径、重试配置、回调函数等）
      * @param onProgress 进度回调函数（可选，优先级高于 options.onProgress）
-     * @returns Promise<DownloadResult> 下载结果
+     * @returns Promise<DownloadResult> 下载结果，包含成功/失败状态、文件路径、错误信息等
      */
     download(url: string, options?: DownloadOptions, onProgress?: DownloadProgressCallback): Promise<DownloadResult>;
     /**
@@ -117,10 +131,31 @@ export declare class Downloader {
      * @returns 清理后的文件名
      */
     private _getFileName;
+    /**
+     * 检查目录是否存在且有访问权限
+     *
+     * 检查项：
+     * 1. 路径是否有效（非空字符串）
+     * 2. 目录是否存在
+     * 3. 路径是否为目录（而非文件）
+     * 4. 是否有读写权限
+     *
+     * @param dirPath 目录路径
+     * @returns 如果目录存在且有读写权限则返回 true，否则返回 false
+     */
+    private _isDirectoryAccessible;
     /**
      * 显示保存对话框
-     * @param url 下载 URL
-     * @param options 下载选项
+     *
+     * 功能说明：
+     * 1. 确定默认保存目录（优先级：defaultPath > outputDir > _lastSelectedDir > 系统下载目录）
+     * 2. 验证并更新 _lastSelectedDir（如果不可访问则重置）
+     * 3. 生成唯一文件名（如果文件已存在，添加数字后缀）
+     * 4. 显示 Electron 保存对话框
+     * 5. 记录用户选择的目录（用于下次默认使用）
+     *
+     * @param url 下载 URL（用于提取默认文件名）
+     * @param options 下载选项（包含 defaultPath、outputDir 等）
      * @param defaultExt 默认扩展名（可选，用于 base64 URL）
      * @returns Promise<string | null> 用户选择的保存路径，如果取消则返回 null
      */
@@ -133,45 +168,87 @@ export declare class Downloader {
     private _isBase64DataUrl;
     /**
      * 保存 base64 数据到文件
-     * @param base64Data base64 编码的数据
-     * @param filePath 目标文件路径
+     *
+     * 处理流程：
+     * 1. 将 base64 字符串解码为 Buffer
+     * 2. 将 Buffer 写入目标文件路径
+     *
+     * @param base64Data base64 编码的数据字符串
+     * @param filePath 目标文件路径（完整路径，包含文件名）
+     * @throws 如果解码失败或文件写入失败，抛出错误
      */
     private _saveBase64ToFile;
     /**
-     * 准备输出路径（确保目录存在、检查文件是否已存在）
-     * @param outputPath 输出路径
-     * @param options 下载选项
-     * @returns 如果文件已存在且不允许覆盖，返回结果；否则返回 null
+     * 准备输出路径
+     *
+     * 主要功能：
+     * 1. 确保输出目录存在（不存在则创建）
+     * 2. 检查文件是否已存在
+     * 3. 如果文件已存在且不允许覆盖，返回已存在的文件信息
+     *
+     * @param outputPath 输出文件路径
+     * @param options 下载选项（包含 override 选项）
+     * @returns 如果文件已存在且不允许覆盖，返回已存在的文件信息；否则返回 null
+     * @throws 如果目录创建失败或权限不足，抛出错误
      */
     private _prepareOutputPath;
     /**
      * 创建成功结果
      * @param filePath 文件路径
-     * @param size 文件大小
-     * @returns DownloadResult
+     * @param size 文件大小（字节）
+     * @returns DownloadResult 成功结果对象
      */
     private _createSuccessResult;
     /**
      * 创建错误结果
      * @param error 错误信息
-     * @returns DownloadResult
+     * @param errorType 错误类型（可选，用于区分不同类型的错误）
+     * @returns DownloadResult 错误结果对象
      */
     private _createErrorResult;
+    /**
+     * 从错误对象中提取错误类型和详细信息
+     * @param error 错误对象
+     * @param url 下载的 URL（用于上下文信息）
+     * @returns 包含错误类型和详细错误信息的对象
+     */
+    private _parseError;
     /**
      * 处理 base64 data URL 的下载
+     *
+     * base64 data URL 格式：data:[<mediatype>][;base64],<data>
+     * 例如：data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
+     *
+     * 处理流程：
+     * 1. 验证 base64 数据有效性
+     * 2. 触发进度回调（模拟 100% 完成）
+     * 3. 解码并保存 base64 数据到文件
+     * 4. 返回成功结果
+     *
      * @param url base64 data URL
-     * @param base64Info base64 信息
+     * @param base64Info base64 信息（扩展名、MIME 类型、数据）
      * @param outputPath 已确定的输出路径
      * @param options 下载选项
-     * @param progressCallback 进度回调
+     * @param progressCallback 进度回调（可选）
      * @returns Promise<DownloadResult> 下载结果
      */
     private _handleBase64Download;
     /**
      * 生成唯一的文件名（如果文件已存在，添加数字后缀）
+     *
+     * 命名规则：
+     * - 如果文件不存在，返回原始文件名
+     * - 如果文件已存在，添加数字后缀：filename(1).ext, filename(2).ext, ...
+     * - 最多尝试 MAX_FILENAME_COUNTER 次，防止无限循环
+     *
+     * 示例：
+     * - "test.pdf" -> "test.pdf" (如果不存在)
+     * - "test.pdf" -> "test(1).pdf" (如果 test.pdf 已存在)
+     * - "test(1).pdf" -> "test(2).pdf" (如果 test(1).pdf 也已存在)
+     *
      * @param dir 目录路径
-     * @param fileName 原始文件名
-     * @returns 唯一的文件名
+     * @param fileName 原始文件名（包含扩展名）
+     * @returns 唯一的文件名（如果原文件不存在则返回原文件名，否则返回带数字后缀的文件名）
      */
     private _generateUniqueFileName;
     /**
@@ -192,6 +269,7 @@ export declare class Downloader {
      * @param options 下载选项
      * @param defaultExt 默认扩展名（可选，用于 base64 URL）
      * @returns 输出文件路径
+     * @throws 如果无法解析有效路径，抛出错误
      */
     private _resolveOutputPath;
 }

package/main/downloader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"downloader.d.ts","sourceRoot":"","sources":["../src/main/downloader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"downloader.d.ts","sourceRoot":"","sources":["../src/main/downloader.ts"],"names":[],"mappings":"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"}