feat(Html2Pdf): add PaperFormat parameter (#7036)

* refactor: 增加 PdfOptions 配置项

* doc: 更新示例增加 Options 配置

* chore: bump version 9.11.5-beta11

* chore: 更新 Html2Pdf 依赖包

* test: 增加单元测试

Author: ArgoZhang

src/BootstrapBlazor.Server/BootstrapBlazor.Server.csproj

@@ -44,7 +44,7 @@
     <PackageReference Include="BootstrapBlazor.Gantt" Version="9.0.2" />
     <PackageReference Include="BootstrapBlazor.Holiday" Version="9.0.1" />
     <PackageReference Include="BootstrapBlazor.Html2Image" Version="9.0.2" />
-    <PackageReference Include="BootstrapBlazor.Html2Pdf" Version="9.0.6-beta01" />
+    <PackageReference Include="BootstrapBlazor.Html2Pdf" Version="10.0.0-rc.2.1.2" />
     <PackageReference Include="BootstrapBlazor.IconPark" Version="9.0.3" />
     <PackageReference Include="BootstrapBlazor.ImageCropper" Version="9.0.3" />
     <PackageReference Include="BootstrapBlazor.IP2Region" Version="9.0.4" />

src/BootstrapBlazor.Server/Components/Samples/Html2Pdfs.razor.cs

@@ -86,7 +86,10 @@ private async Task OnExportAsync()
                 """;
 
             // 增加网页所需样式表文件
-            using var stream = await Html2PdfService.PdfStreamFromHtmlAsync(htmlString, [$"{NavigationManager.BaseUri}_content/BootstrapBlazor/css/bootstrap.blazor.bundle.min.css"]);
+            using var stream = await Html2PdfService.PdfStreamFromHtmlAsync(htmlString, [$"{NavigationManager.BaseUri}_content/BootstrapBlazor/css/bootstrap.blazor.bundle.min.css"], options: new PdfOptions()
+            {
+                Format = PaperFormat.A4
+            });
 
             // 下载 Pdf 文件
             await DownloadService.DownloadFromStreamAsync($"table-{DateTime.Now:HHmmss}.pdf", stream);

src/BootstrapBlazor/BootstrapBlazor.csproj

@@ -1,11 +1,11 @@
 <Project Sdk="Microsoft.NET.Sdk.Razor">
 
   <PropertyGroup Condition="'$(VisualStudioVersion)' == '17.0'">
-    <Version>9.11.5-beta10</Version>
+    <Version>9.11.5-beta11</Version>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(VisualStudioVersion)' == '18.0'">
-    <Version>10.0.0-rc.2.1.9</Version>
+    <Version>10.0.0-rc.2.1.10</Version>
   </PropertyGroup>
 
   <ItemGroup>

src/BootstrapBlazor/Options/MarginOptions.cs

@@ -0,0 +1,33 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License
+// See the LICENSE file in the project root for more information.
+// Maintainer: Argo Zhang([email protected]) Website: https://www.blazor.zone
+
+namespace BootstrapBlazor.Components;
+
+/// <summary>
+/// 页面边距选项
+/// </summary>
+[ExcludeFromCodeCoverage]
+public record MarginOptions
+{
+    /// <summary>
+    /// Top margin, accepts values labeled with units.
+    /// </summary>
+    public object? Top { get; set; }
+
+    /// <summary>
+    /// Left margin, accepts values labeled with units.
+    /// </summary>
+    public object? Left { get; set; }
+
+    /// <summary>
+    /// Bottom margin, accepts values labeled with units.
+    /// </summary>
+    public object? Bottom { get; set; }
+
+    /// <summary>
+    /// Right margin, accepts values labeled with units.
+    /// </summary>
+    public object? Right { get; set; }
+}

src/BootstrapBlazor/Options/PaperFormat.cs

@@ -0,0 +1,89 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License
+// See the LICENSE file in the project root for more information.
+// Maintainer: Argo Zhang([email protected]) Website: https://www.blazor.zone
+
+namespace BootstrapBlazor.Components;
+
+/// <summary>
+/// 纸张规格配置类
+/// </summary>
+[ExcludeFromCodeCoverage]
+public record PaperFormat
+{
+    /// <summary>
+    /// 
+    /// </summary>
+    public static PaperFormat Letter => new(8.5m, 11m);
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public static PaperFormat Legal => new(8.5m, 14m);
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public static PaperFormat Tabloid => new(11m, 17m);
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public static PaperFormat Ledger => new(17m, 11m);
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public static PaperFormat A0 => new(33.1102m, 46.811m);
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public static PaperFormat A1 => new(23.3858m, 33.1102m);
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public static PaperFormat A2 => new(16.5354m, 23.3858m);
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public static PaperFormat A3 => new(11.6929m, 16.5354m);
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public static PaperFormat A4 => new(8.2677m, 11.6929m);
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public static PaperFormat A5 => new(5.8268m, 8.2677m);
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public static PaperFormat A6 => new(4.1339m, 5.8268m);
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public decimal Width { get; set; }
+
+    /// <summary>
+    /// 
+    /// </summary>
+    public decimal Height { get; set; }
+
+    /// <summary>
+    /// 
+    /// </summary>
+    /// <param name="width"></param>
+    /// <param name="height"></param>
+    public PaperFormat(decimal width, decimal height)
+    {
+        Width = width;
+        Height = height;
+    }
+}

src/BootstrapBlazor/Options/PdfOptions.cs

@@ -14,4 +14,29 @@ public class PdfOptions
     /// 获得/设置 是否横向打印 默认 false
     /// </summary>
     public bool Landscape { get; set; }
+
+    /// <summary>
+    /// 获得/设置 是否打印背景色 默认 false
+    /// </summary>
+    public bool PrintBackground { get; set; }
+
+    /// <summary>
+    /// 获得/设置 纸张格式 默认 A4
+    /// </summary>
+    public PaperFormat Format { get; set; } = PaperFormat.A4;
+
+    /// <summary>
+    /// 获得/设置 是否显示页眉页脚 默认 false
+    /// </summary>
+    public bool DisplayHeaderFooter { get; set; }
+
+    /// <summary>
+    /// 获得/设置 放大比例 默认 1 取值 0.1 到 2 之间
+    /// </summary>
+    public decimal Scale { get; set; } = 1;
+
+    /// <summary>
+    /// 获得/设置 页面边距 默认 none
+    /// </summary>
+    public MarginOptions MarginOptions { get; set; } = new();
 }

test/UnitTest/Options/PdfOptionsTest.cs

@@ -0,0 +1,38 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License
+// See the LICENSE file in the project root for more information.
+// Maintainer: Argo Zhang([email protected]) Website: https://www.blazor.zone
+
+namespace UnitTest.Options;
+
+public class PdfOptionsTest
+{
+    [Fact]
+    public void Test_PdfOptions_Ok()
+    {
+        var options = new PdfOptions()
+        {
+            Scale = 1.0m,
+            DisplayHeaderFooter = true,
+            PrintBackground = true,
+            Landscape = true,
+            Format = PaperFormat.A1,
+            MarginOptions = new MarginOptions()
+            {
+                Top = "10mm",
+                Bottom = "10mm",
+                Left = "10mm",
+                Right = "10mm"
+            }
+        };
+        Assert.Equal(1.0m, options.Scale);
+        Assert.True(options.DisplayHeaderFooter);
+        Assert.True(options.PrintBackground);
+        Assert.True(options.Landscape);
+        Assert.Equal(PaperFormat.A1, options.Format);
+        Assert.Equal("10mm", options.MarginOptions.Top);
+        Assert.Equal("10mm", options.MarginOptions.Bottom);
+        Assert.Equal("10mm", options.MarginOptions.Left);
+        Assert.Equal("10mm", options.MarginOptions.Right);
+    }
+}