Reka UI v3.0.0-alpha.0:只发 ESM、data-state 归一化,升级前先跑 codemod
Reka UI(原 Radix Vue)在 2026-11-05 发布 v3.0.0-alpha.0,这是一次 pre-release。仓库:unovue/reka-ui,文档:reka-ui.com,发布说明:v3.0.0-alpha.0。MIT,约 6.9k stars,仓库默认分支仍是 v2。
这个 alpha 的破坏性改动集中:包格式、状态属性、导出路径、组合式函数和底层渲染都在动。
只发 ESM,CJS 工具链先改
v3 只发布 ESM,删除 CJS 构建(#2909)。任何 require('reka-ui') 或依赖 CJS 解析的构建链都会断。
// v3:ESM
import { DialogRoot } from 'reka-ui'
// v2 的 CJS 写法在 v3 不可用
const { DialogRoot } = require('reka-ui')
升级前先确认打包器、测试环境和 Node 配置能处理 ESM。只是应用层改 import 不够,CJS 产物的消费方也要一起改。
data-state 归一到两组轴
组件状态统一到 open / closed 与 checked / unchecked 两组轴(#2914)。自定义 CSS 如果匹配了旧值,需要跟着改。Dialog、Popover、Tooltip、HoverCard 的打开状态变化增加了 change details;Stepper 的 data-state 做了重命名。
[data-state='open'] {}
[data-state='closed'] {}
[data-state='checked'] {}
[data-state='unchecked'] {}
配套 codemod 覆盖 data-state 与 Stepper 重命名(#2915、#2917)。先跑 codemod,再手动检查依赖状态值的样式和测试断言。
按组件子路径导出
v3 增加按组件子路径导出(#2996),resolver 与 Nuxt 模块也支持按组件子路径导入(#2726、#3079)。
import { DialogRoot } from 'reka-ui/Dialog'
import { PopoverRoot } from 'reka-ui/Popover'
这样可以把导入面收窄到具体组件,不必从根入口聚合。使用 Nuxt 模块或 resolver 的项目,需要确认配置已跟上 v3 的子路径规则。
无头组合式函数与 useRender
v3 补齐了一批无头组合式函数:useDialog、usePopover、useTooltip、useHoverCard、useCombobox、useSwitch、useTabs 等,并配套迁移指南。原来只能通过组件使用的行为,现在可以在组合式函数层组织。
渲染层用 useRender 渲染原语替代 Primitive 包装层(#2722、#2788)。这会影响自定义组件对渲染、属性透传和 ref 的处理方式;迁移时不要只改导入,还要检查原有 Primitive 包装逻辑。
滚动锁定、Shadow DOM 与日期能力
滚动锁定与模态行为改用 Base UI 实现,不再依赖 body 上的 pointer-events(#2822、#3070)。依赖 body 样式副作用做弹层互斥的项目,需要重新回归。
其余能力包括:完整 Shadow DOM 支持,含 Root helpers 与 aria-id/label 解析;createHandle() 分离触发器,用于 Popover、Dialog、Menu;CSS transition 感知的退出动画;日期组件支持 Temporal API;构建时生成 Custom Elements Manifest(#3150)。
性能与组件调整
渲染层级方面,日期、数值、表单、简单组件、覆盖层和列表族都改为每个部件一个组件,减少包装层级。Listbox、Collection、RovingFocus 使用键控选择器、缓存集合和委托 roving focus。Select 按需渲染关闭项,并新增 items 属性。Teleport 在关闭时不渲染 portal,也不构建 handle 或 presence 机制。DismissableLayer 改为集中式层栈管理。
组件层面,Calendar 用一个组件统一日、月、年视图(#2921);Color 默认使用对象模型(#2789)。
升级取舍
这是 alpha,破坏性变更多。维护中的生产设计系统、仍依赖 CJS/require 的构建链、固定旧 Nuxt 模块或 resolver 的项目,建议等稳定版。新项目、内部工具,以及已经全 ESM 且能接受 alpha 的项目,可以先跑 codemod,再迁移到按组件子路径导入和新的组合式函数;重点回归滚动锁定、退出动画、Select/Listbox 过滤和自定义 data-state 样式。