深入解析 @radix-ui/react-use-controllable-state：Radix 可控/非可控状态内核的原理与演进

导读

@radix-ui/react-use-controllable-state 是 Radix Primitives（packages/react/use-controllable-state）内部的状态管理核心 Hook，为整个组件库统一实现了「受控（controlled）与不受控（uncontrolled）双模式」能力——所有 Radix 组件（Switch、Dialog、Select 等）的 value/defaultValue、checked/defaultChecked 这类 API 都由它承载。本篇文章以该包官方 CHANGELOG（packages/react/use-controllable-state/CHANGELOG.md）为主线，逐版本解读其从 1.2.0 到 1.2.6 的演进脉络，并结合源码剖析 useControllableState 与 useControllableStateReducer 的实现原理、开发期校验、RSC 兼容性以及 provenance 发布策略。读完你将能：理解受控/不受控状态机的完整工作流程与边界条件，掌握包内导出的两个 Hook 的适用场景与调用约定，并看懂依赖变更背后的兼容性逻辑。

一、包概览：一个内部 Hook 撑起整个组件库的受控模式

与 Radix 的其他公开 API 包不同，react-use-controllable-state 的 README（packages/react/use-controllable-state/README.md）明确声明它是 internal utility，不面向公共使用。它是 Radix 众多组件「可选受控」设计的核心支撑：

• 包入口 packages/react/use-controllable-state/src/index.ts 仅导出两个 API：useControllableState 与 useControllableStateReducer；
• 消费方遍布整个组件库，例如 Switch 组件的源码 packages/react/switch/src/switch.tsx 中：

const [checked, setChecked] = useControllableState({
  prop: checkedProp,
  defaultProp: defaultChecked ?? false,
  onChange: onCheckedChange,
  caller: SWITCH_NAME,
});

这种「prop + defaultProp + onChange + caller」四参数模式，几乎贯穿所有 Radix 交互组件。

从包配置（packages/react/use-controllable-state/package.json）看，它依赖三个 workspace 内部包：

依赖	用途
@radix-ui/primitive	提供 IS_DEVELOPMENT 等开发期常量与基础工具
@radix-ui/react-use-effect-event	提供 useEffectEvent，让 onChange 回调始终引用最新闭包
@radix-ui/react-use-layout-effect	提供布局副作用 Hook（在无 useInsertionEffect 环境回退）

版本上当前为 1.2.6，peer 依赖支持 React ^16.8 || ^17.0 || ^18.0 || ^19.0（见 package.json）。

二、1.2.0：性能优化、缩小 bug 面与误用告警（#3455）

CHANGELOG 记录的 1.2.0 改动是：

