doc(ImageCropper): add round image sample code (#4443)

* refactor: 增加 throw 防止 js 导入失败时无提示

* doc: 更新 ImageCropper 示例

* doc: 更新示例

* feat: 增加圆形头像示例

* chroe: bump version 8.1.0

* test: 更新单元测试

* refactor: 重构代码

Author: ArgoZhang

src/BootstrapBlazor.Server/BootstrapBlazor.Server.csproj

@@ -45,7 +45,7 @@
     <PackageReference Include="BootstrapBlazor.Holiday" Version="8.0.1" />
     <PackageReference Include="BootstrapBlazor.Html2Pdf" Version="8.2.1" />
     <PackageReference Include="BootstrapBlazor.IconPark" Version="8.0.4" />
-    <PackageReference Include="BootstrapBlazor.ImageCropper" Version="0.0.4" />
+    <PackageReference Include="BootstrapBlazor.ImageCropper" Version="8.1.0" />
     <PackageReference Include="BootstrapBlazor.Live2DDisplay" Version="8.0.0" />
     <PackageReference Include="BootstrapBlazor.Markdown" Version="8.0.0" />
     <PackageReference Include="BootstrapBlazor.MaterialDesign" Version="8.0.3" />

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

@@ -6,14 +6,35 @@
 <PackageTips Name="BootstrapBlazor.ImageCropper" />
 
 <DemoBlock Title="@Localizer["ImageCropperNormalText"]" Introduction="@Localizer["ImageCropperNormalIntro"]" Name="Normal">
-    <ImageCropper @ref="Cropper" Url="@images[0]" DefaultButton="false" />
+    <ImageCropper @ref="_cropper" Url="@images[0]"></ImageCropper>
     <section ignore>
         <BootstrapInputGroup>
-            <Button Text="OK" OnClick="(async () => Base64 = await Cropper.Crop())" />
-            <Button Text="@Localizer["ImageCropperResetText"]" OnClick="Cropper.Reset" />
+            <Button Text="OK" OnClick="Crop" />
+            <Button Text="@Localizer["ImageCropperResetText"]" OnClick="_cropper.Reset" />
             <Button Text="@Localizer["ImageCropperReplaceText"]" OnClick="OnClickReplace" />
+            <Button Text="@Localizer["ImageCropperRotateText"]" OnClick="Rotate" />
+            <Button Text="@Localizer["ImageCropperEnableText"]" OnClick="_cropper.Enable" />
+            <Button Text="@Localizer["ImageCropperDisabledText"]" OnClick="_cropper.Disable" />
+            <Button Text="@Localizer["ImageCropperClearText"]" OnClick="_cropper.Clear" />
         </BootstrapInputGroup>
-        <Textarea Value="@Base64" rows="3" class="mt-3" />
+        @if (!string.IsNullOrEmpty(_base64String))
+        {
+            <img src="@_base64String" style="width: 240px;" />
+            <Textarea Value="@_base64String" rows="3" class="mt-3" />
+        }
+    </section>
+</DemoBlock>
+
+<DemoBlock Title="@Localizer["ImageCropperNormalText"]" Introduction="@Localizer["ImageCropperNormalIntro"]" Name="Normal">
+    <ImageCropper @ref="_roundCropper" Url="@images[0]" CropperShape="ImageCropperShape.Round" Options="_roundOptions" />
+    <section ignore>
+        <BootstrapInputGroup>
+            <Button Text="OK" OnClick="RoundCrop" />
+        </BootstrapInputGroup>
+        @if (!string.IsNullOrEmpty(_base64String2))
+        {
+            <img src="@_base64String2" style="width: 240px;" />
+        }
     </section>
 </DemoBlock>
 

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

@@ -5,26 +5,42 @@
 namespace BootstrapBlazor.Server.Components.Samples;
 
 /// <summary>
-/// ImageCroppers
+/// ImageCropper 组件示例
 /// </summary>
 public partial class ImageCroppers
 {
+    private ImageCropper _cropper = default!;
 
-    [NotNull]
-    ImageCropper? Cropper { get; set; }
+    private ImageCropper _roundCropper = default!;
 
-    private string[] images = ["./images/picture.jpg", "./images/ImageList2.jpeg"];
+    private readonly string[] images = ["./images/picture.jpg", "./images/ImageList2.jpeg"];
 
     private int index = 0;
 
-    private string? Base64 { get; set; }
+    private string? _base64String;
+
+    private string? _base64String2;
+
+    private ImageCropperOption _roundOptions = new() { IsRound = true, Radius = "50%" };
 
     private async Task OnClickReplace()
     {
         index = index == 0 ? 1 : 0;
-        await Cropper.Replace(images[index]);
+        await _cropper.Replace(images[index]);
+    }
+
+    private async Task Crop()
+    {
+        _base64String = await _cropper.Crop();
     }
 
+    private async Task RoundCrop()
+    {
+        _base64String2 = await _roundCropper.Crop();
+    }
+
+    private Task Rotate() => _cropper.Rotate(90);
+
     /// <summary>
     /// GetAttributes
     /// </summary>
@@ -41,51 +57,35 @@ protected AttributeItem[] GetAttributes() =>
         },
         new()
         {
-            Name = "DefaultButton",
-            Description = Localizer["AttributesImageCropperDefaultButton"],
+            Name = "IsDisabled",
+            Description = Localizer["AttributesImageCropperIsDisabled"],
             Type = "bool",
-            ValueList = "-",
-            DefaultValue = "true"
+            ValueList = "true|false",
+            DefaultValue = "false"
         },
         new()
         {
-            Name = "Preview",
-            Description = Localizer["AttributesImageCropperPreview"],
-            Type = "bool",
-            ValueList = "-",
-            DefaultValue = "true"
-        },
-        new()
-        {
-            Name = "OnResult()",
-            Description = Localizer["AttributesImageCropperOnResult"],
-            Type = "Func",
-            ValueList = "-",
-            DefaultValue = "-"
-        },
-        new()
-        {
-            Name = "OnBase64Result()",
-            Description = Localizer["AttributesImageCropperOnBase64Result"],
-            Type = "Func",
+            Name = "OnCropAsync",
+            Description = Localizer["AttributesImageCropperOnCropAsync"],
+            Type = "Func<ImageCropperResult, Task>",
             ValueList = "-",
             DefaultValue = "-"
         },
         new()
         {
-            Name = "Crop()",
-            Description = Localizer["AttributesImageCropperCrop"],
-            Type = "Task",
+            Name = "Options",
+            Description = Localizer["AttributesImageCropperOptions"],
+            Type = "ImageCropperOption",
             ValueList = "-",
             DefaultValue = "-"
         },
         new()
         {
-            Name = "CropToStream()",
-            Description = Localizer["AttributesImageCropperCropToStream"],
-            Type = "Task",
+            Name = "CropperShape",
+            Description = Localizer["AttributesImageCropperShape"],
+            Type = "ImageCropperShape",
             ValueList = "-",
             DefaultValue = "-"
-        },
+        }
     ];
 }

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

