pica-resize-image

Phiên bản: 0.0.6

English | Tiếng Việt

Thư viện resize ảnh chất lượng cao cho trình duyệt sử dụng Pica, có hỗ trợ HEIC/HEIF.

Tính năng

• ✅ Resize ảnh chất lượng cao sử dụng Pica
• ✅ Hỗ trợ nhiều định dạng đầu ra (WebP, PNG, JPEG)
• ✅ Hỗ trợ nhiều kiểu đầu ra (File, Blob, Base64)
• ✅ Hỗ trợ HEIC/HEIF - tự động chuyển đổi
• ✅ Chế độ cover - cắt thông minh để vừa kích thước
• ✅ Xử lý hàng loạt - resize nhiều ảnh cùng lúc
• ✅ Hỗ trợ TypeScript
• ✅ Không cần cấu hình - hoạt động ngay lập tức

Cài đặt

npm install pica-resize-image pica heic2any

hoặc

yarn add pica-resize-image pica heic2any

hoặc

bun add pica-resize-image pica heic2any

Cách sử dụng

Sử dụng cơ bản

import { resizeImage, MIME_TYPE } from "pica-resize-image";

const file = /* File từ input[type="file"] */;

const resized = await resizeImage(file, {
  width: 800,
  height: 600,
  mimeType: MIME_TYPE.webp,
  quality: 0.9,
});

console.log(resized); // Đối tượng File

Resize theo chiều rộng (giữ tỷ lệ khung hình)

const resized = await resizeImage(file, {
  width: 800,
});

Resize theo chiều cao (giữ tỷ lệ khung hình)

const resized = await resizeImage(file, {
  height: 600,
});

Chế độ Cover (cắt để vừa khít)

const resized = await resizeImage(file, {
  width: 800,
  height: 600,
  cover: true, // Cắt ảnh để lấp đầy chính xác kích thước
});

Xuất dưới dạng Base64

import { OUTPUT_TYPE } from "pica-resize-image";

const base64 = await resizeImage(file, {
  width: 800,
  output: OUTPUT_TYPE.base64,
});

console.log(base64); // "data:image/webp;base64,..."

Xuất dưới dạng Blob

const blob = await resizeImage(file, {
  width: 800,
  output: OUTPUT_TYPE.blob,
});

console.log(blob); // Blob { size: 12345, type: "image/webp" }

Xử lý hàng loạt

import { resizeImages } from "pica-resize-image";

const files = /* File[] từ input[type="file"] multiple */;

const resized = await resizeImages(files, {
  width: 800,
  mimeType: MIME_TYPE.jpeg,
  quality: 0.85,
});

console.log(resized); // File[]

Hỗ trợ HEIC

Ảnh HEIC/HEIF (ảnh từ iPhone) được tự động phát hiện và chuyển đổi sang JPEG trước khi resize.

const heicFile = /* File HEIC từ iPhone */;

// Hoạt động tự động - không cần cấu hình đặc biệt!
const resized = await resizeImage(heicFile, {
  width: 800,
  mimeType: MIME_TYPE.webp,
});

// Kết quả: File WebP (HEIC → JPEG → WebP)

Lưu ý: Chuyển đổi HEIC tốn thêm khoảng 1-2 giây thời gian xử lý.

API

resizeImage(image, options?)

Resize một ảnh đơn lẻ.

Tham số:

• image: File - File ảnh cần resize
• options?: ResizeImageOptions - Tùy chọn resize

Trả về: Promise<File | Blob | string> - Ảnh đã được resize

resizeImages(images, options?)

Resize nhiều ảnh.

Tham số:

• images: File[] - Mảng các file ảnh
• options?: ResizeImageOptions - Tùy chọn resize

Trả về: Promise<(File | Blob | string)[]> - Mảng các ảnh đã được resize

ResizeImageOptions

type ResizeImageOptions = {
  width?: number; // Chiều rộng mục tiêu tính bằng pixel
  height?: number; // Chiều cao mục tiêu tính bằng pixel
  cover?: boolean; // Cắt để lấp đầy chính xác kích thước (giống background-size: cover)
  mimeType?: MimeType; // Định dạng đầu ra (mặc định: webp)
  quality?: number; // Chất lượng 0-1 (mặc định: 1)
  output?: OutputType; // Kiểu đầu ra (mặc định: "file")
};

Hằng số

// Kiểu đầu ra
OUTPUT_TYPE.file; // Đối tượng File
OUTPUT_TYPE.blob; // Đối tượng Blob
OUTPUT_TYPE.base64; // Chuỗi Base64

// Kiểu MIME
MIME_TYPE.webp; // image/webp (mặc định, nén tốt nhất)
MIME_TYPE.png; // image/png (không mất dữ liệu)
MIME_TYPE.jpeg; // image/jpeg (kích thước nhỏ hơn)

Ví dụ

Ví dụ 1: Upload ảnh với preview

<input type="file" id="upload" accept="image/*,.heic,.heif" />
<img id="preview" />

<script type="module">
  import { resizeImage, OUTPUT_TYPE } from "pica-resize-image";

  document.getElementById("upload").addEventListener("change", async (e) => {
    const file = e.target.files[0];

    const base64 = await resizeImage(file, {
      width: 400,
      output: OUTPUT_TYPE.base64,
    });

    document.getElementById("preview").src = base64;
  });
</script>

Ví dụ 2: Upload hàng loạt

import { resizeImages, MIME_TYPE } from "pica-resize-image";

async function handleFiles(files) {
  console.log(`Đang xử lý ${files.length} ảnh...`);

  const resized = await resizeImages(files, {
    width: 1200,
    mimeType: MIME_TYPE.webp,
    quality: 0.85,
  });

  console.log(`Hoàn tất! Đã resize ${resized.length} ảnh.`);
  return resized;
}

Ví dụ 3: Upload form

import { resizeImage, MIME_TYPE } from "pica-resize-image";

async function uploadToServer(file) {
  // Resize trước khi upload để giảm băng thông
  const resized = await resizeImage(file, {
    width: 1920,
    mimeType: MIME_TYPE.jpeg,
    quality: 0.85,
  });

  const formData = new FormData();
  formData.append("image", resized);

  await fetch("/api/upload", {
    method: "POST",
    body: formData,
  });
}

Tương thích trình duyệt

• Chrome 61+
• Firefox 60+
• Safari 11+
• Edge 79+

Hỗ trợ HEIC yêu cầu WebAssembly (tất cả trình duyệt hiện đại).

Hiệu suất

| Thao tác | Kích thước file | Thời gian | | -------------- | --------------- | ---------- | | Resize JPG/PNG | < 1MB | 100-300ms | | Resize JPG/PNG | 1-5MB | 500-1500ms | | Resize HEIC | < 1MB | 1-2s | | Resize HEIC | 1-5MB | 2-4s |

TypeScript

Hỗ trợ TypeScript đầy đủ.

import {
  resizeImage,
  resizeImages,
  type ResizeImageOptions,
  type OutputType,
  type MimeType,
} from "pica-resize-image";

Testing

# Chạy tests
npm test

# hoặc
bun test

Giấy phép

MIT

Liên kết

• GitHub
• NPM
• Pica
• heic2any

Công nhận

• Pica - Resize ảnh chất lượng cao trong trình duyệt
• heic2any - Chuyển đổi HEIC sang JPEG