Minor improvements to useControllableState to enhance performance, reduce surface area for bugs, and log warnings when misused (#3455)

这条「minor improvements」背后，对应的是当前源码 packages/react/use-controllable-state/src/use-controllable-state.tsx 中的三个核心设计。

2.1 受控/非受控的判定与「轻量 setter」

useControllableState 的核心逻辑只有短短几十行：

const [uncontrolledProp, setUncontrolledProp, onChangeRef] = useUncontrolledState({
  defaultProp,
  onChange,
});
const isControlled = prop !== undefined;
const value = isControlled ? prop : uncontrolledProp;

• 受控模式：调用方传入 prop 时，组件不再持有内部状态，value 完全由外部 prop 决定；
• 非受控模式：prop === undefined 时退回内部 useState(defaultProp)。

setter 则用 useCallback 包了一层，关键在受控分支：

const setValue = React.useCallback<SetStateFn<T>>(
  (nextValue) => {
    if (isControlled) {
      const value = isFunction(nextValue) ? nextValue(prop) : nextValue;
      if (value !== prop) {
        onChangeRef.current?.(value);
      }
    } else {
      setUncontrolledProp(nextValue);
    }
  },
  [isControlled, prop, setUncontrolledProp, onChangeRef],
);

两点细节值得注意：

1. 受控时也支持函数式更新：nextValue 可以是 (prev) => next 形式，内部用 nextValue(prop) 求值，与 useState 的语义保持一致；
2. 值未变化不触发 onChange：value !== prop 时才会调用 onChange，避免多余渲染与事件抖动。

2.2 内部 useUncontrolledState：让 onChange 永不陈旧

非受控分支的辅助 Hook 是理解「少 bug」的关键（见 use-controllable-state.tsx）：

const onChangeRef = React.useRef(onChange);
useInsertionEffect(() => {
  onChangeRef.current = onChange;
}, [onChange]);

React.useEffect(() => {
  if (prevValueRef.current !== value) {
    onChangeRef.current?.(value);
    prevValueRef.current = value;
  }
}, [value, prevValueRef]);

• onChange 不直接进入任何 effect 依赖数组，而是先写入 ref；即使用户每次渲染传入新闭包，也不会引发重复 effect；
• 回调的触发点收敛到「值真正变化」时，配合 prevValueRef 去重；
• 顶部还有一段「防止打包器优化」的兼容代码：优先使用 React 19 的 useInsertionEffect，否则回退到 useLayoutEffect（use-controllable-state.tsx）。

2.3 开发期「受控↔非受控切换」告警

源码中用 IS_DEVELOPMENT 常量（定义于 packages/core/primitive/src/internal/is-development.true.ts）包裹了一段仅开发环境生效的检测逻辑：

if (IS_DEVELOPMENT) {
  const isControlledRef = React.useRef(prop !== undefined);
  React.useEffect(() => {
    const wasControlled = isControlledRef.current;
    if (wasControlled !== isControlled) {
      console.warn(
        `${caller} is changing from ${from} to ${to}. Components should not switch from controlled to uncontrolled (or vice versa). ...`,
      );
    }
    isControlledRef.current = isControlled;
  }, [isControlled, caller]);
}

这是 React 官方一直强调的组件设计准则：一个组件在其生命周期内不应从受控切换为非受控（或反之）。caller 参数正是用来在告警消息里标注具体组件名的。测试用例也专门覆盖了这一行为——在 use-controllable-state.test.tsx 中，UnstableComponent 通过 setChecked(undefined) 将 checked 变为 undefined 后，断言 console.warn 被调用，并精确校验了告警文案：

Checkbox is changing from controlled to uncontrolled. Components should not switch from controlled to uncontrolled (or vice versa). Decide between using a controlled or uncontrolled value for the lifetime of the component.

三、1.2.1 → 1.2.3：依赖收敛与仓库元数据

这三个补丁版本内容相对简单，但揭示了发布节奏与工程细节：

• 1.2.1：仅更新依赖 @radix-ui/react-use-effect-event@0.0.1，说明当时刚引入 useEffectEvent 这一依赖；
• 1.2.2：依赖升级到 @radix-ui/react-use-effect-event@0.0.2；
• 1.2.3：所有 package.json 增加 repository.directory 字段（对应 package.json 中的 "directory": "packages/react/use-controllable-state"），便于 monorepo 下工具链定位源码；同时依赖升级到 0.0.3 与 1.1.2。

可以看到，本包自身的逻辑在这几个版本中保持稳定，改动集中在依赖链的同步。

四、1.2.4：开发期告警彻底从生产包剥离

1.2.4 的变更值得单独说明：

Fix dev-only checks with conditional exports to drop dev-warnings from production builds.

这条改动与 IS_DEVELOPMENT 的解析机制密切相关。@radix-ui/primitive 包通过 is-development.true.ts 与 is-development.false.ts 两个入口配合 conditional exports 解析：

// is-development.true.ts
export const IS_DEVELOPMENT = true;

在生产构建（process.env.NODE_ENV === 'production'）时解析为 false 常量，配合 if (IS_DEVELOPMENT) 这类常量折叠（constant folding），打包器可在压缩阶段直接移除整段 dev-only 代码块（源码注释也明确写了 "Bundlers should be able to remove the code block entirely in production."，见 use-controllable-state.tsx）。因此 1.2.4 修复的正是此前 dev-warning 可能残留在生产 bundle 中的问题。

顺带一提，同一个模式也被 useControllableStateReducer 复用（见 use-controllable-state-reducer.tsx），它在开发期同样会检测受控状态切换并输出相同的告警文案。

五、1.2.5：Provenance 溯源签名与 CI 发布

1.2.5 的内容不涉及任何功能代码：

Republish through CI to attach provenance attestations. The previous versions ... were published manually outside of CI and therefore shipped without provenance; this patch re-releases the same code through the CI pipeline so every package includes an attestation.

这是供应链安全（supply chain security）层面的工程实践：npm 的 provenance 发布（--provenance 标志）利用 Sigstore 生成不可抵赖的构建来源证明。此版本只是「重新发布同样代码」，但让每个产物都附带来自 CI 的 attestation，让下游可以验证「这个包确实是由官方 CI 从官方仓库构建的」。该版本还同步升级了 @radix-ui/primitive@1.1.7、@radix-ui/react-use-effect-event@0.0.4、@radix-ui/react-use-layout-effect@1.1.3。

六、1.2.6：回滚破坏性变更，保障 RSC 兼容性

最新版本 1.2.6 的说明是：

Reverted breaking changes that caused compatibility issues with React Server Components. Updated dependencies: @radix-ui/react-use-effect-event@0.0.5, @radix-ui/react-use-layout-effect@1.1.4

这提示 1.2.x 中期曾在 RSC（React Server Components）兼容性上做过激进调整，发现会破坏兼容性后又回滚。结合仓库内对 RSC 的持续投入（根目录 scripts/rsc-compatibility.rsc.test.ts 即用于验证组件在 RSC 环境下的行为），可以推断：react-use-controllable-state 必须保证既能跑在客户端组件，也能在服务端渲染阶段安全工作。源码中 IS_DEVELOPMENT 包裹条件 Hook、useInsertionEffect 回退到 useLayoutEffect 等设计，都与「在非客户端环境不执行多余副作用」的目标一致。

七、进阶：useControllableStateReducer —— 带状态机的受控状态

除基础 Hook 外，index.ts 还导出了 useControllableStateReducer（实现见 use-controllable-state-reducer.tsx），适用于需要以 reducer/状态机方式管理复杂受控状态的组件（如 Tabs、Select 等）。它把「可选的受控 prop」与 useReducer 结合：

• 签名：useControllableStateReducer(reducer, { prop, defaultProp, onChange, caller }, initialArg, init?)，返回 [state, dispatch]，其中 reducer 接收的 prevState 总是包含一个 state: T 字段；
• 内部约定：reducer 的返回值必须是 S & { state: T } 形态，非受控时由 reducer 推进内部 state，受控时对外输出 { ...internalState, state: controlledState }；
• 双向同步：受控模式下若 reducer 产出的 next.state 与当前 prop 不一致，会立即调用 onChange 通知外部（见 use-controllable-state-reducer.tsx）；反过来，当外部 prop 变化时，通过内部私有的 SYNC_STATE action（Symbol('RADIX:SYNC_STATE')）把最新受控值同步进 reducer 内部状态，保证后续 reducer 计算基于正确基线（见 use-controllable-state-reducer.tsx）；
• onChange 稳定性：onChange 通过 useEffectEvent(onChangeProp) 包装，既避免陈旧闭包，又不把外部回调放进依赖数组（use-controllable-state-reducer.tsx）。

八、版本演进总结与使用要点

版本	核心变化	性质
1.2.0	性能优化、缩小 bug 面、增加误用告警（#3455）	功能
1.2.1 / 1.2.2	依赖 react-use-effect-event 版本跟进	依赖
1.2.3	增加 repository.directory 元数据	工程
1.2.4	dev-only 校验随 conditional exports 在生产构建中剥离	功能修复
1.2.5	CI 重新发布以附加 provenance attestation	供应链
1.2.6	回滚破坏性变更，修复 RSC 兼容；依赖升级	兼容性

最后给出几条可直接落地的实践结论：

1. 组件 API 设计：对外暴露 value/defaultValue、checked/defaultChecked 这类成对属性时，直接用 useControllableState 即可自动获得「受控/非受控/受控切换告警」三种行为，无需自行维护两套状态逻辑；
2. 告警消息定制：务必传入 caller（如组件名常量），否则开发期告警无法定位到具体组件；
3. 事件回调语义：onChange 只在值真正变化时触发一次，且受控模式下以「值是否变化」为唯一判据；
4. 生产包体积：依赖 IS_DEVELOPMENT 常量折叠，dev 告警代码在 production 构建中会被整体移除，无需手动做环境分支；
5. 复杂交互组件：需要以事件/action 方式驱动状态（例如多步切换、方向键导航）时，改用 useControllableStateReducer 获得 reducer 化的受控能力。

要深入研究实现细节，可继续阅读 use-controllable-state.tsx、use-controllable-state-reducer.tsx 以及对应测试 use-controllable-state.test.tsx。