13. 图片¶
本章介绍图片的添加:浮动图片、单元格内嵌图片、高精度锚点,以及打开文件后读回图片。
Warning
浮动图片支持 xlsx / xlsm / xlsb 写出;单元格内嵌图片(InCell)仅支持 xlsx / xlsm。写出到 xls / csv 时图片被丢弃,写出到 xlsb 时 InCell 图片被丢弃,均经 OnDegradation 上报(见第 22 章)。
13.1 图片放置与移动方式¶
ImagePlacement 决定图片是嵌入单元格还是浮动;ImageMoveMode 控制浮动图片随单元格的移动与缩放行为:
public enum ImageMoveMode
{
MoveAndSizeWithCells, // 随单元格移动并缩放
MoveButDontSizeWithCells, // 随单元格移动但不缩放(默认)
FixedPosition, // 固定位置
}
ImagePlacement 用于 AddImage 的 placement 参数(见 13.2 / 13.3),ImageMoveMode 用于 ImageAnchor.MoveMode(见 13.4)。
13.2 浮动图片(Floating)¶
以 row / column 左上角为锚点,默认按图片原始尺寸显示:
var ws = Excel.Create().Worksheets["Sheet1"];
byte[] png = File.ReadAllBytes("logo.png");
ws.AddImage(png, 1, 1); // 锚点 A1,原始尺寸
ws.AddImage(png, 1, 3, 120, 60); // 指定显示尺寸(像素)
AddImage(row / column 重载)参数:
| 参数 | 类型 | 说明 |
|---|---|---|
data |
byte[] |
图片二进制(PNG / JPEG / GIF / BMP) |
row / column |
int |
1 基左上角锚点行列 |
widthPx / heightPx |
double? |
显示尺寸(像素),null = 图片原始尺寸 |
placement |
ImagePlacement |
Floating / InCell,默认 Floating |
extension |
string? |
图片扩展名(可选),null 时按 magic bytes 探测 |
name |
string? |
图片名称(可选) |
13.3 单元格内嵌图片(InCell)¶
Excel 365 InCell 图片(richData 体系):
⚠️ InCell 图片基于 Excel 365 richData 体系(写回为 richData 部件),老版本 Excel 可能无法识别。
13.4 高精度锚点 ImageAnchor¶
ImageAnchor 提供左上单元格 + EMU 偏移 + 显示尺寸 + 移动方式,写回时优先于 Row / Column:
var anchor = new ImageAnchor
{
TopLeftCell = "B2",
TopLeftOffsetX = 100, // EMU 偏移(1px ≈ 9525)
TopLeftOffsetY = 50,
WidthPixels = 200,
HeightPixels = 100,
MoveMode = ImageMoveMode.MoveAndSizeWithCells,
};
ws.AddImage(png, anchor, name: "Chart", altText: "季度图表");
ImageAnchor 关键成员:
| 参数 | 类型 | 说明 |
|---|---|---|
TopLeftCell |
string |
左上单元格 A1 引用 |
TopLeftOffsetX / TopLeftOffsetY |
int |
左上偏移(EMU,1px ≈ 9525) |
WidthPixels / HeightPixels |
double |
显示尺寸(像素) |
MoveMode |
ImageMoveMode |
移动 / 缩放方式,默认 MoveButDontSizeWithCells |
AddImage(anchor 重载)参数:
| 参数 | 类型 | 说明 |
|---|---|---|
data |
byte[] |
图片二进制 |
anchor |
ImageAnchor |
高精度锚点 |
extension |
string? |
图片扩展名(可选),null 时按 magic bytes 探测 |
name |
string? |
图片名称(可选) |
altText |
string? |
无障碍替换文本(可选) |
⚠️
ImageAnchor仅对 Floating 图片生效;InCell 请用 row / column 重载(Anchor会被忽略)。
13.5 图片读回¶
打开含图片的文件后,Worksheet.Images 自动填充:
var opened = Excel.Open("with_images.xlsx");
foreach (var img in opened.Worksheets[0].Images)
{
Console.WriteLine($"{img.CellAddress} {img.Placement} {img.Data.Length} bytes");
// img.Data 为原始图片字节,img.Row/Column 为锚点,img.Extension 为扩展名
}
输出:
WorksheetImage 关键成员:Data(字节)、Extension、Row / Column(1 基锚点)、Placement、WidthPx / HeightPx、Name、Anchor、AltText、CellAddress(只读 A1 引用)。
⚠️ 打开文件时
Worksheet.Images会回填浮动与单元格内嵌图片(浮动 drawing 与 richData 均支持读回)。
Warning
回填的浮动图片仅供查看(字节、锚点、尺寸),修改其属性不会影响保存结果:图片本身随绘图部件原样透传,写入器不重建这部分内容。
调用方经 AddImage 新增的图片不受此限制,正常写出并并入既有绘图部件。
13.6 多 Sheet 混合使用¶
不同工作表可分别使用 Floating 与 InCell 放置,互不干扰:
byte[] img = File.ReadAllBytes("logo.png");
var wb = Excel.Create();
var wsBanner = wb.Worksheets[0];
wsBanner.Name = "Banner";
wsBanner.AddImage(img, 1, 1); // 浮动图片
var wsEmbed = wb.Worksheets.Add("Embed");
wsEmbed.AddImage(img, 1, 1, placement: ImagePlacement.InCell); // 单元格内嵌图片
wb.SaveAs("multi_images.xlsx");
// 读回验证(浮动与内嵌图片都会回填)
var opened = Excel.Open("multi_images.xlsx");
foreach (var s in opened.Worksheets)
foreach (var im in s.Images)
Console.WriteLine($"{s.Name}: {im.CellAddress} {im.Placement} {im.Data.Length} bytes");
输出: