Ant Design ColorPicker 受控模式详解：value、onChange 与 onChangeComplete 的正确用法

导读

在 React 生态中，"受控组件"意味着展示值完全由外部 state 决定、变更事件驱动 state 更新。Ant Design 的 ColorPicker（取色器）为这一场景提供了 value / onChange / onChangeComplete 三件套，其中存在一个容易踩坑的细节：当用 onChangeComplete 而非 onChange 来受控同步颜色时，组件会"锁定"展示颜色。本文以 components/color-picker/demo/controlled.md 对应的受控模式示例为主线，结合组件源码与测试用例，讲清两种受控写法的差异、底层状态合并机制，以及如何正确写出类型安全、行为可预期的受控 ColorPicker。

案例总览：演示的两种受控写法

文档 controlled.md 对示例的核心说明为：

通过 value 和 onChange 设置组件为受控模式，如果通过 onChangeComplete 受控则会锁定展示颜色。 （Set the component to controlled mode. Will lock the display color if controlled by onChangeComplete.）

对应的完整演示代码位于 controlled.tsx：

import React, { useState } from 'react';
import { ColorPicker, Space } from 'antd';
import type { ColorPickerProps, GetProp } from 'antd';

type Color = GetProp<ColorPickerProps, 'value'>;

const Demo: React.FC = () => {
  const [color, setColor] = useState<Color>('#1677ff');

  return (
    <Space>
      <ColorPicker value={color} onChange={setColor} />
      <ColorPicker value={color} onChangeComplete={setColor} />
    </Space>
  );
};

export default Demo;

同一个 color state 被两个取色器共用，区别只在一行回调：

写法	行为
value={color} onChange={setColor}	每次颜色变化（含面板内拖拽过程中的实时变化）都同步回 state，触发块/文字实时跟随鼠标取色结果
value={color} onChangeComplete={setColor}	只在一次选色结束（如松手/提交）时才同步 state，因此在拖拽过程中外部 value 未变，展示颜色被"锁定"不动

这正是受控组件价值所在：展示状态与业务 state 完全单向绑定。官方 API 表（见 index.en-US.md）对 onChangeComplete 的注释也印证了这一点："Called when color pick ends. Will not change the display color when value controlled by onChangeComplete"。

受控基础：value / defaultValue / onChange / onChangeComplete

受控模式依托以下四个核心 API（类型定义见 interface.ts）：

属性	说明	类型	默认值	引入版本
value	当前颜色值（受控），为 null 时表现为"已清空"状态	string | AggregationColor | null | LineGradientType[]	-	-
defaultValue	非受控时的初始颜色	同上	-	-
onChange	颜色值变化时触发	(value: AggregationColor, css: string) => void	-	-
onChangeComplete	一次选色结束时触发	(value: AggregationColor) => void	-	5.7.0

其中颜色值 value 的类型可写为：

type SingleValueType = AggregationColor | string;
type LineGradientType = { color: SingleValueType; percent: number }[];
type ColorValueType = SingleValueType | null | LineGradientType;

也就是说 value 既可以是 '#1677ff' 这类 CSS 字符串，也可以是组件导出的 AggregationColor 对象；5.20.0 起还支持渐变配色，此时传入按百分比排列的颜色点数组。传入任意合法值后，组件内部会经 util.ts 的 generateColor 统一收敛为 AggregationColor 实例，因此 demo 中把 state 初始化为字符串 '#1677ff' 完全可行。

两点回调签名差异值得注意：

• onChange 额外回传 css 字符串（即当前颜色的 CSS 表示），方便在无需解析对象时直接使用，如 onChange={(_, css) => save(css)}；
• onChangeComplete 只回传颜色对象，且语义是"整次选色动作的收尾"，而非过程中的每一次微调。

若想让非受控场景（只给 defaultValue）也能拿到回调，两套事件同样会按上述节奏触发——回调机制与是否受控无关，受控与否只取决于你是否传入了 value 并在回调里 setState。

两种受控写法的差异与"锁色"机制

回到 demo：为何第二个取色器用 onChangeComplete 同步就会"锁定展示颜色"？

原因可归纳为一条因果链：

1. 受控展示由外部 value 决定：组件内部通过 useControlledState(defaultValue, value) 合并内外状态，一旦外部传入 value，展示色就跟随外部 state（合并逻辑见 useModeColor.ts）；
2. onChange 高频触发、onChangeComplete 低频触发：在面板拖拽选色过程中，组件持续派发 onChange，而只在交互结束时派发 onChangeComplete；
3. 用 onChangeComplete 做同步 = 拖拽期间外部 state 不更新 → value 保持旧值 → 展示色被"锁"在旧值上，直到松手提交、state 被写回，展示色才跳变到新值。

