ant-design-blazor 文本域字数提示实战:TextArea ShowCount 完整指南

原创2026-10-11 16:02:551,934 阅读
文章标签:UI组件前端

ant-design-blazor 文本域字数提示实战:TextArea ShowCount 完整指南

在表单录入、评论框、消息输入等场景中,实时向用户展示当前已输入的字数与最大长度限制,能显著改善输入体验。ant-design-blazor 的 TextArea 组件通过 ShowCount 参数即可开箱即用地实现这一能力,且无需引入任何第三方库或手写 JS 统计逻辑。本文以仓库中的官方演示 CharCount 示例 为切入点,深入讲解 ShowCount 的参数语义、底层实现原理、样式机制与测试验证方式,帮助你掌握在真实项目中正确使用字数提示的方法。

一、快速上手:三行代码实现字数提示

仓库中的官方演示 CharCount.razor 给出了最精简的用法,全部代码如下:

<TextArea ShowCount MaxLength=100 OnChange="onChange" />

@code{

    private void onChange(string value)
    {
        Console.WriteLine("onChange =>" + value);
    }
}

其对应文档 CharCount.md 的描述只有一句话:展示字数提示。但要真正理解这行组件标记的含义,需要拆解三个关键点:

  1. ShowCount:开关参数,设为 true 后组件才会渲染字数统计区域;
  2. MaxLength=100:最大长度限制,同时承担两个职责——通过原生 maxlength 属性限制用户输入,并为字数统计提供“分母”;
  3. OnChange:内容变化回调,参数为 string 类型的当前值,这里仅打印到控制台做演示。

该示例对应的 bUnit 测试位于 tests/AntDesign.Tests/Input/TextAreaTests.razor 中的 TextArea_ShowCount_shows_initial_value,它验证了渲染结果:当初始值 value = "0123456789"、MaxLength=100 时,包裹层 div 的 data-count 属性值为 10 / 100——即“已输入 10 个字符,上限 100”。

二、ShowCount 参数语义:来自 Input 基类的通用能力

从组件继承关系看,TextArea 的完整声明链是 TextArea : Input<string>,而 Input<TValue> 继承自 AntInputComponentBase<TValue>。ShowCount 参数定义在基类 components/input/Input.cs 中:

/// <summary>
/// Show count of characters in the input
/// </summary>
[Parameter]
public bool ShowCount { get; set; }

也就是说,ShowCount 是 Input 家族(Input、TextArea、Search、InputPassword 等)共有的参数,官方 API 文档 index.zh-CN.md 对 TextArea 的 ShowCount 说明为:

Property Description Type Default Version
ShowCount 是否显示文本计数。需要设置 MaxLength 属性 boolean false 0.9

注意官方文档特别强调“需要设置 MaxLength 属性”。这句话并非硬性约束——即便不设置 MaxLength,字数统计依然会工作,只是只显示当前字数、不显示上限(详见下文测试 TextArea_ShowCount_without_maxlength)。但实践中强烈建议同时设置,因为:

  • 只显示当前字数时,用户无法感知剩余可输入量,提示价值大打折扣;
  • MaxLength 同时映射为原生 maxlength 属性,从 HTML 层面阻止超长输入,二者配合才能形成“输入拦截 + 视觉反馈”的完整闭环。

三、字数统计的生成逻辑:Count 属性的完整规则

字数统计的核心逻辑在 components/input/TextArea.razor.cs 中,一行代码即可概括:

private string Count => $"{_inputString?.Length ?? 0}{(MaxLength > 0 ? $" / {MaxLength}" : "")}";

这条表达式决定了最终展示文本的三种形态:

条件 展示结果 示例
未设置 MaxLength(MaxLength <= 0,默认值为 -1) 仅当前字数 10
设置了 MaxLength 且大于 0 当前字数 + 分隔符 + 上限 10 / 100
值为 null 按 0 计 0 / 100

其中 _inputString 是组件内部维护的实时输入字符串,它在 OnInputAsync(每次 oninput 事件)和 OnCurrentValueChange 中被同步更新。MaxLength 参数定义于 Input<TValue> 基类,默认值为 -1(表示无限制):

[Parameter]
public int MaxLength { get; set; } = -1;

同时,基类的 SetAttributes() 方法会在 MaxLength >= 0 时将其写入渲染属性集合,最终落到原生 maxlength 属性上:

if (MaxLength >= 0)
{
    Attributes.TryAdd("maxlength", MaxLength);
}

这一行为也有专门的测试 TextArea_MaxLength_Adds_Attribute_To_Textarea 与 TextArea_MaxLength_Adds_Attribute_To_Textarea_After_Initial_Render 进行验证,后者还确认了运行期间动态调整 MaxLength 时属性会同步更新。

