Ant Design Blazor 输入框字数提示(ShowCount)实现指南:从 Input 到 TextArea 的完整实战

原创2026-10-11 10:22:17374 阅读
文章标签:前端UI组件设计系统WebAssembly

Ant Design Blazor 输入框字数提示(ShowCount)实现指南:从 Input 到 TextArea 的完整实战

Ant Design Blazor 的 Input 与 TextArea 组件内置了"带字数提示"能力,通过 ShowCount 参数即可在输入框右下角实时显示当前输入字符数与最大长度的比例(如 0 / 20)。本文基于仓库中的官方示例 show-count.md 与 CharCount.md,结合组件源码 Input.cs、TextArea.razor 及其测试用例,系统讲解字数提示的配置方法、底层实现原理、样式细节与常见组合用法,帮助你在一行代码内为表单输入框和文本域加上专业的字数反馈。

一、功能概览:什么是 ShowCount

ShowCount 是 Input<TValue> 组件(TextArea 继承自 Input<string>)提供的一个布尔参数,用于在输入框或文本域中显示文本计数。官方文档 index.zh-CN.md 中对其说明为:

是否显示文本计数。需要设置 MaxLength 属性。

结合 MaxLength 使用时的典型效果是:在输入框右下角出现类似 12 / 20 的字数提示,其中 12 是当前已输入字符数,20 是 MaxLength 设定的最大长度;不设置 MaxLength 时,则只显示当前字符数(如 12)。

该参数从版本 0.9 起同时支持 Input 与 TextArea,是表单场景中限制输入长度、提示剩余可输字符数最直接的手段。

二、快速上手:官方示例代码

官方 demo 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>

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

而 CharCount.razor 则提供了一个最精简的文本域字数提示写法:

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

