Working with Pictures

使用图片

Aspose.Cells FOSS for Java 允许您将图像直接嵌入工作表单元格，并检索或删除现有图片。图片通过每个 Worksheet 所公开的 PictureCollection 进行管理，每个 Picture 对象提供对图像数据、其锚点位置、检测到的图像类型以及其 MIME 内容类型的访问。

概述

每个工作表通过 Worksheet.getPictures() 暴露其图片，该方法返回一个 PictureCollection。您可以从字节数组、InputStream 或文件路径添加图片。该集合提供用于从原始字节检测图像类型、从图像数据解析文件扩展名以及将扩展名映射到 MIME 内容类型的辅助方法。

在工作表上访问图片

通过 Worksheet.getPictures() 检索 PictureCollection。使用 PictureCollection.getCount() 确定存在多少图片。可以通过 PictureCollection.get(index) 使用零基索引访问各个图片。

添加图片

提供了 PictureCollection.add() 的三种重载形式，每种都返回新添加图片的零基索引：

add(upperLeftRow, upperLeftColumn, lowerRightRow, lowerRightColumn, imageData) 来自字节数组
add(upperLeftRow, upperLeftColumn, lowerRightRow, lowerRightColumn, stream) 来自一个 InputStream
add(upperLeftRow, upperLeftColumn, lowerRightRow, lowerRightColumn, fileName) 来自文件路径

// Embed an image from bytes into cells A1:C5
byte[] imgData = Files.readAllBytes(Paths.get("logo.png"));
int idx = ws.getPictures().add(0, 0, 4, 2, imgData);

读取图片属性

当你持有一个 Picture 引用时，读取其锚点位置、原始图像数据、检测到的图像类型和 MIME 内容类型：

PictureCollection pics = ws.getPictures();
for (int i = 0; i < pics.getCount(); i++) {
    Picture p = pics.get(i);
    System.out.printf("Name=%s type=%s anchor=[%d,%d]-[%d,%d]%n",
        p.getName(), p.getImageType(),
        p.getUpperLeftRow(), p.getUpperLeftColumn(),
        p.getLowerRightRow(), p.getLowerRightColumn());
}

从原始字节检测图像类型

使用 PictureCollection.detectImageType(data) 在不先嵌入的情况下确定字节数组的 ImageType 枚举值。

PictureCollection pics = ws.getPictures();
byte[] data = Files.readAllBytes(Paths.get("chart.png"));
ImageType type = pics.detectImageType(data);
String ext  = pics.extensionFromData(data);
String mime = pics.contentTypeFromExtension(ext);
System.out.printf("type=%s ext=%s mime=%s%n", type, ext, mime);

删除图片

使用 PictureCollection.removeAt(index) 根据零基索引删除图片：

ws.getPictures().removeAt(0);

技巧与最佳实践

当您已经在内存中拥有字节时，请使用 add(..., imageData) 重载；使用流重载可以避免完整加载大型文件。
在嵌入之前，调用 PictureCollection.detectImageType(data) 验证图像格式。
锚点行和列是零基索引。
Picture.getName() 返回内部标识符，而不是原始文件名。
在 XLSX 往返过程中，图片会被保留。

常见问题

问题	原因	修复
`getCount()` 在添加后返回 0	流在添加完成之前已关闭	确保 InputStream 已打开且可读取
`ImageType.UNKNOWN` 已返回	不受支持或损坏的图像数据	验证文件是有效的 PNG、JPEG、GIF、BMP 或 TIFF
图片位置看起来不对	行/列索引不正确	对所有锚点参数使用从零开始的索引

FAQ

嵌入时支持哪些图像格式？

The ImageType 枚举包含 PNG、JPEG、GIF、BMP、TIFF 和 EMF。其他格式可能以二进制数据嵌入，但其 ImageType 为 UNKNOWN。

如何获取嵌入图片的文件扩展名？

调用 PictureCollection.extensionFromData(picture.getData()) 并传入图片原始字节。

我可以替换已有图片的图像数据吗？

是的。通过 get(index) 检索 Picture，然后调用 setData(bytes)。

如何按名称查找图片？

使用 getCount() 和 get(index) 遍历所有图片，并比较 Picture.getName()。

将图片保存为其他格式时会被保留吗？

图片保留取决于目标格式。XLSX 循环往返完全受支持。

API Reference 摘要

Picture

方法	返回类型	描述
`getName()`	`String`	图片的内部名称。
`setName(name)`	`void`	设置内部名称。
`getUpperLeftRow()`	`int`	左上锚点的零基行号。
`setUpperLeftRow(row)`	`void`	设置左上角锚点行。
`getUpperLeftColumn()`	`int`	左上锚点的零基列。
`setUpperLeftColumn(col)`	`void`	设置左上角锚点列。
`getLowerRightRow()`	`int`	右下锚点的零基行。
`setLowerRightRow(row)`	`void`	设置右下角锚点行。
`getLowerRightColumn()`	`int`	底部右侧锚点的零基列。
`setLowerRightColumn(col)`	`void`	设置右下角锚点列。
`getImageType()`	`ImageType`	检测到的图像格式枚举值。
`getData()`	`byte[]`	原始图像字节。
`setData(data)`	`void`	替换原始图像字节。
`getContentType()`	`String`	MIME 内容类型字符串。

PictureCollection

方法	返回类型	描述
`getCount()`	`int`	工作表上的图片数量。
`get(index)`	`Picture`	返回零基索引处的图片。
`add(...)`	`int`	嵌入图像；返回其零基索引。
`removeAt(index)`	`void`	删除零基索引处的图片。
`detectImageType(data)`	`ImageType`	从原始字节中检测图像格式。
`extensionFromData(data)`	`String`	返回图像数据的文件扩展名。
`contentTypeFromExtension(ext)`	`String`	返回文件扩展名的 MIME 类型。

另请参阅

Aspose.Cells for Java — Enterprise Documentation