Java 縮圖生成神器 Thumbnailator 完整應用指南

簡介

Thumbnailator 是一個流暢式 API 的 Java 縮圖生成庫，幾行代碼即可完成縮放、裁剪、旋轉、水印、格式轉換等操作，支援批次處理目錄。Maven 坐標：

<dependency>
    <groupId>net.coobird</groupId>
    <artifactId>thumbnailator</artifactId>
    <version>0.4.20</version>  <!-- 請使用最新版 -->
</dependency>

核心 API 速查與範例

1. 指定尺寸縮放（保持比例）

// 寬≤200 且 高≤300，超過者等比縮小，不超過者不放大
Thumbnails.of("input.jpg")
    .size(200, 300)
    .toFile("output_200x300.jpg");

// 目標尺寸大於原圖 → 不放大（預設行為）
Thumbnails.of("input.jpg")
    .size(2560, 2048)
    .toFile("output_large.jpg");

2. 指定比例縮放

// 縮小至 25%
Thumbnails.of("input.jpg")
    .scale(0.25f)
    .toFile("output_25%.jpg");

// 放大至 110%
Thumbnails.of("input.jpg")
    .scale(1.10f)
    .toFile("output_110%.jpg");

3. 強制指定尺寸（不保持比例，可能變形）

Thumbnails.of("input.jpg")
    .size(200, 200)
    .keepAspectRatio(false)  // 預設 true
    .toFile("output_200x200_stretch.jpg");

4. 旋轉

// 順時針 90°
Thumbnails.of("input.jpg")
    .size(1280, 1024)
    .rotate(90)
    .toFile("output_rot+90.jpg");

// 逆時針 90°
Thumbnails.of("input.jpg")
    .size(1280, 1024)
    .rotate(-90)
    .toFile("output_rot-90.jpg");

5. 加水印

import javax.imageio.ImageIO;
import net.coobird.thumbnailator.geometry.Positions;

// 右下角水印，透明度 0.5，輸出品質 80%
Thumbnails.of("input.jpg")
    .size(1280, 1024)
    .watermark(Positions.BOTTOM_RIGHT,
               ImageIO.read(new File("watermark.png")), 0.5f)
    .outputQuality(0.8f)
    .toFile("output_watermark_br.jpg");

// 置中水印
Thumbnails.of("input.jpg")
    .size(1280, 1024)
    .watermark(Positions.CENTER,
               ImageIO.read(new File("watermark.png")), 0.5f)
    .outputQuality(0.8f)
    .toFile("output_watermark_center.jpg");

6. 裁剪

// 取圖片中心 400x400 區域，再縮放至 200x200
Thumbnails.of("input.jpg")
    .sourceRegion(Positions.CENTER, 400, 400)
    .size(200, 200)
    .keepAspectRatio(false)
    .toFile("output_crop_center.jpg");

// 取右下角 400x400
Thumbnails.of("input.jpg")
    .sourceRegion(Positions.BOTTOM_RIGHT, 400, 400)
    .size(200, 200)
    .keepAspectRatio(false)
    .toFile("output_crop_br.jpg");

// 指定座標 (x=600, y=500, w=400, h=400)
Thumbnails.of("input.jpg")
    .sourceRegion(600, 500, 400, 400)
    .size(200, 200)
    .keepAspectRatio(false)
    .toFile("output_crop_coord.jpg");

7. 格式轉換

Thumbnails.of("input.jpg")
    .size(1280, 1024)
    .outputFormat("png")
    .toFile("output.png");

Thumbnails.of("input.jpg")
    .size(1280, 1024)
    .outputFormat("gif")
    .toFile("output.gif");

8. 輸出到 OutputStream

try (OutputStream os = new FileOutputStream("output_stream.png")) {
    Thumbnails.of("input.jpg")
        .size(1280, 1024)
        .toOutputStream(os);
}

9. 輸出到 BufferedImage（記憶體中後續處理）

BufferedImage thumb = Thumbnails.of("input.jpg")
    .size(1280, 1024)
    .asBufferedImage();

ImageIO.write(thumb, "jpg", new File("output_buffered.jpg"));

批次處理整個目錄

// 將目錄下所有圖片縮放至寬 800，輸出到另一目錄，保留原檔名
Thumbnails.of(new File("input_dir"))
    .size(800, 800)
    .outputFormat("jpg")
    .toFiles(new File("output_dir"), Rename.NO_CHANGE);  // 或 Rename.PREFIX_DOT_THUMBNAIL

進階技巧與注意事項

常見替代方案對比