Ant Design DatePicker status 状态指南：error/warning 的用法、样式与源码实现

导读：antd 的 DatePicker / RangePicker 通过 status 属性即可呈现 error（错误）与 warning（警告）两种语义状态，常用于表单校验失败或对用户输入给出温和提醒的场景。本文以 components/date-picker/demo/status.md 这条官方 demo 为骨架，结合 ant-design 仓库内 DatePicker 的生成器实现与样式源码，讲解 status 的取值、写法、视觉样式、与 Form 校验的联动机制及底层实现原理。

status 是什么：DatePicker 状态体系

日期选择器的默认外观无法表达“填错了”或“值得注意”这类语义。为此，antd 为输入类组件统一引入了 status 状态体系，DatePicker 通过 status 属性即可切换输入框的边框、聚焦条与图标颜色。

官方 demo 文档原文对此说明得非常简洁：

• zh-CN：使用 status 为 DatePicker 添加状态，可选 error 或者 warning。
• en-US：Add status to DatePicker with status, which could be error or warning。

Demo 对应的完整示例位于 components/date-picker/demo/status.tsx，同时覆盖了单选的 DatePicker 与区间的 DatePicker.RangePicker：

import React from 'react';
import { DatePicker, Space } from 'antd';

const App: React.FC = () => (
  <Space vertical style={{ width: '100%' }}>
    <DatePicker status="error" style={{ width: '100%' }} />
    <DatePicker status="warning" style={{ width: '100%' }} />
    <DatePicker.RangePicker status="error" style={{ width: '100%' }} />
    <DatePicker.RangePicker status="warning" style={{ width: '100%' }} />
  </Space>
);

export default App;

从类型定义看，status 的取值来源于 antd 的输入状态工具模块：

const _InputStatuses = ['warning', 'error', '', 'success', 'validating'] as const;
export type InputStatus = (typeof _InputStatuses)[number];

这段定义见 components/_util/statusUtils.ts。它属于整套 input 类组件（Input、InputNumber、Select 等）共享的“输入状态”类型。需要说明的是：虽然类型层面允许 success、validating，但 DatePicker 官方文档只对外承诺 error 与 warning 两种取值，其样式文件也只定义了这两种状态的具体视觉，因此生产环境应严格按 error | warning 使用。

基本用法：给单选与区间选择器加状态

status 的使用方式与 antd 其它状态类属性一致，只需在组件上直接声明。当存在错误或警告语义时，推荐配合 Space 垂直排列并撑满宽度以获得更清晰的对比效果（参考上面 demo）。真实项目中常见的两种触发形态：

• 静态声明：数据本身不可用或不允许选择时，直接写死 status="error"；
• 条件动态切换：依据业务逻辑返回的校验结果计算状态值，例如 status={hasError ? 'error' : ''}。

值得补充的是：DatePicker 家族并非只有 DatePicker 一种形态。查看 components/date-picker/generatePicker/generateSinglePicker.tsx 的工厂函数可知，DatePicker、WeekPicker、MonthPicker、YearPicker、QuarterPicker 与 TimePicker 都是由同一个 getPicker() 工厂生成的（见 getPicker 返回值与文件末尾的导出语句），因此这些形态在选择器交互外观上天然支持 status 属性；RangePicker 则由 generateRangePicker.tsx 单独实现，同样接收 status。

status 与 variant / disabled 的相互作用

自 antd 5.13 起，日期选择器引入了 variant 概念以取代旧的 bordered，用于控制边框形态：

• outlined（默认）：外描边样式
• underlined：仅底部线条，聚焦时显示加粗的 active bar
• filled：填充背景样式
• borderless：无边框样式

需要留意的是，status 的视觉呈现与上述 variant 是叠加关系而非替换关系。源码中，输入框 className 的组装会同时追加尺寸类（-large / -small）、variant 类与状态类，见 generateSinglePicker.tsx：

className={clsx(
  {
    [`${prefixCls}-large`]: mergedSize === 'large',
    [`${prefixCls}-small`]: mergedSize === 'small',
    [`${prefixCls}-${variant}`]: enableVariantCls,
  },
  getStatusClassNames(
    prefixCls,
    getMergedStatus(contextStatus, customStatus),
    hasFeedback,
  ),
  // ...
)}

RangePicker 采用完全相同的拼接策略（见 generateRangePicker.tsx）。也就是说，无论你选择哪种 variant，status 颜色都会被独立地应用到该形态上。

另外，状态样式对 disabled 是豁免的。样式选择器明确排除了禁用态（见下文），因此一个同时带 disabled 与 status="error" 的日期选择器不会显示红色警示，避免“灰底+红框”这类矛盾视觉。

状态如何落到 DOM：工具函数与 className 约定

DatePicker 并没有为每个状态手写一套逻辑，而是复用 antd 的通用状态工具。核心是 components/_util/statusUtils.ts 中的两个函数：

export const getStatusClassNames = (
  prefixCls: string,
  status?: ValidateStatus,
  hasFeedback?: boolean,
) =>
  clsx({
    [`${prefixCls}-status-success`]: status === 'success',
    [`${prefixCls}-status-warning`]: status === 'warning',
    [`${prefixCls}-status-error`]: status === 'error',
    [`${prefixCls}-status-validating`]: status === 'validating',
    [`${prefixCls}-has-feedback`]: hasFeedback,
  });

