feat(Watermark): add IsPage parameter (#5793)

* refactor: support isPage option

* feat: 支持整页面水印

* refactor: 完善判断空逻辑

* feat: 怎加 is-page 样式

* feat: 增加 IsPage 参数

* doc: 增加文档

* refactor: 增加样式

* feat: 增加报错功能

* test: 更新单元测试

Author: ArgoZhang

src/BootstrapBlazor.Server/Components/Samples/Watermarks.razor

@@ -7,6 +7,9 @@
 
 <DemoBlock Title="@Localizer["WatermarkNormalTitle"]" Introduction="@Localizer["WatermarkNormalIntro"]" Name="Normal">
     <section ignore>
+        @((MarkupString)Localizer["WatermarkDescription"].Value)
+        <Pre>&lt;Layout&gt;&lt;/Layout&gt;
+&lt;Watermark IsPage="true" Text="BootstrapBlazor" FontSize="20" Color="#ddd" Rotate="-45" Gap="40"&gt;&lt;/Watermark&gt;</Pre>
         <div class="row form-inline g-3">
             <div class="col-12 col-sm-6">
                 <BootstrapInputGroup>

src/BootstrapBlazor.Server/Locales/en-US.json

@@ -7017,7 +7017,8 @@
     "WatermarkTitle": "Watermark",
     "WatermarkIntro": "Add specific text or patterns to the page",
     "WatermarkNormalTitle": "Basic usage",
-    "WatermarkNormalIntro": "Use the <code>Text</code> property to set a string to specify the watermark text"
+    "WatermarkNormalIntro": "Use the <code>Text</code> property to set a string to specify the watermark text",
+    "WatermarkDescription": "<p>How to add a watermark globally</p><p>You can add a watermark component to the template page <code>MainLayout</code> and set <code>IsPage=\"true\"</code></p>"
   },
   "BootstrapBlazor.Server.Data.AttributeItem": {
     "Name": "Name",

src/BootstrapBlazor.Server/Locales/zh-CN.json

@@ -7017,7 +7017,8 @@
     "WatermarkTitle": "Watermark 水印组件",
     "WatermarkIntro": "在页面上添加文本或图片等水印信息",
     "WatermarkNormalTitle": "基础用法",
-    "WatermarkNormalIntro": "使用 <code>Text</code> 属性设置一个字符串指定水印内容"
+    "WatermarkNormalIntro": "使用 <code>Text</code> 属性设置一个字符串指定水印内容",
+    "WatermarkDescription": "<p>全局增加水印实现方法</p><p>可以在模板页 <code>MainLayout</code> 中加水印组件并设置 <code>IsPage=\"true\"</code> 即可</p>"
   },
   "BootstrapBlazor.Server.Data.AttributeItem": {
     "Name": "参数",

src/BootstrapBlazor/Components/Watermark/Watermark.razor.cs

@@ -53,7 +53,14 @@ public partial class Watermark
     [Parameter]
     public int? Gap { get; set; }
 
+    /// <summary>
+    /// 获得/设置 是否为整页面水印 默认 false
+    /// </summary>
+    [Parameter]
+    public bool IsPage { get; set; }
+
     private string? ClassString => CssBuilder.Default("bb-watermark")
+        .AddClass("is-page", IsPage)
         .AddClassFromAttributes(AdditionalAttributes)
         .Build();
 
@@ -65,6 +72,11 @@ protected override void OnParametersSet()
         base.OnParametersSet();
 
         Text ??= "BootstrapBlazor";
+
+        if(IsPage && ChildContent is not null)
+        {
+            throw new InvalidOperationException($"{nameof(IsPage)} is true, {nameof(ChildContent)} cannot be set.");
+        }
     }
 
     /// <summary>
@@ -95,6 +107,7 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
         Color,
         Rotate,
         Gap,
-        ZIndex
+        ZIndex,
+        IsPage
     };
 }

src/BootstrapBlazor/Components/Watermark/Watermark.razor.js

@@ -71,7 +71,8 @@ const createWatermark = watermark => {
         fontSize: 16,
         text: 'BootstrapBlazor',
         rotate: -40,
-        color: '#0000004d'
+        color: '#0000004d',
+        zIndex: '9999'
     };
 
     for (const key in options) {
@@ -90,31 +91,40 @@ const createWatermark = watermark => {
     div.style.opacity = '1';
     div.style.position = 'absolute';
     div.style.inset = '0';
-    div.style.zIndex = '9999';
     div.classList.add("bb-watermark-bg");
 
+    if (options.zIndex === void 0) {
+        options.zIndex = defaults.zIndex;
+    }
+    div.style.zIndex = options.zIndex;
+
     const mark = el.querySelector('.bb-watermark-bg');
     if (mark) {
         mark.remove();
     }
-    el.appendChild(div);
 
+    if (bg.isPage) {
+        document.body.appendChild(div);
+    }
+    else {
+        el.appendChild(div);
+    }
     options.bg = bg;
     requestAnimationFrame(() => monitor(watermark));
 }
 
 const monitor = watermark => {
-    const { el, options, ob } = watermark;
+    const { el, options } = watermark;
     if (el === null) {
         return;
     }
 
-    if (el.children.length !== 2) {
+    if (options.isPage === false && el.children.length !== 2) {
         clearWatermark(watermark);
         return;
     }
 
-    const mark = el.children[1];
+    const mark = options.isPage ? el.children[0] : el.children[1];
     if (mark.className !== 'bb-watermark-bg') {
         clearWatermark(watermark);
         return;
@@ -138,7 +148,7 @@ const monitor = watermark => {
         clearWatermark(watermark);
         return;
     }
-    if (zIndex !== '9999') {
+    if (zIndex !== options.zIndex) {
         clearWatermark(watermark);
         return;
     }
@@ -198,6 +208,6 @@ const getWatermark = props => {
     return {
         base64: canvas.toDataURL(),
         size: canvasSize,
-        styleSize: canvasSize / devicePixelRatio,
+        styleSize: canvasSize / devicePixelRatio
     };
 }

src/BootstrapBlazor/Components/Watermark/Watermark.razor.scss

@@ -1,3 +1,10 @@
-.bb-watermark {
+.bb-watermark {
     position: relative;
+
+    &.is-page {
+        position: fixed;
+        inset: 0;
+        z-index: 9999;
+        pointer-events: none;
+    }
 }

src/BootstrapBlazor/wwwroot/modules/utility.js

@@ -801,7 +801,7 @@ const deepMerge = (obj1, obj2, skipNull = true) => {
             }
             else {
                 const value = obj2[key];
-                if (skipNull && value === null) {
+                if (skipNull && (value === null || value === void 0)) {
                     continue;
                 }
                 obj1[key] = obj2[key];

test/UnitTest/Components/WatermarkTest.cs

@@ -22,6 +22,17 @@ public void Watermark_Ok()
         });
         cut.MarkupMatches("<div id:ignore class=\"bb-watermark\"><span>Test</span></div>");
 
-        cut.SetParametersAndRender();
+        var ex = Assert.ThrowsAny<InvalidOperationException>(() => cut.SetParametersAndRender(pb =>
+        {
+            pb.Add(a => a.IsPage, true);
+        }));
+        Assert.Equal($"IsPage is true, ChildContent cannot be set.", ex.Message);
+
+        cut.SetParametersAndRender(pb =>
+        {
+            pb.Add(a => a.IsPage, true);
+            pb.Add(a => a.ChildContent, (RenderFragment?)null);
+        });
+        cut.MarkupMatches("<div id:ignore class=\"bb-watermark is-page\"></div>");
     }
 }