sa2kit 3.0.0 → 3.2.0

package/dist/common/universalFile/index.d.ts

@@ -0,0 +1,409 @@
+import { b as ProcessingOptions, F as FileMetadata, d as UploadProgress } from '../../types-8TOIsyLn.js';
+export { A as AccessPermission, c as AudioProcessingOptions, B as BatchOperationResult, o as CDNProviderError, C as CDNType, i as FileEvent, j as FileEventListener, h as FileEventType, m as FileProcessingError, f as FileQueryOptions, k as FileServiceError, l as FileUploadError, I as ImageProcessingOptions, g as PaginatedResult, P as ProcessorType, n as StorageProviderError, S as StorageType, a as UploadFileInfo, e as UploadResult, U as UploadStatus, V as VideoProcessingOptions } from '../../types-8TOIsyLn.js';
+export { U as UniversalFileClient, a as UniversalFileClientConfig, c as createFileClient, u as universalFileClient } from '../../client-BPQS6bKB.js';
+import React__default from 'react';
+import { U as UniversalFileService } from '../../UniversalFileService-BD23NXUR.js';
+import 'events';
+
+/**
+ * 通用文件服务常量定义
+ */
+/** 模块版本 */
+declare const UNIVERSAL_FILE_VERSION = "1.0.0";
+/** 模块名称 */
+declare const UNIVERSAL_FILE_NAME = "@qhr123/sa2kit/universalFile";
+/** 默认最大文件大小(字节) - 100MB */
+declare const DEFAULT_MAX_FILE_SIZE: number;
+/** 默认最大图片大小(字节) - 10MB */
+declare const DEFAULT_MAX_IMAGE_SIZE: number;
+/** 默认最大视频大小(字节) - 500MB */
+declare const DEFAULT_MAX_VIDEO_SIZE: number;
+/** 默认最大音频大小(字节) - 50MB */
+declare const DEFAULT_MAX_AUDIO_SIZE: number;
+/** 默认最大文档大小(字节) - 20MB */
+declare const DEFAULT_MAX_DOCUMENT_SIZE: number;
+/** 图片MIME类型 */
+declare const IMAGE_MIME_TYPES: string[];
+/** 视频MIME类型 */
+declare const VIDEO_MIME_TYPES: string[];
+/** 音频MIME类型 */
+declare const AUDIO_MIME_TYPES: string[];
+/** 文档MIME类型 */
+declare const DOCUMENT_MIME_TYPES: string[];
+/** 所有支持的MIME类型 */
+declare const ALL_SUPPORTED_MIME_TYPES: string[];
+/** 图片扩展名 */
+declare const IMAGE_EXTENSIONS: string[];
+/** 视频扩展名 */
+declare const VIDEO_EXTENSIONS: string[];
+/** 音频扩展名 */
+declare const AUDIO_EXTENSIONS: string[];
+/** 文档扩展名 */
+declare const DOCUMENT_EXTENSIONS: string[];
+/** API基础路径 */
+declare const API_BASE_PATH = "/api/universal-file";
+/** API端点 */
+declare const API_ENDPOINTS: {
+    /** 上传文件 */
+    readonly UPLOAD: string;
+    /** 获取文件URL */
+    readonly GET_URL: (fileId: string) => string;
+    /** 获取文件元数据 */
+    readonly GET_METADATA: (fileId: string) => string;
+    /** 删除文件 */
+    readonly DELETE: (fileId: string) => string;
+    /** 查询文件列表 */
+    readonly QUERY: string;
+    /** 批量删除 */
+    readonly BATCH_DELETE: string;
+    /** 获取上传进度 */
+    readonly GET_PROGRESS: (fileId: string) => string;
+};
+/** 错误代码 */
+declare const ERROR_CODES: {
+    /** 文件上传错误 */
+    readonly FILE_UPLOAD_ERROR: "FILE_UPLOAD_ERROR";
+    /** 文件大小超限 */
+    readonly FILE_SIZE_EXCEEDED: "FILE_SIZE_EXCEEDED";
+    /** 文件类型不支持 */
+    readonly FILE_TYPE_NOT_SUPPORTED: "FILE_TYPE_NOT_SUPPORTED";
+    /** 文件不存在 */
+    readonly FILE_NOT_FOUND: "FILE_NOT_FOUND";
+    /** 文件处理错误 */
+    readonly FILE_PROCESSING_ERROR: "FILE_PROCESSING_ERROR";
+    /** 存储提供者错误 */
+    readonly STORAGE_PROVIDER_ERROR: "STORAGE_PROVIDER_ERROR";
+    /** CDN提供者错误 */
+    readonly CDN_PROVIDER_ERROR: "CDN_PROVIDER_ERROR";
+    /** 网络错误 */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** 超时错误 */
+    readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
+    /** 未授权 */
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    /** 权限不足 */
+    readonly FORBIDDEN: "FORBIDDEN";
+    /** 服务器错误 */
+    readonly SERVER_ERROR: "SERVER_ERROR";
+};
+/** 默认分页大小 */
+declare const DEFAULT_PAGE_SIZE = 20;
+/** 默认请求超时时间(毫秒) - 30秒 */
+declare const DEFAULT_REQUEST_TIMEOUT = 30000;
+/** 默认上传超时时间(毫秒) - 5分钟 */
+declare const DEFAULT_UPLOAD_TIMEOUT = 300000;
+/** 默认分片上传大小(字节) - 5MB */
+declare const DEFAULT_CHUNK_SIZE: number;
+
+/**
+ * 通用文件服务工具函数
+ */
+/**
+ * 格式化文件大小
+ */
+declare function formatFileSize(bytes: number): string;
+/**
+ * 解析文件大小字符串
+ */
+declare function parseFileSize(sizeStr: string): number;
+/**
+ * 获取文件扩展名
+ */
+declare function getFileExtension(fileName: string): string;
+/**
+ * 根据文件名获取MIME类型
+ */
+declare function getMimeTypeFromFileName(fileName: string): string;
+/**
+ * 检查MIME类型是否支持
+ */
+declare function isMimeTypeSupported(mimeType: string, allowedTypes?: string[]): boolean;
+/**
+ * 判断是否为图片类型
+ */
+declare function isImageFile(mimeType: string): boolean;
+/**
+ * 判断是否为视频类型
+ */
+declare function isVideoFile(mimeType: string): boolean;
+/**
+ * 判断是否为音频类型
+ */
+declare function isAudioFile(mimeType: string): boolean;
+/**
+ * 判断是否为文档类型
+ */
+declare function isDocumentFile(mimeType: string): boolean;
+/**
+ * 获取文件类型类别
+ */
+declare function getFileCategory(mimeType: string): 'image' | 'video' | 'audio' | 'document' | 'other';
+/**
+ * 验证文件名是否合法
+ */
+declare function validateFileName(fileName: string): boolean;
+/**
+ * 清理文件名，移除非法字符
+ */
+declare function sanitizeFileName(fileName: string): string;
+/**
+ * 生成唯一文件名
+ */
+declare function generateUniqueFileName(originalName: string, fileId: string): string;
+/**
+ * 生成存储路径
+ */
+declare function generateStoragePath(moduleId: string, fileName: string, options?: {
+    businessId?: string;
+    useDate?: boolean;
+    customPrefix?: string;
+}): string;
+/**
+ * 解析存储路径
+ */
+declare function parseStoragePath(path: string): {
+    moduleId?: string;
+    businessId?: string;
+    year?: string;
+    month?: string;
+    day?: string;
+    fileName: string;
+};
+/**
+ * 验证文件大小
+ */
+declare function validateFileSize(file: File, maxSize: number): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * 验证文件类型
+ */
+declare function validateFileType(file: File, allowedTypes?: string[]): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * 验证文件
+ */
+declare function validateFile(file: File, options?: {
+    maxSize?: number;
+    allowedTypes?: string[];
+}): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * 构建查询字符串
+ */
+declare function buildQueryString(params: Record<string, any>): string;
+/**
+ * 解析URL查询参数
+ */
+declare function parseQueryString(url: string): Record<string, string>;
+/**
+ * 计算上传进度
+ */
+declare function calculateProgress(uploadedBytes: number, totalBytes: number): number;
+/**
+ * 计算上传速度
+ */
+declare function calculateSpeed(uploadedBytes: number, elapsedTime: number): number;
+/**
+ * 计算剩余时间
+ */
+declare function calculateRemainingTime(uploadedBytes: number, totalBytes: number, speed: number): number;
+/**
+ * 创建文件错误对象
+ */
+declare function createFileError(code: string, message: string, details?: Record<string, any>): {
+    code: string;
+    message: string;
+    details?: Record<string, any>;
+    timestamp: Date;
+};
+/**
+ * 格式化错误消息
+ */
+declare function formatErrorMessage(error: unknown): string;
+/**
+ * 读取文件为Base64
+ */
+declare function readFileAsBase64(file: File): Promise<string>;
+/**
+ * 读取文件为ArrayBuffer
+ */
+declare function readFileAsArrayBuffer(file: File): Promise<ArrayBuffer>;
+/**
+ * 读取文件为文本
+ */
+declare function readFileAsText(file: File, encoding?: string): Promise<string>;
+
+/**
+ * 通用文件上传组件
+ * Universal File Uploader Component
+ *
+ * 支持拖拽上传、进度显示、多文件上传等功能
+ * 使用 Tailwind CSS 样式，支持暗色模式
+ */
+
+interface FileUploaderProps {
+    /** 文件服务实例 */
+    fileService: UniversalFileService;
+    /** 模块标识 */
+    moduleId: string;
+    /** 业务标识 */
+    businessId?: string;
+    /** 允许的文件类型 */
+    acceptedTypes?: string[];
+    /** 最大文件大小(MB) */
+    maxFileSize?: number;
+    /** 最大文件数量 */
+    maxFiles?: number;
+    /** 是否支持多文件上传 */
+    multiple?: boolean;
+    /** 是否启用文件处理 */
+    enableProcessing?: boolean;
+    /** 默认处理选项 */
+    defaultProcessingOptions?: ProcessingOptions;
+    /** 上传成功回调 */
+    onUploadSuccess?: (files: FileMetadata[]) => void;
+    /** 上传失败回调 */
+    onUploadError?: (error: string) => void;
+    /** 上传进度回调 */
+    onProgress?: (progress: UploadProgress[]) => void;
+    /** 自定义样式类名 */
+    className?: string;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 显示模式 */
+    mode?: 'compact' | 'normal' | 'detailed';
+}
+declare const FileUploader: React__default.FC<FileUploaderProps>;
+
+/**
+ * 通用文件管理组件
+ * 支持文件列表、预览、批量操作、搜索筛选等功能
+ */
+
+interface FileManagerProps {
+    /** 模块ID，限制显示特定模块的文件 */
+    moduleId?: string;
+    /** 业务ID，限制显示特定业务的文件 */
+    businessId?: string;
+    /** 显示模式 */
+    mode?: 'grid' | 'list' | 'table';
+    /** 是否允许上传 */
+    allowUpload?: boolean;
+    /** 是否允许下载 */
+    allowDownload?: boolean;
+    /** 是否允许删除 */
+    allowDelete?: boolean;
+    /** 是否允许批量操作 */
+    allowBatch?: boolean;
+    /** 是否显示预览 */
+    showPreview?: boolean;
+    /** 是否显示搜索 */
+    showSearch?: boolean;
+    /** 是否显示筛选器 */
+    showFilters?: boolean;
+    /** 每页显示数量 */
+    pageSize?: number;
+    /** 自定义操作按钮 */
+    customActions?: Array<{
+        key: string;
+        label: string;
+        icon?: string;
+        onClick: (files: FileMetadata[]) => void;
+        disabled?: (files: FileMetadata[]) => boolean;
+    }>;
+    /** 文件选择回调 */
+    onFileSelect?: (files: FileMetadata[]) => void;
+    /** 上传完成回调 */
+    onUploadComplete?: (files: FileMetadata[]) => void;
+}
+declare const UniversalFileManager: React__default.FC<FileManagerProps>;
+
+/**
+ * 文件夹管理组件
+ * 支持创建、重命名、删除文件夹，以及文件夹树形结构显示
+ */
+
+interface FolderNode {
+    /** 文件夹ID */
+    id: string;
+    /** 文件夹名称 */
+    name: string;
+    /** 父文件夹ID */
+    parentId?: string;
+    /** 子文件夹 */
+    children: FolderNode[];
+    /** 文件数量 */
+    fileCount: number;
+    /** 总大小 */
+    totalSize: number;
+    /** 创建时间 */
+    createdAt: Date;
+    /** 更新时间 */
+    updatedAt: Date;
+    /** 是否展开 */
+    expanded?: boolean;
+}
+interface FolderManagerProps {
+    /** 当前文件夹ID */
+    currentFolderId?: string;
+    /** 文件夹树数据 */
+    folderTree: FolderNode[];
+    /** 是否显示文件数量 */
+    showFileCount?: boolean;
+    /** 是否显示文件大小 */
+    showSize?: boolean;
+    /** 是否允许创建文件夹 */
+    allowCreate?: boolean;
+    /** 是否允许重命名 */
+    allowRename?: boolean;
+    /** 是否允许删除 */
+    allowDelete?: boolean;
+    /** 是否允许拖拽 */
+    allowDrag?: boolean;
+    /** 文件夹选择回调 */
+    onFolderSelect?: (folderId: string) => void;
+    /** 文件夹创建回调 */
+    onFolderCreate?: (parentId: string | undefined, name: string) => Promise<FolderNode>;
+    /** 文件夹重命名回调 */
+    onFolderRename?: (folderId: string, newName: string) => Promise<void>;
+    /** 文件夹删除回调 */
+    onFolderDelete?: (folderId: string) => Promise<void>;
+    /** 文件移动回调 */
+    onFileMove?: (fileIds: string[], targetFolderId: string) => Promise<void>;
+}
+declare const FolderManager: React__default.FC<FolderManagerProps>;
+
+/**
+ * 文件分享模态框组件
+ * 支持生成分享链接、设置访问权限、过期时间等
+ */
+
+interface FileShareModalProps {
+    /** 要分享的文件 */
+    files: FileMetadata[];
+    /** 关闭回调 */
+    onClose: () => void;
+    /** 分享成功回调 */
+    onShareSuccess?: (shareInfo: ShareInfo) => void;
+}
+interface ShareInfo {
+    /** 分享链接 */
+    shareUrl: string;
+    /** 访问密码 */
+    password?: string;
+    /** 过期时间 */
+    expiresAt?: Date;
+    /** 访问权限 */
+    permission: 'view' | 'download';
+    /** 分享代码 */
+    shareCode: string;
+}
+declare const FileShareModal: React__default.FC<FileShareModalProps>;
+
+export { ALL_SUPPORTED_MIME_TYPES, API_BASE_PATH, API_ENDPOINTS, AUDIO_EXTENSIONS, AUDIO_MIME_TYPES, DEFAULT_CHUNK_SIZE, DEFAULT_MAX_AUDIO_SIZE, DEFAULT_MAX_DOCUMENT_SIZE, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_IMAGE_SIZE, DEFAULT_MAX_VIDEO_SIZE, DEFAULT_PAGE_SIZE, DEFAULT_REQUEST_TIMEOUT, DEFAULT_UPLOAD_TIMEOUT, DOCUMENT_EXTENSIONS, DOCUMENT_MIME_TYPES, ERROR_CODES, type FileManagerProps, FileMetadata, FileShareModal, type FileShareModalProps, FileUploader, type FileUploaderProps, FolderManager, type FolderManagerProps, type FolderNode, IMAGE_EXTENSIONS, IMAGE_MIME_TYPES, ProcessingOptions, type ShareInfo, UNIVERSAL_FILE_NAME, UNIVERSAL_FILE_VERSION, UniversalFileManager, UploadProgress, VIDEO_EXTENSIONS, VIDEO_MIME_TYPES, buildQueryString, calculateProgress, calculateRemainingTime, calculateSpeed, createFileError, formatErrorMessage, formatFileSize, generateStoragePath, generateUniqueFileName, getFileCategory, getFileExtension, getMimeTypeFromFileName, isAudioFile, isDocumentFile, isImageFile, isMimeTypeSupported, isVideoFile, parseFileSize, parseQueryString, parseStoragePath, readFileAsArrayBuffer, readFileAsBase64, readFileAsText, sanitizeFileName, validateFile, validateFileName, validateFileSize, validateFileType };