跳转至

13. 图片

本章介绍图片的添加:浮动图片、单元格内嵌图片、高精度锚点,以及打开文件后读回图片。

Warning

浮动图片支持 xlsx / xlsm / xlsb 写出;单元格内嵌图片(InCell)仅支持 xlsx / xlsm。写出到 xls / csv 时图片被丢弃,写出到 xlsb 时 InCell 图片被丢弃,均经 OnDegradation 上报(见第 22 章)。


13.1 图片放置与移动方式

ImagePlacement 决定图片是嵌入单元格还是浮动;ImageMoveMode 控制浮动图片随单元格的移动与缩放行为:

public enum ImagePlacement { InCell, Floating }
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 体系):

ws.AddImage(png, 2, 1, placement: ImagePlacement.InCell);

⚠️ 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 为扩展名
}

输出:

A1 Floating 70 bytes
C1 Floating 70 bytes
A2 InCell 70 bytes

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");

输出:

Banner: A1 Floating 70 bytes
Embed: A1 InCell 70 bytes

浮动图片的效果见[第 12 章](freeze-panes.md)的截图。