Ant Design Blazor 字数统计指南:为 Input 与 TextArea 启用 ShowCount 字符计数

原创2026-10-11 16:03:541,716 阅读
文章标签:前端UI组件设计系统WebAssembly

Ant Design Blazor 字数统计指南:为 Input 与 TextArea 启用 ShowCount 字符计数

导读

在表单场景中,为输入框和文本域展示已输入字符数、配合 MaxLength 提示剩余可输入额度,是提升用户体验的常见手段。Ant Design Blazor 的 Input 与 TextArea 组件内置了 ShowCount 特性,一行属性即可开启实时字符统计。本文以仓库中 site/AntDesign.Docs/Demos/Components/Input/demo/CharCount.md 演示文档为主线,结合 Input.cs、TextArea.razor 及配套测试,完整讲解该功能的用法、底层实现原理与样式细节,帮助你快速在 Blazor 项目中落地“带字数提示的文本域”。

ShowCount 功能概览

ShowCount 是 Input 基类暴露的一个布尔参数,用于控制组件是否显示已输入字符数。该参数同时作用于单行输入框 Input(含 InputPassword、Search 等派生组件)与多行文本域 TextArea。定义位置在 Input.cs:

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

从源码结构看,由于 TextArea 通过 @inherits Input<string> 继承自 Input(见 TextArea.razor),两个组件共享同一套参数体系,因此 ShowCount、MaxLength、Suffix、AllowClear 等行为保持一致。

基本用法:带字数提示的文本域

CharCount.md 演示文档对应的完整示例代码位于 CharCount.razor,它展示了最精简的用法:

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

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

开启 ShowCount 后,文本域右下角会实时显示类似 0 / 100 的计数文案;用户输入过程中数字实时增长。MaxLength 将输入长度硬限制为 100 个字符,同时用于计算剩余额度展示。

需要说明的是:CharCount.md 与同目录下的 show-count.md 描述的是同一主题,后者的演示代码 ShowCount.razor 则展示了 Input 与 TextArea 的对照用法:

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

@code {
    void OnChange(string value)
    {
        Console.WriteLine(value);
    }
}

这里 AntDesign.Input 显式指定了泛型参数 TValue="string"(因为 Input<TValue> 是泛型组件),并组合了 AllowClear(可一键清空)与 Suffix(后缀内容,示例中为 "RMB")。两者均开启 ShowCount,但渲染位置不同:输入框的计数显示在输入框内部右侧,文本域的计数显示在其右下角。

参数详解与边界行为

围绕 ShowCount 最常用的参数是 MaxLength,其定义位于 Input.cs:

/// <summary>
/// Max length
/// </summary>
[Parameter]
public int MaxLength { get; set; } = -1;

其核心行为体现在两处:

  1. HTML 属性映射:当 MaxLength >= 0 时,组件会把它作为 maxlength 属性写入原生 input/textarea 元素,从浏览器层面限制输入长度。见 Input.cs:
if (MaxLength >= 0)
{
    Attributes.TryAdd("maxlength", MaxLength);
}
  1. 计数文案拼接:计数文本的生成逻辑是 当前长度 加上可选的 / MaxLength 后缀,由 CountString 属性实现,见 Input.cs:
private string CountString => $"{_inputString?.Length ?? 0}{(MaxLength > 0 ? $" / {MaxLength}" : "")}";

由此可以归纳出三种展示形态(均有对应行为):

参数组合 计数显示 说明
ShowCount(不带 MaxLength) 12 仅显示当前字符数,不限制长度
ShowCount MaxLength="100" 12 / 100 显示当前字符数与上限,并限制输入
ShowCount MaxLength="0" 0 MaxLength=0 时计数不显示上限(因判定条件为 > 0)

后两种形态分别在 tests/AntDesign.Tests/Input/TextAreaTests.razor 中有测试用例直接验证:

  • TextArea_ShowCount_without_maxlength:不带 MaxLength 时,data-count 属性仅等于字符数本身(TextAreaTests.razor);
  • TextArea_ShowCount_shows_initial_value:Value="0123456789" 且 MaxLength=100 时,data-count 断言为 10 / 100(TextAreaTests.razor)。

源码解析:计数从何而来、如何更新

数据来源:_inputString

计数显示的长度并非直接取 Value 属性,而是维护了一个内部字段 _inputString,用于跟踪当前输入框中的原始文本。在 Input.cs 中声明,并在以下时机更新:

  • 初始化时:_inputString = Value?.ToString()(Input.cs);
  • 每次输入事件:OnInputAsync 中执行 _inputString = args?.Value.ToString()(Input.cs);
  • 值变化回调:OnValueChange 中同步 _inputString = CurrentValueAsString(Input.cs);
  • 点击清除(AllowClear)时:_inputString = null,计数归零(Input.cs)。

