Ant Design AutoComplete 禁用状态文字颜色 Debug：Form 级禁用与组件级禁用的视觉一致性

导读

本文以 disabled-in-form-debug 文档 为核心，讲解 Ant Design 中 AutoComplete 组件在“置于 Form 的禁用上下文中”与“直接设置 disabled 属性”两种场景下，输入文字应统一使用禁用色（colorTextDisabled）的调试目标与实现原理。读完本篇，你将理解 demo 中两个输入框的对照设计、disabled 状态如何从 Form 一路传递到底层 Select 基类，以及禁用样式在源码中的落点，便于你在自定义组件或主题定制中复刻这种“状态视觉一致”的做法。

文档定位：这是一个什么样的 demo

该文档位于 components/auto-complete 的 demo 目录下，与同名的 disabled-in-form-debug.tsx 成对出现。文档内容本身非常简短，只描述了一个调试目标（Debug）：

禁用状态下的文字颜色 Debug：AutoComplete 在禁用的 Form 中以及直接禁用时，输入框文字均应使用禁用色。

它并不是一个面向最终用户的用法示例，而是一个视觉回归验证 demo：当仓库中有人修改了 AutoComplete、底层 Select 或 Form 的禁用相关逻辑时，通过比对这个 demo 的渲染快照，就能发现“两种禁用路径下文字颜色不一致”这类视觉缺陷。该 demo 在 AutoComplete 中文 API 文档 中以如下方式挂载（英文文档 index.en-US.md 中同样注册）：

<code src="./demo/disabled-in-form-debug.tsx" debug>Disabled text color in Form debug</code>

注意这里的 debug 属性——仓库中的站点渲染器据此把它归类为调试类 demo，它服务于开发期的视觉校验，而不是文档站上的常规教学示例。

完整示例代码：两种禁用路径的并排对照

demo 源码全文如下（完整继承自 disabled-in-form-debug.tsx）：

import React from 'react';
import { AutoComplete, Flex, Form } from 'antd';

const options = [{ value: 'Disabled Value' }];

const App: React.FC = () => (
  <Flex vertical gap={12} style={{ width: 240 }}>
    <Form disabled>
      <Form.Item label="Form disabled" style={{ marginBottom: 0 }}>
        <AutoComplete value="Disabled Value" options={options} />
      </Form.Item>
    </Form>
    <AutoComplete disabled value="Disabled Value" options={options} />
  </Flex>
);

export default App;

这个页面把两个输入框垂直排布（Flex vertical gap={12}，宽度固定 240px），构成一个最小可判定的视觉对照实验：

行	禁用方式	AutoComplete 自身 props	预期视觉
上	Form 容器声明 disabled	未写 disabled	输入文字为禁用色
下	组件自身声明 disabled	disabled	输入文字为禁用色

两条路径共享同一个受控值 value="Disabled Value" 和同一份 options（[{ value: 'Disabled Value' }]），这样排除了“文字内容不同导致颜色观感不同”的干扰，比对焦点完全收敛在文字颜色这一条样式上。这正是文档中“均应使用禁用色”这句话的验证载体：只要两处渲染出的文字色出现任何偏差（例如一处仍为正常文字色 colorText），就说明某条禁用链路存在样式漏洞。

源码链路：两条禁用路径如何汇合

要理解这个 demo 为什么“值得专门开一个 debug 页”，需要看 AutoComplete 的组件实现。

AutoComplete 本质上是 Select 的受控包装

从 AutoComplete.tsx 源码看，AutoComplete 并没有自己实现选择器逻辑，而是把大部分 props 原样透传给内部 Select，并以一个内部标记模式运行：

return (
  <Select
    ref={ref}
    suffixIcon={null}
    {...omit(props, [
      'dataSource',
      'dropdownClassName',
      'popupClassName',
      'onDropdownVisibleChange',
      'onOpenChange',
    ])}
    prefixCls={prefixCls}
    ...
    mode={Select.SECRET_COMBOBOX_MODE_DO_NOT_USE as SelectProps['mode']}
    ...
  >
    {optionChildren}
  </Select>
);

这里有两点对本文主题很关键：

1. omit 的列表中不包含 disabled，也就是说组件自身的 disabled 属性会被原封不动地传递给 Select（demo 中第二个输入框走的路径）。
2. AutoComplete 复用 Select 的全部交互与样式体系，因此它的禁用视觉完全取决于 Select 的实现。这解释了为什么仓库要为“AutoComplete 在禁用 Form 中”单独做 debug——两条禁用路径最终都必须落到 Select 的同一套禁用样式上，任何一层断链（比如 Form 的禁用没有下传到基类，或基类识别了禁用却没改文字色）都会在这个 demo 上暴露。

入口文件 index.tsx 只是再包了一层，把 AutoComplete.Option（Select.Option 的导出）与用于文档站调试面板的 PurePanel 挂到组件对象上，与禁用逻辑无关。

Form 禁用与组件禁用的汇合点