@code{

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

代码要点解读

  • ShowCount:开启字数提示的核心开关,值为 true 时生效;
  • MaxLength:最大字符长度,同时会透传为原生 <input> / <textarea> 的 maxlength 属性,从输入层面直接限制用户可输入的字符数;默认值为 -1,表示不限制(此时字数提示只显示当前长度);
  • OnChange:输入内容变化(失焦或绑定刷新)时触发的回调,参数类型为 TValue,上面示例中为 string,可在回调中拿到最新输入值;
  • AllowClear + Suffix(仅 Input 示例):演示了字数提示与清除按钮、后缀内容共存的组合布局,三者会同时出现在输入框的 suffix 区域中。

三、Input 组件:字数提示的实现细节

3.1 参数定义与默认值

在源码 Input.cs 中,ShowCount 与 MaxLength 两个参数定义如下:

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

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

MaxLength 的默认值是 -1。在 SetAttributes() 方法中,只有当 MaxLength >= 0 时才会把 maxlength 属性写入 DOM:

protected void SetAttributes()
{
    Attributes ??= [];

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

也就是说:只设 ShowCount 而不设 MaxLength 时,输入框不会被限制长度,字数提示仅显示当前字符数;设置 MaxLength 后,浏览器原生与组件计数才会同时以最大长度为上限。

3.2 计数文本的生成:CountString

Input<TValue> 内部通过 _inputString 字段跟踪最新的输入值(在 OnInputAsync 中随每次输入实时更新),并据此生成计数文本:

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

这段逻辑可以拆解为两种输出形态:

  • 未设置 MaxLength(默认 -1):输出 0、12 这类纯当前长度;
  • 设置了 MaxLength:输出 0 / 20、12 / 100 这类当前长度 / 最大长度。

3.3 计数节点的渲染:Counter RenderFragment

计数内容由 Counter 渲染片段生成,渲染为带 ant-input-show-count-suffix 类名的 <span>;如果同时存在 Suffix 内容,则追加 ant-input-show-count-has-suffix 类,保证计数与自定义后缀之间有合适间距:

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

3.4 渲染位置:suffix 区域

在 BuildRenderTree 中,是否启用后缀容器由 hasSuffix 决定,ShowCount 是触发条件之一:

var hasSuffix = Suffix != null || AllowClear || FormItem?.FeedbackIcon != null || ShowCount;

随后在 suffix 容器内按顺序渲染:清除图标(AllowClear)→ 计数(ShowCount)→ 自定义后缀(Suffix)→ 表单反馈图标:

if (hasSuffix)
{
    builder.OpenElement(91, "span");
    builder.AddAttribute(92, "class", $"{PrefixCls}-suffix");

    if (AllowClear) builder.AddContent(93, ClearIcon);
    if (ShowCount) builder.AddContent(110, Counter);
    if (Suffix != null) builder.AddContent(94, Suffix);
    if (FormItem?.FeedbackIcon != null) builder.AddContent(95, FormItem.FeedbackIcon);

    builder.CloseElement();
}

因此,Input 的字数提示实际是作为 suffix 区域中的一个 <span> 渲染在输入框右侧,与 AllowClear、Suffix、表单校验反馈图标共同组成"右侧功能区",顺序固定为:清除图标 → 计数 → 后缀 → 反馈图标。

四、TextArea 组件:基于 data-count 的字数提示

文本域的字数提示实现路径与 Input 不同,它利用 CSS 伪元素 ::after 读取 data-count 属性完成渲染。

4.1 包装容器与 data-count 属性

在 TextArea.razor 中,当存在 Suffix、AllowClear、FormItem?.FeedbackIcon 或 ShowCount 中的任意一项时,文本域会包上一层 <div>,并把计数写入 data-count 属性:

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

计数文本 Count 在 TextArea.razor.cs 中生成,与 Input 的 CountString 规则一致:

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

4.2 类名标记:ant-input-textarea-show-count

TextArea 初始化时,ClassMapper 会在 ShowCount 为 true 时追加 ant-input-textarea-show-count 类:

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

4.3 样式层:伪元素 ::after 显示计数

对应样式定义在 index.less 中(components/input/style/index.less#L50-L69):

&-textarea-show-count {
  // https://github.com/ant-design/ant-design/issues/33049
  > .@{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;
    }
  }
}

关键点:

  • 计数不是真实 DOM 节点,而是通过 content: attr(data-count) 由 CSS 伪元素绘制,因此不占文档流、不影响复制粘贴与屏幕阅读器读取;
  • pointer-events: none 确保计数区域不拦截鼠标事件;
  • 计数颜色使用 @text-color-secondary(次要文本色),视觉上弱于正文输入内容;
  • 当 TextArea 位于 FormItem 中时,通过 margin-bottom: -22px 微调位置,避免与表单校验提示信息冲突。

4.4 RTL 适配

在 rtl.less 中针对从右向左布局做了适配,RTL 模式下计数对齐方式从右对齐改为左对齐:

&-textarea {
  &-rtl {
    direction: rtl;
  }

  &-rtl&-show-count::after {
    text-align: left;
  }
}

五、样式细节:Input 侧计数节点

Input 侧计数节点使用的前缀类样式定义在 affix.less 中:

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

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

同样使用次要文本色 @text-color-secondary;当与自定义 Suffix 共存时,ant-input-show-count-has-suffix 提供 2px 的右间距,避免计数与后缀文字紧贴。

六、测试验证:计数行为有据可查

仓库测试用例 TextAreaTests.razor 对字数提示的四种核心行为做了断言,可作为功能行为的"官方佐证":

1. 初始值展示(TextArea_ShowCount_shows_initial_value):为 ShowCount MaxLength=100 的 TextArea 设置初始值 "0123456789"(10 个字符)后,断言外层 div 的 data-count 属性等于 "10 / 100"。

2. 不设 MaxLength(TextArea_ShowCount_without_maxlength):仅设置 ShowCount、不设置 MaxLength 时,data-count 仅等于 "10"(当前长度),与 Count 属性中 MaxLength > 0 才拼接 / N 的逻辑一致。

3. 禁用态包装(TextArea_Wrapper_Disabled):ShowCount + Disabled 组合下,外层 <span> 应包含 ant-input-affix-wrapper-disabled 类。

4. 输入后实时更新(TextArea_ShowCount_increase):设置 DebounceMilliseconds="0" 后模拟输入 "newValue",再触发 KeyUp 并重新渲染,断言 data-count 变为 "8 / 100",证明计数会随输入实时刷新(_inputString 在 OnInputAsync 中同步更新)。

这些测试可以直接在 tests/AntDesign.Tests 项目中运行,验证当前仓库版本的字数提示行为。

七、组合用法与注意事项

7.1 常见组合场景

组合 效果 适用场景
ShowCount + MaxLength 显示 当前 / 最大,输入被硬性限制 评论框、标题输入、简介填写
仅 ShowCount 只显示当前字符数,不限制输入 展示字数统计而不想拦截输入
ShowCount + AllowClear 计数与一键清空共存 搜索框、表单可重置字段
ShowCount + Suffix 计数与自定义后缀(如单位)并存 金额、计量单位输入
ShowCount + AutoSize 文本域自适应高度 + 右下角计数 多行备注、消息内容

7.2 注意事项

  • MaxLength 的单位:计数基于 _inputString.Length,即字符串的 char 数量。中文字符按 1 个字符计,与浏览器原生 maxlength 行为保持一致,但并非 UTF-16 码点或"字节数",在 emoji(代理对)等场景下计数可能与直觉略有差异;
  • MaxLength 默认值为 -1:只有 > 0 时才参与计数拼接与 maxlength 属性写入;若想"有计数但无硬限制",直接不设该属性即可;
  • 与 FormItem 的配合:FormItem 中启用校验反馈图标时,图标会渲染在计数之后;TextArea 样式也对 -in-form-item 场景做了位置微调,可直接嵌套在 FormItem 内使用,无需额外处理;
  • 计数实时性:Input/TextArea 的计数基于 _inputString,在 oninput 事件中即时更新,配合 DebounceMilliseconds(默认 250ms,设置后自动开启 BindOnInput)可控制绑定与计数的刷新节奏。

八、小结

ShowCount 是 Ant Design Blazor 输入组件中"零成本"的字数反馈方案:一行参数即可在 Input 与 TextArea 上启用,配合 MaxLength 实现"计数 + 硬性限制",并与 AllowClear、Suffix、FormItem 校验反馈等能力天然共存。其底层实现清晰——Input 侧通过 suffix 区域的 Counter 渲染片段输出计数 <span>,TextArea 侧则借助 data-count 属性与 CSS ::after 伪元素绘制,两者均以 _inputString.Length 为计数依据。官方示例 ShowCount.razor 与 CharCount.razor 可直接作为起点复制改造,相关测试 TextAreaTests.razor 则为行为正确性提供了验证保障。

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