四、底层渲染结构剖析:字数统计落在哪里

理解了计算规则后,再看它如何渲染到页面上。TextArea 的渲染模板在 components/input/TextArea.razor 中,关键分支条件是:

@if (Suffix != null || AllowClear || FormItem?.FeedbackIcon != null || ShowCount)
{
    <div class="@ClassMapper.Class" style="@Style" data-count="@Count">
        <span class="@_warpperClassMapper.Class">
            <textarea @ref="Ref" class="@_textareaClassMapper.Class" @attributes="attributes"
                      @onchange:stopPropagation="@StopPropagation"
                      @onblur:stopPropagation="@StopPropagation" />
            @if (AllowClear) { @ClearIcon }
        </span>
        <span class="ant-input-textarea-suffix">
            @if (Suffix != null) { @Suffix }
            @if (FormItem?.FeedbackIcon != null) { @FormItem.FeedbackIcon }
        </span>
    </div>
}
else
{
    <textarea @ref="Ref" class="@ClassMapper.OriginalClass @_textareaClassMapper.Class" @attributes="attributes" ... />
}

这里揭示了三个重要的实现细节:

1. 统计文本不直接渲染为 DOM 文本,而是放在 data-count 属性中。 外层 div 上的 data-count="@Count" 会被后续 LESS 样式通过 content: attr(data-count) 读取并显示。这种做法的好处是字数文本与布局彻底解耦,样式层完全掌控展示方式。

2. ShowCount 是外层包裹结构(wrapper)是否出现的触发条件之一。 一旦开启 ShowCount,组件会从“裸 textarea”切换为“div 包裹 + 内层 span 包裹”的多层结构,CSS 类也随之变化。在 TextArea.razor.cs 的 OnInitialized 中,类映射器会为计数场景追加专门样式类:

ClassMapper
    .Add("ant-input-textarea ")
    .If("ant-input-textarea-show-count", () => ShowCount)
    .If("ant-input-textarea-in-form-item", () => FormItem != null)
    .If("ant-input-textarea-has-feedback", () => FormItem?.HasFeedback == true)
    ...

3. 计数与 Suffix、反馈图标共用一个 ant-input-textarea-suffix 容器。 开启 ShowCount 后若同时设置了 Suffix 或表单校验反馈图标(FormItem.FeedbackIcon),它们都会出现在这个后缀容器内,样式上由绝对定位控制位置。

五、样式实现:data-count 如何变成可见文字

字数提示的最终显示依赖 LESS 样式。核心样式位于 components/input/style/index.less:

&-textarea-show-count {
  > .@{input-prefix-cls} {
    height: 100%;
  }

  &::after {
    float: right;
    color: @text-color-secondary;
    white-space: nowrap;
    content: attr(data-count);
    pointer-events: none;
  }

  &.@{input-prefix-cls}-textarea-in-form-item {
    &::after {
      margin-bottom: -22px;
    }
  }
}

要点解读:

  • 使用 ::after 伪元素承载计数文字,content: attr(data-count) 从 div 的 data-count 属性取值——这就是上一节提到的“属性驱动显示”机制;
  • float: right 使计数靠右对齐,位于文本域右下角;
  • pointer-events: none 保证计数文本不会拦截鼠标事件,不影响用户选中文本或点击操作;
  • 当 TextArea 处于表单项中时(类名含 ant-input-textarea-in-form-item),通过负 margin 修正计数位置,避免与表单项的校验信息布局冲突;
  • 颜色使用主题变量 @text-color-secondary(次要文本色),视觉上弱于正文,符合辅助提示的定位。

此外,rtl.less 中还针对 RTL(从右向左)布局做了适配:

&-rtl&-show-count::after {
  ...
}

如果你的应用开启了 RTL 方向(如阿拉伯语、希伯来语界面),字数统计会自动切换到左侧对齐,无需额外处理。

六、测试验证:用 bUnit 锁住字数统计行为

仓库用 bUnit 测试对字数统计的各种边界情况做了回归保护,全部位于 tests/AntDesign.Tests/Input/TextAreaTests.razor,直接对应 CharCount 演示的功能点。这些测试本身就是理解行为契约的最佳文档:

测试方法 验证行为
TextArea_ShowCount_shows_initial_value 初始值 + MaxLength 时,data-count 为 "10 / 100"
TextArea_ShowCount_without_maxlength 不设 MaxLength 时,data-count 仅显示 "10"
TextArea_ShowCount_increase 输入新内容后计数实时增长,从 0 / 100 变为 8 / 100
TextArea_Wrapper_Disabled ShowCount 与 Disabled 同用时,wrapper 正确加上禁用样式类
TextArea_MaxLength_Adds_Attribute_To_Textarea MaxLength 正确映射到原生 maxlength 属性

