my-uniapp-tools/dist/upload/utils.d.ts

一个简洁稳定的 uni-app 开发工具库，提供剪贴板、本地存储、导航、系统信息等常用功能

/**
 * upload 模块工具函数
 *
 * @description
 * 纯函数工具集，遵循 KISS 原则
 * 不要类，不要抽象，只要简单直接的函数
 */
import { UniFile } from './types';
/**
 * 根据文件名或路径提取扩展名（不带点）
 *
 * @example
 * getExtension('photo.jpg') // => 'jpg'
 * getExtension('archive.tar.gz') // => 'gz'
 * getExtension('noext') // => undefined
 */
export declare function getExtension(path: string): string | undefined;
/**
 * 扩展名同义词归一化（用于白名单校验）
 *
 * @description
 * 只处理最常见的 jpg/jpeg/jpe 同义情况，统一归一为 jpg
 * 只用于"比较/校验"，不会修改对外展示的文件名/扩展名
 *
 * @example
 * normalizeExtension('jpeg') // => 'jpg'
 * normalizeExtension('JPG') // => 'jpg'
 * normalizeExtension('.png') // => 'png'
 */
export declare function normalizeExtension(ext: string): string;
/**
 * 归一化扩展名白名单
 */
export declare function normalizeExtensions(extensions: unknown): string[] | undefined;
/**
 * 生成简单的文件唯一 ID
 *
 * @example
 * createFileId(0) // => '1672531200000_0_a1b2c3d4e5f6'
 */
export declare function createFileId(index: number): string;
/**
 * 判断是否为 H5 环境下的 blob URL
 *
 * @example
 * isBlobUrl('blob:http://localhost:8080/xxx') // => true
 * isBlobUrl('http://example.com/image.jpg') // => false
 */
export declare function isBlobUrl(path: string): boolean;
/**
 * 安全回收对象 URL（仅在浏览器环境有效）
 *
 * @description
 * 用于回收 `URL.createObjectURL` 创建的 `blob:` URL
 * 回收失败不应影响主流程
 */
export declare function revokeObjectURLSafely(path: string): void;
/**
 * 安全 JSON 解析
 *
 * @description
 * 对上传接口的响应体进行统一解析
 * 能解析为 JSON 则返回对象，否则返回原始字符串
 * 不会抛错，避免解析失败影响上传主流程
 *
 * @example
 * safeJsonParse('{"code":0}') // => {code: 0}
 * safeJsonParse('plain text') // => 'plain text'
 */
export declare function safeJsonParse(raw: unknown): unknown;
/**
 * 将 formData 的值序列化为字符串
 *
 * @description
 * H5 FormData 只接受 string/Blob 等
 * - string/number/boolean：使用 String()
 * - object/array：默认 JSON.stringify，避免变成 `[object Object]`
 * - 其他：尽量转成字符串，不抛错
 *
 * @example
 * serializeFormDataValue(123) // => '123'
 * serializeFormDataValue({a: 1}) // => '{"a":1}'
 */
export declare function serializeFormDataValue(value: unknown): string;
/**
 * 将业务侧 formData 归一化为可安全发送的字符串字典
 *
 * @description
 * 统一 H5(FormData) 与 uni.uploadFile(formData) 的行为
 * 避免对象被隐式转成 `[object Object]`
 *
 * @example
 * normalizeFormData({a: 1, b: {c: 2}}) // => {a: '1', b: '{"c":2}'}
 */
export declare function normalizeFormData(formData?: unknown): Record<string, string> | undefined;
/**
 * 归一化请求头，避免 JS 侧传入非对象或非字符串值导致平台层行为漂移
 */
export declare function normalizeHeaders(headers?: unknown): Record<string, string> | undefined;
/**
 * 推断当前运行平台（仅用于标记，不做强依赖逻辑）
 *
 * @description
 * 使用条件编译消除运行时分支
 *
 * @returns 平台标识
 */
export declare function detectPlatform(): UniFile['platform'];
/**
 * 归一化 uni.uploadFile 成功回调的状态码
 *
 * @description
 * 部分平台/版本可能缺少 statusCode 字段
 * 尝试从 errMsg 推断或返回 0（代表无法判定）
 *
 * @returns 归一化后的状态码（0 表示未知/不可用）
 */
export declare function normalizeUniUploadStatusCode(res: any): number;
/**
 * 归一化 uni 侧选择文件失败的错误文案
 *
 * @description
 * uni 的 errMsg 往往是英文（例如：`chooseImage:fail cancel`）
 * 最小规则：
 * - 取消选择 → 统一为"用户取消选择"
 * - 其他错误 → 尽量保留中文；若是英文长串则给通用中文提示
 *
 * @example
 * normalizePickFailMessage('chooseImage:fail cancel') // => '用户取消选择'
 * normalizePickFailMessage('未知错误') // => '未知错误'
 */
export declare function normalizePickFailMessage(errMsg?: string): string;
/**
 * 将文件大小（字节）与 MB 限制进行比较
 *
 * @description
 * 仅当 maxMB 为 null 或 undefined 时视为不限制
 * 允许显式传 0（表示不允许选择文件）
 *
 * @example
 * validateFileSize(1024 * 1024 * 10, 5) // => {valid: false, message: '文件大小不能超过 5MB'}
 * validateFileSize(1024 * 1024 * 3, 5) // => {valid: true}
 */
export declare function validateFileSize(size: number, maxMB?: number): {
    valid: boolean;
    message?: string;
};
/**
 * 验证文件列表（大小与扩展名）
 * @param files 文件列表
 * @param config 校验配置
 */
export declare function validateSelectedFiles(files: UniFile[], config: {
    maxSizeMB?: number;
    extensions?: string[];
}): {
    success: boolean;
    message?: string;
};
/**
 * 归一化并发数
 *
 * @description
 * upload 的并发配置属于“控制流参数”，必须在 core 层收敛成一个确定的整数。
 * 规则保持简单直观：
 * - `raw` 是有限正数：向下取整后与 totalCount 取最小值（并发不应超过任务数）
 * - 其他非法值：视为“默认全并发”（等于 totalCount）
 */
export declare function normalizeConcurrency(raw: unknown, totalCount: number): number;