pic-compressor 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +90 -0
  3. package/dist/index.cjs +543 -0
  4. package/dist/index.d.cts +99 -0
  5. package/dist/index.d.mts +99 -0
  6. package/dist/index.mjs +536 -0
  7. package/dist/index.umd.js +2 -0
  8. package/package.json +85 -0
package/dist/index.d.cts ADDED
@@ -0,0 +1,99 @@
1
+
2
+ //#region src/index.d.ts
3
+ /**
4
+ * Browser image compression utilities.
5
+ * @packageDocumentation
6
+ */
7
+ export type ImageType = 'image/jpeg' | 'image/png' | 'image/webp' | 'image/avif';
8
+ type CompressOutputMode = 'legacy' | 'compact';
9
+ export type ImageCompressionPreset = 'balanced' | 'social' | 'high-quality' | 'thumbnail' | 'long-image';
10
+ export interface ICompressOptions {
11
+ /** 业务场景预设，显式传入的其他选项优先级更高，默认 balanced */
12
+ preset?: ImageCompressionPreset;
13
+ /** 压缩质量，取值范围 0 ~ 1；PNG 通常忽略该参数 */
14
+ quality?: number;
15
+ /** 输出图片类型，默认 image/jpeg */
16
+ mime?: ImageType;
17
+ /** 最大宽度；仅设置该值时不使用默认高度限制 */
18
+ maxWidth?: number;
19
+ /** 最大高度；仅设置该值时不使用默认宽度限制 */
20
+ maxHeight?: number;
21
+ /** 最大宽高的兼容配置，等价于同时设置 maxWidth 和 maxHeight */
22
+ maxSize?: number;
23
+ /** 小于该体积时不压缩，默认 50KB */
24
+ minFileSizeKB?: number;
25
+ /** 输出图片最大像素数，默认约 8.4MP，用于避免大 Canvas 造成 OOM */
26
+ maxPixels?: number;
27
+ /** Canvas 单边的安全上限，默认 8192px；受限 WebView 可主动降为 4096 */
28
+ maxCanvasDimension?: number;
29
+ /** 是否在宽高比达到 3:1 时放宽长边限制，默认由 preset 决定 */
30
+ preserveLongImage?: boolean;
31
+ /** 期望的最大文件体积，单位 KB；会迭代调整质量，必要时继续缩小尺寸 */
32
+ targetFileSizeKB?: number | null;
33
+ /** 迭代压缩的最低质量，默认由 preset 决定 */
34
+ minQuality?: number;
35
+ /** 目标体积压缩的最大编码次数，默认 8 */
36
+ maxIterations?: number;
37
+ /** FileList 的最大并发数，默认 2 */
38
+ concurrency?: number;
39
+ /**
40
+ * legacy 保留 Data URL、Uint8Array 等旧返回字段；compact 仅返回必要信息，显著降低内存占用。
41
+ * 默认 legacy，以保持向后兼容。
42
+ */
43
+ outputMode?: CompressOutputMode;
44
+ /** 未缩放且输出不小于原文件时返回原文件，默认 true */
45
+ keepOriginalIfLarger?: boolean;
46
+ /** 输出 JPEG 时透明像素的背景色，默认 #fff */
47
+ backgroundColor?: string;
48
+ /** 输出格式不被运行环境支持时是否拒绝，默认 false（接受 Canvas 回退格式） */
49
+ strictMime?: boolean;
50
+ /** 压缩进度回调，取值 0 ~ 100 */
51
+ onProgress?: (progress: number) => void;
52
+ /** 用于取消单图或批量压缩 */
53
+ signal?: AbortSignal;
54
+ /** 当输入为 Blob 时使用的文件名，默认 image */
55
+ fileName?: string;
56
+ }
57
+ export interface ICompressImgResult {
58
+ file: File;
59
+ bufferArray?: Uint8Array;
60
+ origin?: File;
61
+ beforeSrc?: string;
62
+ afterSrc?: string;
63
+ beforeKB?: number;
64
+ afterKB?: number;
65
+ width?: number;
66
+ height?: number;
67
+ mime?: string;
68
+ compressed?: boolean;
69
+ quality?: number;
70
+ iterations?: number;
71
+ targetAchieved?: boolean;
72
+ }
73
+ export interface CompressionPresetOptions {
74
+ quality: number;
75
+ minQuality: number;
76
+ maxWidth?: number;
77
+ maxHeight?: number;
78
+ maxPixels: number;
79
+ targetFileSizeKB?: number;
80
+ preserveLongImage?: boolean;
81
+ }
82
+ /** Detect whether the current runtime can create a usable Canvas 2D context. */
83
+ export declare function supportCanvas(): boolean;
84
+ export declare const IMAGE_COMPRESSION_PRESETS: Readonly<Record<ImageCompressionPreset, Readonly<CompressionPresetOptions>>>;
85
+ /**
86
+ * Web 端等比例压缩图片，支持单文件和 FileList。
87
+ * 默认普通图片最大宽高为 2560px；长图会按方向放宽长边，但始终受 maxPixels 限制。
88
+ * 批量处理默认最多并发两张；生产环境建议使用 outputMode: 'compact' 降低内存峰值。
89
+ */
90
+ export declare function compressImage(file: File, options?: ICompressOptions): Promise<ICompressImgResult>;
91
+ export declare function compressImage(file: Blob, options?: ICompressOptions): Promise<ICompressImgResult>;
92
+ export declare function compressImage(file: FileList, options?: ICompressOptions): Promise<ICompressImgResult[]>;
93
+ declare const _default: {
94
+ IMAGE_COMPRESSION_PRESETS: Readonly<Record<ImageCompressionPreset, Readonly<CompressionPresetOptions>>>;
95
+ supportCanvas: typeof supportCanvas;
96
+ compressImage: typeof compressImage;
97
+ };
98
+ //#endregion
99
+ export { _default as default };
package/dist/index.d.mts ADDED
@@ -0,0 +1,99 @@
1
+
2
+ //#region src/index.d.ts
3
+ /**
4
+ * Browser image compression utilities.
5
+ * @packageDocumentation
6
+ */
7
+ export type ImageType = 'image/jpeg' | 'image/png' | 'image/webp' | 'image/avif';
8
+ type CompressOutputMode = 'legacy' | 'compact';
9
+ export type ImageCompressionPreset = 'balanced' | 'social' | 'high-quality' | 'thumbnail' | 'long-image';
10
+ export interface ICompressOptions {
11
+ /** 业务场景预设，显式传入的其他选项优先级更高，默认 balanced */
12
+ preset?: ImageCompressionPreset;
13
+ /** 压缩质量，取值范围 0 ~ 1；PNG 通常忽略该参数 */
14
+ quality?: number;
15
+ /** 输出图片类型，默认 image/jpeg */
16
+ mime?: ImageType;
17
+ /** 最大宽度；仅设置该值时不使用默认高度限制 */
18
+ maxWidth?: number;
19
+ /** 最大高度；仅设置该值时不使用默认宽度限制 */
20
+ maxHeight?: number;
21
+ /** 最大宽高的兼容配置，等价于同时设置 maxWidth 和 maxHeight */
22
+ maxSize?: number;
23
+ /** 小于该体积时不压缩，默认 50KB */
24
+ minFileSizeKB?: number;
25
+ /** 输出图片最大像素数，默认约 8.4MP，用于避免大 Canvas 造成 OOM */
26
+ maxPixels?: number;
27
+ /** Canvas 单边的安全上限，默认 8192px；受限 WebView 可主动降为 4096 */
28
+ maxCanvasDimension?: number;
29
+ /** 是否在宽高比达到 3:1 时放宽长边限制，默认由 preset 决定 */
30
+ preserveLongImage?: boolean;
31
+ /** 期望的最大文件体积，单位 KB；会迭代调整质量，必要时继续缩小尺寸 */
32
+ targetFileSizeKB?: number | null;
33
+ /** 迭代压缩的最低质量，默认由 preset 决定 */
34
+ minQuality?: number;
35
+ /** 目标体积压缩的最大编码次数，默认 8 */
36
+ maxIterations?: number;
37
+ /** FileList 的最大并发数，默认 2 */
38
+ concurrency?: number;
39
+ /**
40
+ * legacy 保留 Data URL、Uint8Array 等旧返回字段；compact 仅返回必要信息，显著降低内存占用。
41
+ * 默认 legacy，以保持向后兼容。
42
+ */
43
+ outputMode?: CompressOutputMode;
44
+ /** 未缩放且输出不小于原文件时返回原文件，默认 true */
45
+ keepOriginalIfLarger?: boolean;
46
+ /** 输出 JPEG 时透明像素的背景色，默认 #fff */
47
+ backgroundColor?: string;
48
+ /** 输出格式不被运行环境支持时是否拒绝，默认 false（接受 Canvas 回退格式） */
49
+ strictMime?: boolean;
50
+ /** 压缩进度回调，取值 0 ~ 100 */
51
+ onProgress?: (progress: number) => void;
52
+ /** 用于取消单图或批量压缩 */
53
+ signal?: AbortSignal;
54
+ /** 当输入为 Blob 时使用的文件名，默认 image */
55
+ fileName?: string;
56
+ }
57
+ export interface ICompressImgResult {
58
+ file: File;
59
+ bufferArray?: Uint8Array;
60
+ origin?: File;
61
+ beforeSrc?: string;
62
+ afterSrc?: string;
63
+ beforeKB?: number;
64
+ afterKB?: number;
65
+ width?: number;
66
+ height?: number;
67
+ mime?: string;
68
+ compressed?: boolean;
69
+ quality?: number;
70
+ iterations?: number;
71
+ targetAchieved?: boolean;
72
+ }
73
+ export interface CompressionPresetOptions {
74
+ quality: number;
75
+ minQuality: number;
76
+ maxWidth?: number;
77
+ maxHeight?: number;
78
+ maxPixels: number;
79
+ targetFileSizeKB?: number;
80
+ preserveLongImage?: boolean;
81
+ }
82
+ /** Detect whether the current runtime can create a usable Canvas 2D context. */
83
+ export declare function supportCanvas(): boolean;
84
+ export declare const IMAGE_COMPRESSION_PRESETS: Readonly<Record<ImageCompressionPreset, Readonly<CompressionPresetOptions>>>;
85
+ /**
86
+ * Web 端等比例压缩图片，支持单文件和 FileList。
87
+ * 默认普通图片最大宽高为 2560px；长图会按方向放宽长边，但始终受 maxPixels 限制。
88
+ * 批量处理默认最多并发两张；生产环境建议使用 outputMode: 'compact' 降低内存峰值。
89
+ */
90
+ export declare function compressImage(file: File, options?: ICompressOptions): Promise<ICompressImgResult>;
91
+ export declare function compressImage(file: Blob, options?: ICompressOptions): Promise<ICompressImgResult>;
92
+ export declare function compressImage(file: FileList, options?: ICompressOptions): Promise<ICompressImgResult[]>;
93
+ declare const _default: {
94
+ IMAGE_COMPRESSION_PRESETS: Readonly<Record<ImageCompressionPreset, Readonly<CompressionPresetOptions>>>;
95
+ supportCanvas: typeof supportCanvas;
96
+ compressImage: typeof compressImage;
97
+ };
98
+ //#endregion
99
+ export { _default as default };