企业官网建设流程全解析

• 前端
• UI组件

在 React 生态中，"受控组件"（Controlled Component）与"非受控组件"（Uncontrolled Component）是表单类组件最重要的设计范式之一。rsuite 的DatePicker同时支持这两种模式：通过value+onChange将组件状态交由外部接管，或通过defaultValue让组件自行维护初始值。本文以 rsuite 官方文档中的 controlled 示例 为骨架，结合DatePicker源码、useControlledhook 实现与官方测试用例，帮助你彻底理解 DatePicker 的值管理机制，并能在实际项目中正确选择受控与非受控方案。

一、官方示例：同一页面展示两种模式

rsuite 文档在 DatePicker 组件页 中提供了一个经典的对照示例：同一个页面渲染两个 DatePicker，一个受控、一个非受控，便于直观对比二者差异。

import { DatePicker, Stack } from 'rsuite'; const App = () => { const [value, setValue] = React.useState(new Date()); const handleChange = (value, event) => { setValue(value); console.log('Controlled Change', value); }; return ( <Stack spacing={10} direction="column" alignItems="flex-start"> <label>Controlled Value:</label> <DatePicker value={value} onChange={handleChange} /> <label>Uncontrolled Value:</label> <DatePicker defaultValue={new Date()} /> </Stack> ); }; ReactDOM.render(<App />, document.getElementById('root'));

这个示例包含了理解 DatePicker 值管理所需的全部核心要素：

• 受控模式：<DatePicker value={value} onChange={handleChange} />。组件显示什么值完全由外部value决定，用户选择新日期后通过onChange通知外部更新value，再通过props回流到组件；
• 非受控模式：<DatePicker defaultValue={new Date()} />。只需提供初始值defaultValue，此后组件内部自行维护状态，无需外部参与；
• onChange的签名：(value, event) => void，第一个参数是新的Date值，第二个参数是触发变化的原生SyntheticEvent事件对象。

二、受控与非受控：何时选用哪种模式

2.1 受控模式（Controlled）

当你需要"单向数据流"管理日期值时，选择受控模式。典型场景包括：

• 日期值需要与表单状态管理库（如 Form、Redux、Zustand）同步；
• 需要在用户选择后对值做二次加工（如格式化、联动其他组件、限制选择范围）；
• 需要支持"外部程序化改值"（例如点击"重置"按钮把日期恢复到某一天）。

受控模式下，组件的行为遵循以下契约：

1. 显示值始终等于props.value，用户操作不会直接改变显示值；
2. 用户选择新日期时，组件调用onChange(newValue, event)，由外部决定是否以及如何更新value；
3. 如果外部没有更新value（例如onChange中丢弃了值），组件显示值保持不变——这正是受控组件的核心特征，也是它与非受控组件最本质的区别。

2.2 非受控模式（Uncontrolled）

当日期值属于"局部 UI 状态"、无需被外部读取或干预时，选择非受控模式更简洁：

• 初始值通过defaultValue传入；
• 之后用户选择的日期由组件内部state维护；
• 外部仍可通过onChange旁听（监听）值的变化，但无需回写。

2.3 关于受控模式中的onChange逻辑

在受控示例中，handleChange内执行了setValue(value)与console.log两件事。需要特别强调的是：onChange只是"通知"，并不是"设置"。真正让组件值变化的，是外部调用setValue后触发重新渲染、将新的value通过 props 传回组件。若你的onChange只是打日志而不更新状态，受控 DatePicker 会"看起来点了没反应"，这正是受控组件的预期行为。

三、源码级解析：DatePicker 的值是如何被管理的

3.1 类型契约：FormControlBaseProps

DatePicker的 props 接口继承自FormControlBaseProps<Date | null>，见 DatePicker.tsx：

export interface DatePickerProps extends PickerBaseProps<DatePickerLocale>, FormControlBaseProps<Date | null>, DeprecatedProps { ... }

而FormControlBaseProps在 src/internals/types/form.ts 中定义了表单类组件的统一值契约：

