Ant Design Select 多选数量上限 maxCount 完整指南：配置、底层实现与计数反馈

maxCount 是 antd Select 组件中用于约束多选模式可选上限的 Props，它从 5.13.0 版本开始提供，用于阻止用户无限勾选。本文围绕 components/select/demo/maxCount.md 及其配套示例，结合本仓库中 Select 的源码与测试，讲解 maxCount 的作用范围、推荐搭配写法、底层透传逻辑与边界限制，帮助你写出可直接落地的多选限选表单。

一句话认识 maxCount

在 antd 的 Select 组件里，maxCount 用于指定「最多可选中的 items 数量」。当用户的已选数量达到上限后，下拉列表中尚未被选中的选项会进入禁止选中（disabled）状态，无法再被勾选。它是约束交互行为的属性，与另一个常用属性 maxTagCount（控制已选 tag 在输入框中的显示数量、超出部分折叠为 +N）有本质区别：

• maxCount：限制「能选多少个」，超出即不能继续选；
• maxTagCount：限制「显示多少个」，只是视觉折叠，不影响继续选中。

官方属性表对该属性的完整定义为：指定可选中的最多 items 数量，仅在 mode 为 multiple 或 tags 时生效，类型为 number，默认值为 -（无限制），自 5.13.0 引入且不支持 ConfigProvider 全局配置。

示例源码与最小可用代码

官方示例位于 components/select/demo/maxCount.tsx，它演示的是「最多选 3 个人员」的典型场景，并在后缀区实时展示当前计数。去掉样式装饰后的最小可用形态如下：

import React from 'react';
import { Select } from 'antd';

const MAX_COUNT = 3;

const App: React.FC = () => {
  const [value, setValue] = React.useState<string[]>(['Ava Swift']);

  return (
    <Select
      mode="multiple"
      maxCount={MAX_COUNT}
      value={value}
      onChange={setValue}
      placeholder="Please select"
      options={[
        { value: 'Ava Swift', label: 'Ava Swift' },
        { value: 'Cole Reed', label: 'Cole Reed' },
        // ... 其余选项
      ]}
    />
  );
};

export default App;

要点拆解：

1. mode="multiple" 是前提：maxCount 只在多选（multiple）与标签输入（tags）两种模式下有意义，示例因此显式开启了 multiple。
2. value 受控 + onChange：示例将选中值提升为受控状态，onChange 直接把新数组写回 value，保证 UI 与数据同步。
3. 默认值不占用限制名额：示例初始化选中了 Ava Swift（数组长度为 1），用户实际还能再选 2 项，说明 maxCount 是对总选中数量（含受控 value 中已有项）的约束，而非「本次会话还能选几个」。

该示例同时出现在官方 Demo 目录的「最大选中数量」条目（components/select/index.zh-CN.md 中 version="5.13.0" 标记即为该属性的引入版本），并作为截图快照用例被 CI 守护（见 components/select/tests/snapshots/demo.test.tsx.snap 中 renders components/select/demo/maxCount.tsx correctly）。

进阶：在下拉后缀实时展示「已选 / 上限」计数

demo/maxCount.md 的配套示例在说明 maxCount 之外，还演示了一种高价值搭配：把已选数量与上限渲染进选择框后缀，使用户随时感知剩余额度。这正是示例中使用 suffixIcon 替换默认下拉箭头的原因：

const suffix = (
  <>
    <span>
      {value.length} / {MAX_COUNT}
    </span>
    <DownOutlined />
  </>
);

随后将 suffix={suffix} 传入 Select。当用户逐个选中或取消时，value 变化触发重渲染，后缀中的 1 / 3、2 / 3 便实时更新；DownOutlined 则用于保留"可展开"的视觉提示。

需要留意的是，antd 官方属性表中注明：替换掉的后缀图标默认不再响应展开/收缩事件，如有交互需求需要自行处理。若你不需要计数提示，完全可以直接省略 suffixIcon，仅依赖 maxCount 自身的禁用态反馈。

底层实现：属性如何被解析与透传

在 antd 这一层，Select 的核心实现集中在 components/select/index.tsx，maxCount 的流转分三步：

1. 从 props 解构：组件在解构阶段取出 maxCount，同时计算当前是否处于多选语义（见 index.tsx）：

const isMultiple = mode === 'multiple' || mode === 'tags';

注意源码特意将 combobox 模式归一为 undefined，因此 isMultiple 只对 multiple / tags 为真，这与「maxCount 仅在这两种模式生效」的文档约束完全一致。

2. 开发环境参数守卫：当 maxCount 被传入但组件并非多选模式时，源码会给出使用警告（见 index.tsx）：

warning(
  !(typeof maxCount !== 'undefined' && !isMultiple),
  'usage',
  '`maxCount` only works with mode `multiple` or `tags`',
);

3. 透传至底层 rc-select：真正的选中拦截逻辑由底层 rc-select 实现，antd 在渲染 RcSelect 时做了条件化转发（见 index.tsx）：

maxCount={isMultiple ? maxCount : undefined}

即在非多选模式下，maxCount 根本不会被传给底层组件。这意味着超出上限后选项自动变成 disabled 的"禁止选中"反馈，是由 rc-select 依据 maxCount 与当前选中集合的长度比对得出的：当 已选数量 >= maxCount 时，所有未选中项进入不可点选状态。

上述守卫行为有测试用例固化：见 components/select/tests/index.test.tsx 中的 Select maxCount warning 用例，它渲染了一个未开启多选的 <Select maxCount={10} />，并断言控制台输出 Warning: [antd: Select] \maxCount` only works with mode `multiple` or `tags``。

使用约束与边界情况速查

场景	行为
mode="multiple" + maxCount={n}	正常限选，达到 n 个后其余选项禁用
mode="tags" + maxCount={n}	同样生效，新输入的标签数量同样受限
单选（未设 mode 或 mode="combobox"）	属性被丢弃并触发 dev 警告，无实际效果
不传 maxCount	无数量限制（默认行为）
与 maxTagCount 并用	一个控"可选上限"，一个控"显示折叠"，互不冲突
受控 value 预置超过 n 个	以当前 value 长度为准，进一步选择被禁止；先在外部裁剪 value 后再继续

结合前文给出的源码依据，实际接入时有四条经验可以直接套用：

1. 务必先开 multiple 或 tags，否则 maxCount 形同虚设且伴随 warning；
2. maxCount 与 defaultValue/value 叠加生效，预置的已选项占用额度；
3. 善用 suffixIcon 计数（如示例的 value.length / MAX_COUNT）把限制可视化，减少用户困惑；
4. 在 tags 模式下配合清除/删除交互：超限后用户通过 tag 上的移除按钮释放名额，计数后缀随之回落，可继续添加。

小结

maxCount 是 antd Select 中"交互级"的数量硬限制，从 5.13.0 起可用：声明 mode 为 multiple/tags 后传入一个 number，底层 rc-select 便会在达到上限时自动禁用其余选项；antd 侧源码则负责模式校验、dev 警告与条件透传（components/select/index.tsx）。配合 suffixIcon 实时计数（参考 components/select/demo/maxCount.tsx），即可低成本实现带余量提示的限选下拉框。