ant-design-blazor 文本域字数提示实战:TextArea ShowCount 完整指南
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 的描述只有一句话:展示字数提示。但要真正理解这行组件标记的含义,需要拆解三个关键点:
ShowCount:开关参数,设为true后组件才会渲染字数统计区域;MaxLength=100:最大长度限制,同时承担两个职责——通过原生maxlength属性限制用户输入,并为字数统计提供“分母”;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 时有几点值得注意:
-
务必搭配
MaxLength使用。虽然组件允许单独开启ShowCount,但只有同时设置MaxLength,原生输入限制与“当前/上限”的完整提示才同时生效,这也是官方 API 文档的推荐用法。 -
初始值也会被计入统计。
Count属性基于_inputString实时计算,无论是双向绑定(@bind-Value)传入的初始值、DefaultValue,还是用户后续输入,都会即时反映在计数上,测试TextArea_ShowCount_shows_initial_value已覆盖此场景。 -
与表单项(FormItem)协同。
ShowCount开启后组件会进入 wrapper 渲染分支,此时与FormItem的校验状态、反馈图标共存于同一容器;样式层已针对表单项场景做了专门的位置修正,但若自定义样式时需留意ant-input-textarea-show-count与ant-input-textarea-in-form-item两个类同时存在的情况。 -
RTL 布局自动适配。国际化项目无需额外代码,rtl.less 中的规则会自动调整计数对齐方向。
-
计数文本不可交互。
::after伪元素设置了pointer-events: none,不会影响文本选中、复制等操作,也不会拦截文本域内的点击事件,可放心使用。
小结
从三行示例代码到 data-count 属性、::after 伪元素渲染链路,ant-design-blazor 的 TextArea ShowCount 是一个“参数极简、实现完整”的典型能力:ShowCount 负责开关、MaxLength 负责输入限制与统计上限、底层类映射器与 LESS 样式负责呈现,bUnit 测试则锁定了从初始值到实时增长的各类行为。无论是评论框、留言板还是表单长文本录入,直接复用 CharCount.razor 的写法即可获得与官方组件库一致的字数提示体验。