export interface FormControlBaseProps<T = InputHTMLAttributes<HTMLInputElement>['value']> { /** Name of the form field */ name?: string; /** Initial value */ defaultValue?: T; /** Current value of the component. Creates a controlled component */ value?: T; /** Set the component to be disabled and cannot be entered */ disabled?: boolean; /** Render the control as plain text */ plaintext?: boolean; /** Make the control readonly */ readOnly?: boolean; /** * Called after the value has been changed */ onChange?: (value: T, event: SyntheticEvent) => void; }

从类型定义可以看出两个关键点：

1. value的类型是Date | null：DatePicker 允许受控值为null，用于表达"未选择日期"的状态（详见下文第五节的清空场景）；
2. value注释明确写着 "Creates a controlled component"：一旦传入value，组件即进入受控模式——这与 React 官方对受控 input 的约定完全一致。

3.2 核心机制：useControlled Hook

DatePicker组件内部通过useControlled来同时支持两种模式，见 DatePicker.tsx：

const [value, setValue] = useControlled(valueProp, defaultValue);

该 hook 的完整实现位于 src/internals/hooks/useControlled.ts：

export function useControlled<V = any, D = V>(controlledValue: V, defaultValue: D) { const controlledRef = useRef(false); controlledRef.current = controlledValue !== undefined; const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue); // If it is controlled, this directly returns the attribute value. const value = controlledRef.current ? controlledValue : uncontrolledValue; const setValue = useCallback( nextValue => { // Only update the value in state when it is not under control. if (!controlledRef.current) { setUncontrolledValue(nextValue); } }, [controlledRef] ); return [value, setValue, controlledRef.current] as [...]; }

这段实现值得逐行拆解，它揭示了 rsuite 组件受控/非受控切换的全部秘密：

关键结论：rsuite 判定"是否受控"的依据是valueprop 是否为undefined。也就是说：

• 传value={undefined}（或不传）→ 非受控，defaultValue生效；
• 传value={new Date(...)}或value={null}→ 受控，defaultValue被忽略。

3.3 值更新链路：updateValue

在 DatePicker.tsx 中，所有"确定新日期"的路径（点击 OK 按钮、选择快捷范围、清空、输入框修改）最终都汇聚到updateValue：

const updateValue = (event: React.SyntheticEvent, date?: Date | null, closeOverlay = true) => { const nextValue = typeof date !== 'undefined' ? date : calendarDate; setCalendarDate(nextValue || startOfToday()); setValue(nextValue); if (nextValue !== value) { onChange?.(nextValue, event); } if (closeOverlay !== false) { handleClose(); } };

注意其中setValue(nextValue)的行为在两种模式下截然不同：

• 非受控模式：setValue会更新内部 state，日期随即反映到输入框中；
• 受控模式：setValue是空操作，真正让界面更新的是外部收到onChange(nextValue, event)后回传的新value。若外部不回传，界面保持旧值（官方测试用例 DatePicker.spec.tsx 中专门验证了这一行为，见下文第四节）。

onChange中还有一个细节：if (nextValue !== value)的引用比较，意味着只有当新值与当前值不是同一个Date引用时才触发onChange，避免无意义的重复回调。

四、测试用例验证：受控行为是"锁死"的

rsuite 为受控/非受控行为编写了专门的单元测试，位于 src/DatePicker/test/DatePicker.spec.tsx，可以直接作为行为规范的"活文档"：

测试一：受控值不可被用户操作改变（第 443-460 行）：

it('Should not change for the value when it is controlled', () => { const onChange = vi.fn(); render( <DatePicker format="yyyy-MM-dd" value={parseISO('2018-01-05')} onChange={onChange} defaultOpen /> ); fireEvent.click(screen.getByRole('gridcell', { name: '06 Jan 2018' })); fireEvent.click(screen.getByRole('button', { name: /ok/i })); expect(onChange).toHaveBeenCalledTimes(1); expect(screen.getByRole('textbox')).to.have.value('2018-01-05'); });

这个测试精确刻画了受控组件的契约：用户点击了 1 月 6 日并点了 OK，onChange被调用了一次，但由于外部没有更新value，输入框中的值仍然是2018-01-05。"onChange 会被触发，但显示值不会被用户操作改变"——这是判断一个组件是否为受控组件的黄金标准。

测试二：受控 value 直接驱动显示（第 541-548 行）：