例如 TextArea_ShowCount_increase 的完整写法:

[Fact]
public void TextArea_ShowCount_increase()
{
    //Arrange
    string value = "";
    string newValue = "newValue";
    var cut = Render<AntDesign.TextArea>(
        @<AntDesign.TextArea ShowCount MaxLength=100 Value=@value DebounceMilliseconds="0" />);

    //Act
    cut.Find("textarea").Input(newValue);
    cut.Find("textarea").KeyUp(String.Empty);
    cut.Render();
    var divWrapper = cut.Find("div");
    var attribute = divWrapper.GetAttribute("data-count");

    //Assert
    attribute.Should().Be($"{newValue.Length} / 100");
}

这段测试还透露了一个实战细节:DebounceMilliseconds="0" 用于关闭防抖,使每次按键立即更新绑定值,从而保证测试(以及需要实时计数的业务场景)中计数能即时刷新。默认情况下 DebounceMilliseconds 为 250ms,连续输入时计数更新会稍有延迟。

七、扩展到 Input 普通输入框:同一参数,两套渲染

ShowCount 不仅适用于 TextArea,也适用于普通单行 Input。仓库演示 ShowCount.razor 同时展示了两种形态:

<div>
    <AntDesign.Input TValue="string" ShowCount MaxLength="20" OnChange="OnChange" AllowClear Suffix="@("RMB".ToRenderFragment())" />
    <br />
    <br />
    <TextArea ShowCount MaxLength="100" OnChange="OnChange" />
</div>

对于单行 Input,计数文本通过基类 Input.cs 中的 Counter 渲染片段(RenderFragment)生成,以 ant-input-show-count-suffix 类名的 span 元素输出:

protected RenderFragment Counter => builder =>
{
    string counterCls = "ant-input-show-count-suffix";
    if (Suffix != null)
    {
        counterCls += " ant-input-show-count-has-suffix";
    }
    builder.AddMarkupContent(111, $@"<span class=""{counterCls}"">{CountString}</span>");
};

而 CountString 的计算逻辑与 TextArea 中的 Count 完全一致:

private string CountString => $"{_inputString?.Length ?? 0}{(MaxLength > 0 ? $" / {MaxLength}" : "")}";

两者差异仅在于:

  • Input(单行):计数作为 span 元素渲染在 ant-input-suffix 后缀容器内,与 AllowClear 的清除图标、Suffix 内容并列;
  • TextArea(多行):计数写入外层 div 的 data-count 属性,由 ::after 伪元素呈现。

八、实战组合建议与注意事项

基于以上源码分析,在实际项目中组合使用 ShowCount 时有几点值得注意:

  1. 务必搭配 MaxLength 使用。虽然组件允许单独开启 ShowCount,但只有同时设置 MaxLength,原生输入限制与“当前/上限”的完整提示才同时生效,这也是官方 API 文档的推荐用法。

  2. 初始值也会被计入统计。Count 属性基于 _inputString 实时计算,无论是双向绑定(@bind-Value)传入的初始值、DefaultValue,还是用户后续输入,都会即时反映在计数上,测试 TextArea_ShowCount_shows_initial_value 已覆盖此场景。

  3. 与表单项(FormItem)协同。ShowCount 开启后组件会进入 wrapper 渲染分支,此时与 FormItem 的校验状态、反馈图标共存于同一容器;样式层已针对表单项场景做了专门的位置修正,但若自定义样式时需留意 ant-input-textarea-show-count 与 ant-input-textarea-in-form-item 两个类同时存在的情况。

  4. RTL 布局自动适配。国际化项目无需额外代码,rtl.less 中的规则会自动调整计数对齐方向。

  5. 计数文本不可交互。::after 伪元素设置了 pointer-events: none,不会影响文本选中、复制等操作,也不会拦截文本域内的点击事件,可放心使用。

小结

从三行示例代码到 data-count 属性、::after 伪元素渲染链路,ant-design-blazor 的 TextArea ShowCount 是一个“参数极简、实现完整”的典型能力:ShowCount 负责开关、MaxLength 负责输入限制与统计上限、底层类映射器与 LESS 样式负责呈现,bUnit 测试则锁定了从初始值到实时增长的各类行为。无论是评论框、留言板还是表单长文本录入,直接复用 CharCount.razor 的写法即可获得与官方组件库一致的字数提示体验。

登录后查看全文
ant-design-blazor