对于第一个输入框，AutoComplete 自己并没有收到 disabled，禁用态来自外层 <Form disabled>。在 Form 的实现中，disabled 会作为禁用上下文沿 React 树向下传递，表单内控件（AutoComplete 背后的 Select）会读取该上下文合并出最终的禁用状态；从源码结构看，可以推断其工作方式与其他表单控件（Input、Select 等）保持一致：上下文禁用态与自身 disabled 属性做“或”运算，任一为真即渲染为禁用。

两条路径在视觉层的汇合点，位于 Select 基类的输入区样式。在 select-input.ts 中，禁用态的样式规则统一写在 &-disabled 修饰下：

// ==========================================================
// ==                       Disabled                       ==
// ==========================================================
'&-disabled': {
  background: token.colorBgContainerDisabled,
  [varName('color')]: token.colorTextDisabled,
  cursor: 'not-allowed',

  input: {
    cursor: 'not-allowed',
  },
},

这段样式正是文档中“输入框文字均应使用禁用色”的实现依据：文字色被显式设置为主题 token colorTextDisabled，同时容器背景使用 colorBgContainerDisabled、光标变为 not-allowed。由于 AutoComplete 透传 prefixCls（getPrefixCls('select')，见 AutoComplete.tsx），它命中与 Select 完全相同的 &-disabled 规则。

除文字色外，禁用相关的 token 还在 select/style/token.ts 中做了聚合（如 multipleItemColorDisabled: colorTextDisabled），以及下拉面板侧的禁用项配色（select/style/dropdown.ts 中同样使用 token.colorTextDisabled）。这说明“禁用色”不是一个散落的魔法值，而是从主题 token 出发，在输入框、多选标签、下拉项等多个表面统一取色——demo 校验的“文字颜色”，只是这条 token 链路中最先被肉眼察觉的一环。

同目录下的姊妹 demo

auto-complete/demo 下还有一组同系列的 debug demo，可对照理解“禁用态视觉一致性”的覆盖面：

• disabled-custom-debug.tsx：验证 AutoComplete 的自定义输入框（customizeInput）禁用时，与原生 Input、Select 的禁用配色保持一致；
• form-debug.tsx：验证 AutoComplete 在 Form 中校验态（成功/错误/警告）的视觉表现。

disabled-custom-debug.tsx 的实现是把 <Input.TextArea disabled /> 作为 children 传给 <AutoComplete disabled>，与 Input disabled 和 Select disabled 并排渲染；这对应了 AutoComplete.tsx 中“唯一非 Option 子节点被识别为 customizeInput”的逻辑分支——本节的 disabled-in-form-debug demo 走的是标准输入框路径，两者共同覆盖了禁用态的两个输入表面。

关键参数速查

围绕本文主题，涉及的核心 props 及其在禁用语义中的作用如下（类型定义见 AutoComplete.tsx）：

参数	位置	作用	备注
disabled	AutoComplete 自身 / Select 基类	组件级禁用，直接命中 &-disabled 样式	经 omit 列表后原样透传给 Select
disabled	Form 容器	为整张表单内的控件注入禁用上下文	demo 中第一个输入框即未自带 disabled
value	AutoComplete	受控值，决定输入框展示的文字	demo 固定为 "Disabled Value" 以保证两行可比
options	AutoComplete	候选项数据源	demo 使用 [{ value: 'Disabled Value' }]
status	AutoComplete	校验态（success / warning / error）	与 disabled 正交，由 form-debug.tsx 系列单独校验

需要特别说明的边界：文档中描述的“禁用色”指的是主题语义色 colorTextDisabled，具体色值由当前主题决定（默认浅色主题下为灰色系）。如果你的项目通过 ConfigProvider 覆盖了 colorTextDisabled，demo 中的两个输入框颜色会同步变化，但“两处一致”这一校验结论不受影响。

如何用这个 demo 做验证

1. 本地复现：仓库为只读研究场景，实际开发中可按 AutoComplete 组件文档 的指引安装对应版本并在你自己的工程中使用同款代码；本 demo 只依赖 antd 的 AutoComplete、Form、Flex 三个公开导出，无额外依赖。
2. 比对要点：只看输入框内已渲染文字的 color，确认上下两行取色相同，且等于当前主题下 colorTextDisabled 的计算值；顺带确认背景为禁用底色、光标为 not-allowed。
3. 回归依据：仓库为 demo 目录维护了快照测试（见 snapshots），样式回归时该 demo 的渲染结果会参与比对，这正是“debug demo”被保留在 demo 目录并注册进 API 文档的意义。

小结

这个 debug demo 的价值在于把一个容易遗漏的边界条件——“Form 级禁用”与“组件级禁用”必须产生完全相同的视觉结果——固化成了一个两行输入框的对照页面。它的背后链路清晰：AutoComplete 透传 props 并复用 Select 基类（AutoComplete.tsx），两条禁用路径在基类的 &-disabled 规则（select-input.ts）处汇合，最终都从主题 token colorTextDisabled 取色。理解这条链路后，你也能在自己的组件库中用同样的“并排对照 + token 统一取色”方式，保证复合禁用来源下的视觉一致性。