it('Should accept controlled value', () => { render(<DatePicker value={new Date('7/11/2021')} open format="yyyy-MM-dd" />); expect(screen.getByRole('textbox')).to.have.value('2021-07-11'); expect(screen.getByRole('grid', { name: 'Jul 2021' })).to.contain( screen.getByRole('gridcell', { name: '11 Jul 2021', selected: true }) ); });

验证了受控value直接决定输入框文本与日历面板的高亮选中日期。

测试三：受控值允许为 null（清空场景）（第 550-559 行）：

it('Should be a controlled value, null is allowed', () => { const { rerender } = render( <DatePicker value={new Date('6/10/2021')} open format="yyyy-MM-dd" /> ); expect(screen.getByRole('textbox')).to.have.value('2021-06-10'); rerender(<DatePicker value={null} open format="yyyy-MM-dd" />); expect(screen.getByRole('textbox')).to.have.value(''); });

说明受控模式下将value设为null，输入框会显示为空（清空效果）。这对应源码中handleClean回调的updateValue(event, null)分支（DatePicker.tsx）。

五、进阶实践：受控模式下的常见场景

5.1 与表单集成：null 值表达"未选择"

由于FormControlBaseProps<Date | null>允许null，在表单校验场景中可以约定null表示"尚未选择"：

const [formValue, setFormValue] = React.useState({ birthday: null // 未选择 }); <DatePicker value={formValue.birthday} onChange={(date) => setFormValue(prev => ({ ...prev, birthday: date }))} />

配合shouldDisableDate等 props 可以构建复杂的可用日期约束，而这些约束同样作用于受控与非受控两种模式（源码中 isDateDisabled 与updateValue独立工作，互不干扰）。

5.2 外部程序化改值

受控模式天然支持"从组件外部改值"：

<Button onClick={() => setValue(new Date())}>回到今天</Button> <DatePicker value={value} onChange={(v) => setValue(v)} />

5.3 onChange 双参数：value 与 event

onChange的第二个参数是原生事件对象，在需要区分"用户点击日期"还是"清空操作"等不同触发来源时非常有用。官方测试（如 DatePicker.spec.tsx）也验证了onChange.mock.calls[0][0]是一个Date实例、第二参数为事件对象。

5.4 混合使用 defaultValue 与 onChange

非受控模式下仍然可以传入onChange监听变化：

<DatePicker defaultValue={new Date()} onChange={(value, event) => console.log('用户选择了', value)} />

此时onChange只做通知不做回写，组件由内部 state 驱动，是最轻量的"默认值 + 监听"组合。

六、使用建议与注意事项

1. 判定依据是value !== undefined：传入value={null}会让组件进入受控模式（且显示为空值），这与不传value（非受控、空初始）在行为上有微妙差异——前者外部必须持续管理状态，后者组件自持。请勿混淆二者；
2. 受控与非受控不要混用：不要在受控模式下依赖defaultValue生效，也不要期望非受控组件能通过外部value改值；
3. 引用比较：onChange触发依赖nextValue !== value的引用比较，更新状态时若传入了与原值相同的Date引用，将不会触发onChange；
4. 清空语义：受控模式下如需支持"清空"，请将value置为null，并确保cleanable（默认true）未被关闭，且组件非readOnly状态，否则清空按钮不会显示（见 DatePicker.tsx 的showCleanButton计算）；
5. 深入阅读：感兴趣的读者可以继续研读 useControlled 源码、DatePicker 值管理实现 以及 DatePicker 完整测试套件，这一模式在 rsuite 几乎所有表单组件（如 CheckPicker、TreePicker、InputNumber 等）中复用，掌握后可以一通百通。

七、小结

• 受控模式（传value+onChange）：值由外部唯一掌控，onChange只是通知，界面值不会因用户操作而"擅自"改变；
• 非受控模式（传defaultValue）：初始值由外部指定，此后内部 state 自行驱动，onChange可选监听；
• 判定机制：useControlled以value !== undefined区分两种模式，受控时内部setValue为空操作，从而保证单向数据流不被破坏；
• 官方测试：DatePicker.spec.tsx 中的三个用例分别锁定了"受控值不可被用户改动""受控值直接驱动界面""受控值可为 null"三条核心行为规范。

理解并善用这两种模式，是写出健壮、可维护的 rsuite 日期选择表单的第一步。

• 前端
• UI组件