Images

Images

本页介绍了在页面上放置光栅图像、检查文档中已嵌入的图像以及减小图像大小的方式。有关将 page 到图像，请参见 Conversion.

嵌入图像

Page.AddImage() 将 JPEG、PNG、BMP 或 TIFF 图像字节放置在页面上的像素精确矩形中。

// Source is 1280x1014; scaled to 60% of the page width, aspect preserved.
const srcW = 1280;
const srcH = 1014;
const imgW = pageWidth(page) * 0.6;
const imgH = (imgW * srcH) / srcW;
const x = (pageWidth(page) - imgW) / 2;
const y = (pageHeight(page) - imgH) / 2;

page.AddImage(imageBytes, [x, y, x + imgW, y + imgH]);

AddImageOptions 接受 opacity，当无法从字节中嗅探时需要显式的 format，一个 tag（在标记文档中用于附加图像的 StructElement），以及用于可选内容的 layer。

检查嵌入的图像

Page.Images 将页面上已有的每个图像列为 ImageInfo[]，且不解码任何像素数据——每个条目公开 Width、Height、Bits、ColorSpace 和 Filter。对 ImageInfo 调用 Decode() 可获取其原始样本字节，调用 Replace() 可就地替换为新的图像数据，或调用 Remove() 将其从页面中删除。

for (const img of page.Images) {
  console.log(img.Width, img.Height, img.ColorSpace, img.Filter);
}

优化图像

Document.Optimize() 在整个文档中减小文件大小；传递一个 images 选项（OptimizeImageOptions，以及 dpi 和 quality 字段）以在同一次处理过程中对嵌入的图像进行降采样和重新编码。

const report = doc.Optimize({ images: { dpi: 150, quality: 80 } });

技巧与最佳实践

• Page.Images 仅读取元数据 —— 如果您只需要尺寸或色彩空间，则无需预先使用 Decode() 解码每张图像的完整像素数据。
• 当源字节来自没有可靠文件扩展名可供检测的流或缓冲区时，请在 AddImageOptions 中传递显式的 format。
• 使用 Document.Optimize({ images: { dpi, quality } }) 来压缩包含大量图像的文档，而不是手动解码并重新添加每张图像。
• Page.AddImage() 的矩形直接设定放置尺寸 —— 将目标矩形按源图像的宽高比进行缩放，以避免拉伸。

常见问题

FAQ

如何在页面上放置图像？

调用 page.AddImage(imageBytes, rect)，其中 rect 是页面空间点中的一个 [x0, y0, x1, y1] 矩形。

如何在不解码的情况下列出页面上已有的图像？

读取 page.Images —— 一个 ImageInfo[]，为每个图像公开 Width、Height、ColorSpace 和 Filter，而无需解码像素数据。

我可以通过压缩图像来减小文档的文件大小吗？

是的——调用 Document.Optimize({ images: { dpi, quality } })，它在文档范围的优化过程中对嵌入的图像进行降采样和重新编码。

将图像嵌入与将页面渲染为图像有什么区别？

Page.AddImage() 将光栅图像字节放置在现有页面上。 Page.ToImage() （见 Conversion) 执行相反的操作——将整个页面渲染为 PNG 字节。

API Reference 摘要

另请参阅

• Aspose.PDF — Enterprise Documentation