源码层面的直接证据在 ColorPicker.tsx：内部变更处理函数 onInternalChange 无论是否处于拖拽都会 setColor 并触发外部 onChange，但调用 onInternalChangeComplete 前有一个关键守卫 if (!changeFromPickerDrag)——只有非拖拽来源（如输入框提交、面板点击）才会在变更瞬间补发完成事件；而面板内的拖拽流程则是由 PanelPicker/index.tsx 在拖拽结束后单独派发完成事件。

测试用例验证"锁色"

受控 + onChangeComplete 的行为在 tests/index.test.tsx 有专门的 controlled with onChangeComplete 用例覆盖，测试渲染 <ColorPicker value="#F00" open onChange={...} onChangeComplete={...} /> 后模拟拖拽：

• 拖拽过程中 onChange 被调用并携带新颜色 rgb(0,255,255)，而 onChangeComplete 未被调用；
• 此时触发块（组件外层的颜色块）样式仍为 rgb(255, 0, 0)，即旧值——展示颜色被锁定；
• 面板弹层内的颜色块则实时跟随操作为 rgb(0,255,255)，便于用户看清正在吸取的颜色；
• 松手（mouseUp）后，因回调并未真正更新外部 state，两处颜色块最终都回到 rgb(255, 0, 0)。

也就是说，"锁定"是受控语义的自然结果：展示色永远等于外部 value，而 onChangeComplete 只在选色结束时才允许你把 value 改掉。如果你的业务需要在拖拽过程中实时反馈选中色（如实时预览应用色），应当使用 onChange={setColor}；如果希望"确认后才生效"（如只在用户松开滑块后落库、避免频繁写存储），onChangeComplete 是更优的受控选择。

底层实现：useControlledState 与 useModeColor

受控逻辑不直接散落在组件体里，而是封装在 hooks/useModeColor.ts 中。该 hook 返回五个值：合并后的颜色、颜色 setter、当前模式（single/gradient）、模式 setter 以及模式选项列表。

其核心动作包括：

• 状态合并：const [mergedColor, setMergedColor] = useControlledState(defaultValue, value)。useControlledState（来自 @rc-component/util）遵循 React 惯例：传了 value 则外部接管，没传则退化为内部 state 并使用 defaultValue 初始化——这正是受控/非受控一键切换的底层来源；
• 颜色类型收敛：postColor 通过 generateColor(mergedColor || '') 把字符串/对象统一成 AggregationColor，并用 cacheColor 处理"清空"后的回显问题（详见 useModeColor.ts）；
• 模式与颜色联动：通过 useEffect 监听颜色变化，渐变颜色自动把模式切到 gradient，纯色则切到 single，保证 mode 与 value 永远一致（useModeColor.ts）。

在 ColorPicker.tsx，主组件把这套结果交给面板渲染：value 传到面板与触发器作为唯一展示来源，setColor 则被包装进 onInternalChange——于是"内部操作 → setState → 外部 onChange → 用户 setState → 外部 value 回流"构成了完整的受控闭环。

用 GetProp 从 Props 推导值类型

demo 里还有一个值得复用的 TypeScript 技巧：

type Color = GetProp<ColorPickerProps, 'value'>;

GetProp 是 Ant Design 从 @ant-design/util/组件工具中导出的类型工具（本仓库中亦见 components/_util/type.ts），作用是从组件 props 类型中"提取"某个属性的类型。这样声明 state 有两大好处：

1. 单一事实来源：颜色类型后续演进（如支持渐变数组、null）时，业务代码自动跟随，无需手写易过时的联合类型；
2. 双向赋值安全：由于 onChange/onChangeComplete 回调参数是 AggregationColor，而 value 同时接受 AggregationColor 与字符串，useState<Color> 初始化为 '#1677ff'、并在回调里 setColor 都能通过类型检查。

在 index.tsx 中，AggregationColor（别名为 Color）与 ColorPickerProps 均从 ColorPicker 入口导出，因此 import type { ColorPickerProps, GetProp } from 'antd' 即可取用。

小结

• 受控取色用 value + 回调：需要"实时跟随"就选 onChange；需要"结束才生效、展示锁色"就选 onChangeComplete；
• "锁色"不是 bug：它是受控组件展示值严格等于外部 value 的必然结果，源码通过 !changeFromPickerDrag 分支控制完成事件的派发时机，测试用例（index.test.tsx）对此有完整断言；
• 类型安全：用 GetProp<ColorPickerProps, 'value'> 提取 state 类型，可同时兼容字符串、AggregationColor 与渐变数组；
• 想要还原这段演示，可直接查看 components/color-picker/demo/controlled.tsx，官方中文/英文 API 文档参见 index.zh-CN.md 与 index.en-US.md。

对比受控模式以外的能力（预设色板、自定义面板渲染、透明度与格式控制等），可继续阅读同目录下的其他示例文档，例如 demo/presets.md、demo/format.md 与 demo/trigger.md。