pica-resize-image/README.vi.md

A resize image plugin for Pica

# pica-resize-image

[![npm version](https://img.shields.io/npm/v/pica-resize-image.svg)](https://www.npmjs.com/package/pica-resize-image)
[![npm downloads](https://img.shields.io/npm/dm/pica-resize-image.svg)](https://www.npmjs.com/package/pica-resize-image)
[![license](https://img.shields.io/npm/l/pica-resize-image.svg)](https://github.com/theanh-it/pica-resize-image/blob/main/LICENSE)

**Phiên bản: 0.0.6**

**[English](./README.md) | [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

```bash
npm install pica-resize-image pica heic2any
```

hoặc

```bash
yarn add pica-resize-image pica heic2any
```

hoặc

```bash
bun add pica-resize-image pica heic2any
```

## Cách sử dụng

### Sử dụng cơ bản

```typescript
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)

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

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

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

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

```typescript
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

```typescript
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

```typescript
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

```typescript
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.

```typescript
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`

```typescript
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ố

```typescript
// 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

```html
<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

```javascript
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

```javascript
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 đủ.

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

## Testing

```bash
# Chạy tests
npm test

# hoặc
bun test
```

## Giấy phép

MIT

## Liên kết

- [GitHub](https://github.com/theanh-it/pica-resize-image)
- [NPM](https://www.npmjs.com/package/pica-resize-image)
- [Pica](https://github.com/nodeca/pica)
- [heic2any](https://github.com/alexcorvi/heic2any)

## Công nhận

- [Pica](https://github.com/nodeca/pica) - Resize ảnh chất lượng cao trong trình duyệt
- [heic2any](https://github.com/alexcorvi/heic2any) - Chuyển đổi HEIC sang JPEG