TextArea 侧在 TextArea.razor.cs 以同样的规则生成了 Count 属性:

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

值得注意的一个实现细节:_inputString 通过 OnInputAsync 在每次 oninput 事件时更新,因此计数是“随输入实时刷新”的,而不是等到失焦(blur)或 change 才变化。这得益于 TextArea.razor 中对 oninput 事件的处理链。

渲染出口:Input 的 Counter 与 TextArea 的 data-count

单行 Input 的计数通过 Counter 这个 RenderFragment 渲染为一个带 ant-input-show-count-suffix 类的 span,见 Input.cs:

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>");
};

只有 ShowCount 为真时该片段才会被加入渲染树(Input.cs)。同时,是否渲染包装层还取决于 Suffix != null || AllowClear || FormItem?.FeedbackIcon != null || ShowCount(Input.cs),说明 ShowCount 与清除按钮、后缀、表单校验图标共享同一套“后缀容器”机制。

TextArea 则走另一条路径:开启 ShowCount 时,组件包裹一层带有 data-count 属性的 div(TextArea.razor):

@if (Suffix != null || AllowClear || FormItem?.FeedbackIcon != null || ShowCount)
{
    <div class="@ClassMapper.Class" style="@Style" data-count="@Count">
        <span class="@_warpperClassMapper.Class">
            <textarea ... />

data-count 属性值即计数文案,它并不会直接显示,而是被 CSS 的 ::after 伪元素读取并展示——这正是该组件实现“右下角计数”的巧妙之处。

样式实现:计数器如何呈现

文本域的 ::after 伪元素

在 index.less 中,ant-input-textarea-show-count 类通过 ::after 伪元素渲染计数:

&-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;
  }
}

关键点在于 content: attr(data-count):它把 div 上的 data-count 属性值作为文本内容输出,因此计数更新只需改变属性值,无需 JS 操作 DOM 文本。pointer-events: none 保证计数区域不会拦截鼠标事件,用户仍可正常点击文本域内部。@text-color-secondary 使计数以次要文字颜色显示,视觉上弱化于主输入内容。

输入框的 suffix 计数

单行输入框的计数样式在 affix.less 中:

&-show-count-suffix {
  color: @text-color-secondary;
}

&-show-count-has-suffix {
  margin-right: 2px;
}

当 Suffix 与 ShowCount 同时存在时,ant-input-show-count-has-suffix 类会在计数与后缀之间留出 2px 间距,避免视觉拥挤。此外,rtl.less 还处理了 RTL 布局下计数的对齐方向(text-align: left)。

组合场景与实战建议

与表单校验共存

ShowCount 与 FormItem 的 FeedbackIcon 共用同一个包装容器判断(FormItem?.FeedbackIcon != null),因此开启字数统计的输入框/文本域可以直接放入 FormItem 中,与校验状态图标、错误提示并存,样式类 ant-input-textarea-in-form-item、ant-input-textarea-has-feedback 会自动追加(见 TextArea.razor.cs)。若同时开启 FormItem.HasFeedback,计数、校验图标会按渲染顺序排列,从测试 TextArea_Wrapper_Disabled 可看出包装层还会同步 Disabled 状态(TextAreaTests.razor)。

输入上限与计数的联动

推荐始终将 ShowCount 与 MaxLength 搭配使用:MaxLength 从 maxlength 属性层面硬性截断输入,ShowCount 实时反馈剩余额度,二者叠加可形成“即见即所得”的限制体验。若业务上只需提示不需限制,单独使用 ShowCount 即可,此时计数仅显示当前长度。

实时性确认

若需在输入过程中即时响应计数变化(例如联动提交按钮的可用状态),应使用 OnInput 事件或 BindOnInput,而非 OnChange(OnChange 在值提交/失焦时才触发)。计数显示本身是实时的——OnInputAsync 每次输入都会更新 _inputString 并触发重渲染,这一点在测试 TextArea_ShowCount_increase 中得到了验证:输入 newValue 后 data-count 立即变为 8 / 100(TextAreaTests.razor)。

结语

Ant Design Blazor 的字数统计能力并非简单的“读 Value.Length 再拼字符串”,而是由 _inputString 状态追踪、data-count 属性桥接、CSS ::after 伪元素渲染三部分协同完成的完整链路:Input 与 TextArea 共享 ShowCount/MaxLength 参数语义,又在渲染出口上各自适配(输入框用 suffix span、文本域用 data-count 伪元素)。理解这条链路后,你不仅能熟练使用该特性,还能在需要定制计数格式(如统计中文字符、过滤换行)时,准确找到扩展切入点。相关演示与测试代码均可直接在仓库中查阅:CharCount.razor、ShowCount.razor 与 TextAreaTests.razor。

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