export const getMergedStatus = (contextStatus?: ValidateStatus, customStatus?: InputStatus) =>
  customStatus || contextStatus;

getStatusClassNames 负责把语义状态翻译成 ant-picker-status-error / ant-picker-status-warning 这类 CSS 类名；getMergedStatus 则体现优先级规则——组件上显式传入的 customStatus 优先于 Form 上下文带来的 contextStatus，未显式指定时才回落到上下文状态。

状态颜色的真正来源：样式 token 与生成逻辑

仅挂上 className 还不够，真正产生红/橙视觉的是日期选择器的样式模块。在 components/date-picker/style/index.ts 中有一个专门的 genPickerStatusStyle 生成器：

const genPickerStatusStyle: GenerateStyle<PickerToken, CSSObject> = (token) => {
  const { componentCls, colorError, colorWarning } = token;
  const [varName] = genCssVar(token.antCls, 'date-picker');

  return {
    [`${componentCls}:not(${componentCls}-disabled):not([disabled])`]: {
      [`&${componentCls}-status-error`]: {
        [varName('affix-color')]: token.colorErrorAffix,
        [`${componentCls}-active-bar`]: {
          background: colorError,
        },
      },
      [`&${componentCls}-status-warning`]: {
        [varName('affix-color')]: token.colorWarningAffix,
        [`${componentCls}-active-bar`]: {
          background: colorWarning,
        },
      },
    },
  };
};

这段样式揭示了 status 的视觉构成：

1. affix（前后缀图标）颜色：通过 CSS 变量 --date-picker-affix-color 注入，error 对应 colorErrorAffix，warning 对应 colorWarningAffix。由于 DatePicker 的日历图标走的是组件自身的前缀图标逻辑，这里用一个 CSS 变量即可驱动图标变色，无需为每个 variant 重复声明。
2. active bar（聚焦条）颜色：当采用 underlined 等含聚焦条的外观时，error / warning 状态会把 -active-bar 的背景分别置为设计令牌 colorError 与 colorWarning。
3. 禁用豁免：外层选择器带 :not(...-disabled):not([disabled])，保证禁用状态下状态色一律不生效。

在此基础上，日期选择器的整体结构（含 border/focus/placeholder 等）由 style/index.ts 的 genPickerStyle 与基于 input variants 的 style/variants.ts（复用 components/input/style/variants.ts 中的 genOutlinedStyle、genUnderlinedStyle、genFilledStyle、genBorderlessStyle）共同拼装完成。状态样式与 variants 样式互不干扰，这正是它们可以自由组合的原因。

在 Form 中联动：校验状态的自动同步

status 最有价值的应用场景是表单校验。DatePicker 内部从 components/form/context.tsx 导出的 FormItemInputContext 中读取了表单上下文：

const formItemContext = useContext(FormItemInputContext);
const { hasFeedback, status: contextStatus, feedbackIcon } = formItemContext;

随后通过 getMergedStatus(contextStatus, customStatus) 合并，见 generateSinglePicker.tsx。这意味着：

• 当你把 DatePicker 放进 <Form.Item> 且 Form.Item 校验失败（validateStatus 为 error）时，选择器会自动呈现出红色 error 状态，无需手写 status；
• 若同时显式传入了 status，则显式值优先生效；
• 若表单开启 hasFeedback（如 <Form.Item hasFeedback>），反馈图标会经由 suffixIcon 相关逻辑参与后缀插槽的组装，使日期选择器的日历图标位置能够显示校验反馈图标。

简而言之：demo 展示的是手动声明状态，而 Form 场景是让状态随校验自动出现，两种方式最终都汇入同一套 ant-picker-status-* 类与 token 驱动的样式管线，表现完全一致。

实践建议与边界

• 取值纪律：只使用 error | warning（或空值），不要依赖 success / validating 在 DatePicker 上的样式表现，后者未在日期选择器样式中定义。
• 表单场景优先交给 Form.Item：当状态完全由校验结果决定时，让 Form 上下文自动驱动即可，避免在受控组件里重复维护一份可能不同步的状态值。
• 与 disabled 组合时预期要明确：禁用态不会展示状态色；若业务上既要禁用又要提示，应改用下方说明文字或 Tooltip，而非依赖红框。
• 样式定制入口：状态色取自全局设计令牌 colorError / colorWarning / colorErrorAffix / colorWarningAffix，可通过 ConfigProvider 的主题令牌统一调整，改动后 DatePicker 的状态色即随之变化。

小结

status 是 antd 输入类组件统一的“语义状态开关”：在 DatePicker 上声明 error 或 warning，即可获得与 Input 等组件完全一致的红色/橙色警示视觉，且天然适配四种 variant 形态。其背后是 statusUtils.getStatusClassNames/getMergedStatus 的类名映射、ant-picker-status-* 约定以及 genPickerStatusStyle 的 token 化配色共同支撑；与 Form 的 FormItemInputContext 打通后，还能让校验错误自动映射为选择器状态。掌握这一属性，可以让日期选择在表单校验、合规提醒等场景中保持整库输入组件一致的体验与维护成本。