Ant Design Blazor 字数统计指南:为 Input 与 TextArea 启用 ShowCount 字符计数
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;
其核心行为体现在两处:
- HTML 属性映射:当
MaxLength >= 0时,组件会把它作为maxlength属性写入原生input/textarea元素,从浏览器层面限制输入长度。见 Input.cs:
if (MaxLength >= 0)
{
Attributes.TryAdd("maxlength", MaxLength);
}
- 计数文案拼接:计数文本的生成逻辑是
当前长度加上可选的/ 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。