@@ -6499,13 +6499,15 @@
     "ImageCropperNormalIntro": "Url parameter setting image",
     "ImageCropperResetText": "Reset",
     "ImageCropperReplaceText": "Replace",
-    "AttributesImageCropperUrl": "Image URL or Base64 dataurl",
-    "AttributesImageCropperDefaultButton": "Show default button",
-    "AttributesImageCropperPreview": "Show preview after cropping",
-    "AttributesImageCropperOnResult": "Crop result Stream callback method",
-    "AttributesImageCropperOnBase64Result": "Crop result base64 callback method",
-    "AttributesImageCropperCrop": "Crop, return base64, and execute OnResult/OnBase64Result callback",
-    "AttributesImageCropperCropToStream": "Crop, return Stream"
+    "ImageCropperRotateText": "Rotate",
+    "ImageCropperEnableText": "Enable",
+    "ImageCropperDisabledText": "Disabled",
+    "ImageCropperClearText": "Clear",
+    "AttributesImageCropperUrl": "Image Url",
+    "AttributesImageCropperIsDisabled": "Whether the component is disabled",
+    "AttributesImageCropperOnCropAsync": "Crop result callback method",
+    "AttributesImageCropperOptions": "Crop option",
+    "AttributesImageCropperShape": "Crop shape"
   },
   "BootstrapBlazor.Server.Components.Samples.Translators": {
     "TranslatorsTitle": "Azure Translator",

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

@@ -6499,13 +6499,15 @@
     "ImageCropperNormalIntro": "Url 参数设置图片",
     "ImageCropperResetText": "复位",
     "ImageCropperReplaceText": "替换",
-    "AttributesImageCropperUrl": "图片URL 或 Base64 dataurl",
-    "AttributesImageCropperDefaultButton": "显示默认按钮",
-    "AttributesImageCropperPreview": "显示剪裁后预览",
-    "AttributesImageCropperOnResult": "剪裁结果 Stream 回调方法",
-    "AttributesImageCropperOnBase64Result": "剪裁结果 base64 回调方法",
-    "AttributesImageCropperCrop": "剪裁,返回 base64, 并执行 OnResult/OnBase64Result 回调",
-    "AttributesImageCropperCropToStream": "剪裁,返回 Stream"
+    "ImageCropperRotateText": "旋转",
+    "ImageCropperEnableText": "启用",
+    "ImageCropperDisabledText": "禁用",
+    "ImageCropperClearText": "清除",
+    "AttributesImageCropperUrl": "图片地址",
+    "AttributesImageCropperIsDisabled": "是否被禁用",
+    "AttributesImageCropperOnCropAsync": "剪裁结果回调方法",
+    "AttributesImageCropperOptions": "裁剪选项",
+    "AttributesImageCropperShape": "裁剪形状"
   },
   "BootstrapBlazor.Server.Components.Samples.Translators": {
     "TranslatorsTitle": "AzureTranslator 翻译服务",

src/BootstrapBlazor/Extensions/JSModuleExtensions.cs

@@ -25,18 +25,22 @@ public static class JSModuleExtensions
     /// <returns>A <see cref="Task"/><![CDATA[<]]><see cref="JSModule"/><![CDATA[>]]> 模块加载器</returns>
     public static async Task<JSModule> LoadModule(this IJSRuntime jsRuntime, string fileName, string? version = null)
     {
-        JSModule? module = null;
         if (!string.IsNullOrEmpty(version))
         {
             fileName = $"{fileName}?v={version}";
         }
+
+        JSModule? module;
         try
         {
             var jSObjectReference = await jsRuntime.InvokeAsync<IJSObjectReference>(identifier: "import", fileName);
             module = new JSModule(jSObjectReference);
         }
-        catch (Exception) { }
-        return module ?? new JSModule(null);
+        catch (Exception)
+        {
+            throw;
+        }
+        return module;
     }
 
     /// <summary>

test/UnitTest/Extensions/JSModuleExtensionsTest.cs

@@ -19,8 +19,7 @@ public async Task LoadModule_Ok()
     public async Task LoadModule_Exception()
     {
         var jsRuntime = new MockJSRuntime();
-        var module = await jsRuntime.LoadModule("./mock.js", "test");
-        Assert.NotNull(module);
+        await Assert.ThrowsAsync<TaskCanceledException>(() => jsRuntime.LoadModule("./mock.js", "test"));
     }
 
     [Fact]