feat(TextArea): add UseShiftEnter parameter (#5351)

* feat: 增加 OnKeyUpAsync 参数

* refactor: 精简代码

* refactor: 重构代码

* doc: 更新示例

* refactor: 移除不需要的 OnKeyDownAsync 回调

* doc: 更新示例文档

* doc: 增加参数说明文档

* doc: 精简代码

* test: 更新单元测试

Co-Authored-By: ice6 <[email protected]>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 3 people

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

@@ -9,59 +9,60 @@
 <DemoBlock Title="@Localizer["TextAreaNormalTitle"]"
            Introduction="@Localizer["TextAreaNormalIntro"]"
            Name="Normal">
-    <label class="form-label mb-3">@Localizer["TextAreaLabel"]</label>
     <Textarea PlaceHolder="@Localizer["TextAreaPlaceHolder"]" rows="4" />
 </DemoBlock>
 
 <DemoBlock Title="@Localizer["TextAreaDisableTitle"]"
            Introduction="@Localizer["TextAreaDisableIntro"]"
            Name="IsDisabled">
-    <label class="form-label mb-3">@Localizer["TextAreaLabel"]</label>
     <Textarea PlaceHolder="@Localizer["TextAreaPlaceHolder"]" rows="4" IsDisabled="true" />
 </DemoBlock>
 
 <DemoBlock Title="@Localizer["TextAreaReadOnlyTitle"]"
            Introduction="@Localizer["TextAreaReadOnlyIntro"]"
            Name="ReadOnly">
-    <label class="form-label mb-3">@Localizer["TextAreaLabel"]</label>
-<Textarea PlaceHolder="@Localizer["TextAreaPlaceHolder"]" rows="4" readonly />
+    <Textarea PlaceHolder="@Localizer["TextAreaPlaceHolder"]" rows="4" readonly />
 </DemoBlock>
 
 <DemoBlock Title="@Localizer["TextAreaHeightTitle"]"
            Introduction="@Localizer["TextAreaHeightIntro"]"
            Name="Rows">
-    <label class="form-label mb-3">@Localizer["TextAreaLabel"]</label>
-
-<Textarea PlaceHolder="@Localizer["TextAreaPlaceHolder"]" rows="4" />
+    <Textarea PlaceHolder="@Localizer["TextAreaPlaceHolder"]" rows="4" />
 </DemoBlock>
 
 <DemoBlock Title="@Localizer["TextAreaBindWayTitle"]"
            Introduction="@Localizer["TextAreaBindWayIntro"]"
            Name="BindValue">
-    <div class="row g-3">
-        <div class="col-12">
-            <label class="form-label">@Localizer["TextAreaLabel"]</label>
-            <Textarea PlaceHolder="@Localizer["TextAreaPlaceHolder"]" rows="4" @bind-Value="@Text"></Textarea>
-        </div>
+    <Textarea PlaceHolder="@Localizer["TextAreaPlaceHolder"]" rows="4" @bind-Value="@Text"></Textarea>
+    <section ignore class="row g-3">
         <div class="col-12">
             <label class="form-label">@Localizer["TextAreaBindWayBindValue"]</label>
             <div class="form-control textarea-demo">@Text</div>
         </div>
-    </div>
+    </section>
 </DemoBlock>
 
 <DemoBlock Title="@Localizer["TextAreaScrollTitle"]"
            Introduction="@Localizer["TextAreaScrollIntro"]"
            Name="IsAutoScroll">
     <Textarea class="mb-3" PlaceHolder="@Localizer["TextAreaPlaceHolder"]" rows="10" @ref="TextareaElement" @bind-Value="@ChatText" IsAutoScroll="IsAutoScroll" />
+    <section ignore>
+        <BootstrapInputGroup>
+            <Button Text="@Localizer[ChatLocalizerName]" OnClick="MockChat" Icon="fa-fw fas fa-comments" />
+            <Button Text="@Localizer["TextAreaScrollToTop"]" OnClick="ScrollToTop" />
+            <Button Text="@Localizer["TextAreaScrollToBottom"]" OnClick="ScrollToBottom" />
+            <Button Text="@Localizer["TextAreaScrollTo"]" OnClick="ScrollTo20" />
+            <Button Text="@($"{Localizer["TextAreaAutoScroll"]}{(IsAutoScroll ? " On":" Off")}" )" OnClick="SwitchAutoScroll" />
+        </BootstrapInputGroup>
+    </section>
+</DemoBlock>
 
-    <BootstrapInputGroup>
-        <Button Text="@Localizer[ChatLocalizerName]" OnClick="MockChat" Icon="fa-fw fas fa-comments" />
-        <Button Text="@Localizer["TextAreaScrollToTop"]" OnClick="ScrollToTop" />
-        <Button Text="@Localizer["TextAreaScrollToBottom"]" OnClick="ScrollToBottom" />
-        <Button Text="@Localizer["TextAreaScrollTo"]" OnClick="ScrollTo20" />
-        <Button Text="@($"{Localizer["TextAreaAutoScroll"]}{(IsAutoScroll ? " On":" Off")}" )" OnClick="SwitchAutoScroll" />
-    </BootstrapInputGroup>
+<DemoBlock Title="@Localizer["TextAreaUseShiftEnterTitle"]"
+           Introduction="@Localizer["TextAreaUseShiftEnterIntro"]"
+           Name="UseShiftEnter">
+    <Textarea rows="4" autocomplete="off" autocorrect="off" spellcheck="false"
+              UseInputEvent="true" UseShiftEnter="true" PlaceHolder="@Localizer["TextAreaUseShiftEnterPlaceHolder"]"
+              @bind-Value="@KeyText"></Textarea>
 </DemoBlock>
 
 <AttributeTable Items="@GetAttributes()" />

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

@@ -15,6 +15,8 @@ public partial class TextAreas
 
     private string? Text { get; set; }
 
+    private string? KeyText { get; set; }
+
     private string? ChatText { get; set; }
 
     private int ScrollValue { get; set; }
@@ -163,11 +165,19 @@ private AttributeItem[] GetAttributes() =>
         },
         new()
         {
-            Name = nameof(BootstrapBlazor.Components.Textarea.IsAutoScroll),
+            Name = nameof(Textarea.IsAutoScroll),
             Description = Localizer["TextAreaAutoScroll"],
             Type = "bool",
             ValueList = "true|false",
             DefaultValue = "false"
+        },
+        new()
+        {
+            Name = nameof(Textarea.UseShiftEnter),
+            Description = Localizer["TextAreaUseShiftEnter"],
+            Type = "bool",
+            ValueList = "true|false",
+            DefaultValue = "false"
         }
     ];
 }

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

