QuestPFD 图像 (Image)

静态图像

• 此元素可用于在文档中插入图像。
• 默认情况下，Image 会保持图像的原始比例。
• 图片被加载到一个 SkiaSharp.Image 对象中。请注意，所有限制都源于此。例如，可用的图像格式可能因平台而异。
• 您可以使用任何常见的位图格式插入图像，如 JPG、PNG、BMP 等。更多信息

// 可以将图片作为以下之一提供：
// 1) 字节数组
byte[] imageData = File.ReadAllBytes("path/to/logo.png");
container.Image(imageData);

// 2) 文件名
container.Image("path/myFile.png");

// 3) 流
using var stream = new FileStream("logo.png", FileMode.Open);
container.Image(stream);

图像缩放

默认情况下，Image 元素希望使用整个可用宽度，同时保持其比例。您可以使用以下选项更改此行为：

1. FitWidth - 元素会扩展以占据整个可用宽度。默认。

container.Image("path/myFile.png").FitWidth();

2. FitHeight - 元素会扩展以占据整个可用高度。与约束元素配合使用效果良好。

container.Image("path/myFile.png").FitHeight();

3. FitArea - 这是上述两个选项的组合。元素会扩展以占据整个可用区域，同时保持其比例。这意味着有时它会占据整个宽度，有时会占据整个高度。这是最安全的选择。

container.Image("path/myFile.png").FitArea();

4. FitUnproportionally - 元素会调整大小以占据整个可用空间，不保留比例。图像可能会看起来缩放不正确，通常不建议使用。

container.Image("path/myFile.png").FitUnproportionally();

图像压缩

.container.Column(column =>
{
    column.Spacing(10);
    // 低质量 = 输出文件更小
    column.Item().Image("photo.jpg").WithCompressionQuality(ImageCompressionQuality.VeryLow);
    // 高质量/保真度 = 输出文件更大
    column.Item().Image("photo.jpg").WithCompressionQuality(ImageCompressionQuality.High);
});

提示 您可以通过 DocumentSettings 类全局配置图像压缩。了解更多

图像 DPI

.container.Column(column =>
{
    column.Spacing(10);
    // 低分辨率 = 较低分辨率，像素化
    column.Item().Image("photo.jpg").WithRasterDpi(16);
    // 高分辨率 = 更高分辨率
    column.Item().Image("photo.jpg").WithRasterDpi(72);
});

提示 您可以通过 DocumentSettings 类全局配置目标矢量 DPI。了解更多

在文档中重用图像

假设您想生成一个项目列表，每个项目都使用同一张图像。在这种情况下，对于列表中的每个元素，将执行以下步骤：

1. 从文件系统加载文件，
2. 将文件解析为图像，
3. 使用指定设置缩放和压缩图像，
4. 将图像保存为 PDF 文档中的单独资源。

从性能角度看，这些步骤都会产生负面影响，并且最终的 PDF 文件大小也会增加。

.Column(column =>
{
    column.Spacing(15);

    foreach (var i in Enumerable.Range(0, 5))
    {
        column.Item().Row(row =>
        {
            row.AutoItem().Width(24).Image("checkbox.png");
            row.RelativeItem().PaddingLeft(8).AlignMiddle().Text(Placeholders.Label()).FontSize(16);
        });
    }
});

要解决这个问题，您可以加载图像并将其作为共享资源使用：

.container.Column(column =>
{
    column.Spacing(15);
    var image = Image.FromFile("checkbox.png");
    foreach (var i in Enumerable.Range(0, 5))
    {
        column.Item().Row(row =>
        {
            row.AutoItem().Width(24).Image(image);
            row.RelativeItem().PaddingLeft(8).AlignMiddle().Text(Placeholders.Label()).FontSize(16);
        });
    }
});

动态图像

• QuestPDF 提供了灵活的布局，因此很难预测所需的图像分辨率。
• 为了获得最佳的图像清晰度，请使用特定分辨率（或针对 Retina 显示器的分辨率倍数）生成图像。
• 当创建地图/图表时很有用。
• 此元素的行为类似于静态图像。
• 它接受一个函数作为参数，该函数接收可用空间并返回二进制格式的图像。

// 在代码的某个位置
byte[] GenerateImage(Size size)
{
    // 逻辑：根据需要生成并返回具有特定分辨率的图像
}

.Image(GenerateImage);

限制图像大小

PDF 标准使用点来描述尺寸，一英寸有 72 点。Image 使用像素来描述内容，但像素本身没有实际尺寸。只有当您指定 DPI（每英寸点数）时，才能确定像素的大小。QuestPDF 库始终会缩放图像，因为根据图像分辨率确定物理图像大小是没有意义的。

要强制图像占据指定的区域，您可以使用任何约束元素。最简单的两个是 Width 和 Height，例如：

.container.Width(1, Unit.Inch).Image(ImageElement.Image);

请注意，由于 Image 元素默认使用适当的缩放设置，您不需要同时使用 Width 和 Height（图像的比例将得到保留）。

SVG 支持

库支持 SVG 图像。您可以像处理位图图像一样使用它们。

在下面的例子中，图像按需加载和解析：

Document
    .Create(document =>
    {
        document.Page(page =>
        {
            page.Size(PageSizes.A7.Landscape());
            page.Margin(25);

            page.Content()
                .Padding(25)
                .Svg(SvgImage.FromFile("pdf-icon.svg"))
                .FitArea();
        });
    })
    .GeneratePdfAndShow();

您也可以通过一次加载和解析图像来提高性能：

// 在全局或静态上下文中
var image = SvgImage.FromFile("pdf-icon.svg");

Document
    .Create(document =>
    {
        document.Page(page =>
        {
            page.Size(PageSizes.A7.Landscape());
            page.Margin(25);

            page.Content()
                .Padding(25)
                .Svg(image))
                .FitArea();
        });
    })
    .GeneratePdfAndShow();