@@ -3280,7 +3280,11 @@
     "TextAreaScrollToBottom": "Scroll to bottom",
     "TextAreaScrollToTop": "Scroll to top",
     "TextAreaScrollTo": "Scroll +20",
-    "TextAreaAutoScroll": "Automatic scrolling"
+    "TextAreaAutoScroll": "Automatic scrolling",
+    "TextAreaUseShiftEnterTitle": "Shift Enter",
+    "TextAreaUseShiftEnterIntro": "By setting <code>UseShiftEnter=\"true\"</code> you can start using <kbd>Shift</kbd> + <kbd>Enter</kbd> for line breaks, which is suitable for dialog applications.",
+    "TextAreaUseShiftEnterPlaceHolder": "Please enter some text, Enter sends Shift + Enter line break",
+    "TextAreaUseShiftEnter": "Whether to use Shift + Enter instead of the original Enter key behavior"
   },
   "BootstrapBlazor.Server.Components.Samples.Toggles": {
     "TogglesOnText": "On",

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

@@ -3280,7 +3280,11 @@
     "TextAreaScrollToBottom": "滚动到底部",
     "TextAreaScrollToTop": "滚动到顶部",
     "TextAreaScrollTo": "滚动+20",
-    "TextAreaAutoScroll": "自动滚屏"
+    "TextAreaAutoScroll": "自动滚屏",
+    "TextAreaUseShiftEnterTitle": "Shift Enter",
+    "TextAreaUseShiftEnterIntro": "通过设置 <code>UseShiftEnter=\"true\"</code> 开始使用 <kbd>Shift</kbd> + <kbd>Enter</kbd> 进行换行操作，适用于对话框类应用",
+    "TextAreaUseShiftEnterPlaceHolder": "请输入一些文字，Enter 发送 Shift + Enter 换行",
+    "TextAreaUseShiftEnter": "是否使用 Shift + Enter 代替原回车按键行为"
   },
   "BootstrapBlazor.Server.Components.Samples.Toggles": {
     "TogglesOnText": "开启",

src/BootstrapBlazor/Components/AutoComplete/AutoComplete.razor.js

@@ -1,4 +1,4 @@
-import { debounce, getHeight } from "../../modules/utility.js"
+import { debounce } from "../../modules/utility.js"
 import { handleKeyUp, select, selectAllByFocus, selectAllByEnter } from "../Input/BootstrapInput.razor.js"
 import Data from "../../modules/data.js"
 import EventHandler from "../../modules/event-handler.js"

src/BootstrapBlazor/Components/Textarea/Textarea.razor

@@ -6,4 +6,6 @@
 {
     <BootstrapLabel required="@Required" for="@Id" ShowLabelTooltip="ShowLabelTooltip" Value="@DisplayText" />
 }
-<textarea @attributes="AdditionalAttributes" placeholder="@PlaceHolder" id="@Id" class="@ClassName" disabled="@Disabled" @bind-value="@CurrentValueAsString" @bind-value:event="@EventString" @onblur="OnBlur" data-bb-scroll="@AutoScrollString" @ref="FocusElement"></textarea>
+<textarea @attributes="AdditionalAttributes" placeholder="@PlaceHolder" id="@Id" class="@ClassName" disabled="@Disabled"
+          @bind-value="CurrentValueAsString" @bind-value:event="@EventString" @onblur="@OnBlur"
+          data-bb-shift-enter="@_shiftEnterString" data-bb-scroll="@AutoScrollString" @ref="FocusElement"></textarea>

src/BootstrapBlazor/Components/Textarea/Textarea.razor.cs

@@ -34,11 +34,19 @@ public partial class Textarea
     [Parameter]
     public bool IsAutoScroll { get; set; }
 
+    /// <summary>
+    /// 获得/设置 是否使用 Shift + Enter 代替原回车按键行为 默认为 false
+    /// </summary>
+    [Parameter]
+    public bool UseShiftEnter { get; set; }
+
     /// <summary>
     /// 获得 客户端是否自动滚屏标识
     /// </summary>
     private string? AutoScrollString => IsAutoScroll ? "auto" : null;
 
+    private string? _shiftEnterString => UseShiftEnter ? "true" : null;
+
     /// <summary>
     /// <inheritdoc/>
     /// </summary>

src/BootstrapBlazor/Components/Textarea/Textarea.razor.js

@@ -1,13 +1,24 @@
 import { select, handleKeyUp, selectAllByFocus, selectAllByEnter } from "../Input/BootstrapInput.razor.js"
 import Data from "../../modules/data.js"
+import EventHandler from "../../modules/event-handler.js"
 
 export function init(id) {
+    var el = document.getElementById(id);
     const text = {
         prevMethod: '',
-        element: document.getElementById(id)
+        element: el
     }
 
-    Data.set(id, text)
+    Data.set(id, text);
+    EventHandler.on(el, 'keydown', e => {
+        if (e.key === "Enter" || e.key === "NumpadEnter") {
+            const useShiftEnter = el.getAttribute('data-bb-shift-enter') === 'true';
+            const shiftKey = e.shiftKey;
+            if (!shiftKey || !useShiftEnter) {
+                e.preventDefault();
+            }
+        }
+    });
 }
 
 export function execute(id, method, position) {
@@ -36,7 +47,12 @@ export function execute(id, method, position) {
 }
 
 export function dispose(id) {
-    Data.remove(id)
+    const text = Data.get(id);
+    Data.remove(id);
+
+    if (text) {
+        EventHandler.off(text.element);
+    }
 }
 
 export { select, handleKeyUp, selectAllByFocus, selectAllByEnter }

test/UnitTest/Components/TextareaTest.cs

@@ -76,4 +76,20 @@ public async Task OnBlurAsync_Ok()
         await cut.InvokeAsync(() => { input.Blur(); });
         Assert.True(blur);
     }
+
+    [Fact]
+    public void UseShiftEnter_Ok()
+    {
+        var cut = Context.RenderComponent<Textarea>(builder =>
+        {
+            builder.Add(a => a.UseShiftEnter, true);
+        });
+        cut.Contains("data-bb-shift-enter=\"true\"");
+
+        cut.SetParametersAndRender(pb =>
+        {
+            pb.Add(a => a.UseShiftEnter, false);
+        });
+        cut.DoesNotContain("data-bb-shift-enter=\"true\"");
+    }
 }