radix-vue Drawer 组件 Base UI 对齐修复实战:五阶段实施计划与源码落地深度解析
radix-vue Drawer 组件 Base UI 对齐修复实战:五阶段实施计划与源码落地深度解析
本文以仓库中 2026-04-09-drawer-baseui-parity-fixes.md 实施计划为骨架,围绕 radix-vue(Vue 3 UI 组件库)中 Drawer(抽屉)组件与 Base UI React Drawer 的行为与 API 对齐工作展开。你将掌握:如何在不做整体重构的前提下,通过「表面 API 修复 → 手势数学重写 → 缺失行为补齐 → 测试覆盖 → 验证提交」五个阶段,系统性消除第三方组件移植中的行为差异,并能对照当前仓库源码逐项确认每一项修复的实际落点。
一、计划背景:一次代码评审驱动的对齐工程
1.1 上下文与目标
本计划文档是一次代码评审之后的跟进(Follow-up):评审对象是仓库中 Drawer 组件与 mui/base-ui packages/react/src/drawer(Base UI 的 React Drawer 实现)的对照。评审共提出 6 个 Critical(严重)+ 10 个 Important(重要)+ 若干 Minor(次要) 问题。
计划的核心目标非常明确:
Bring the Vue Drawer port into behavioral + API parity with Base UI's React Drawer where it matters for correctness, without a full viewport-extraction refactor.
即:在不进行整体 viewport 提取式重构的前提下,让 Vue 移植版的 Drawer 在行为与 API 两个维度上与 Base UI 对齐——凡是影响正确性的差异都必须消除。
1.2 三条关键策略
计划的执行路线可以概括为三个字:就地修、别名补、逐行移植。
| 策略 | 说明 |
|---|---|
| 就地修复行为差距 | 在既有组件内直接修正(例如 C1 采用功能性而非结构性方案解决) |
| 通过 re-export 补充 API 对齐别名 | 新增 Backdrop / Popup / Viewport 三个 Base UI 命名别名 |
| 逐行移植数学逻辑 | snap-release 数学从 Base UI DrawerViewport.tsx 逐行移植;useSwipeDismiss.ts 的 CSS 变量符号处理重写为直接使用阻尼后的增量 |
1.3 执行模式:可分阶段提交
计划要求采用**内联分阶段(Inline phases)**执行,每个阶段之间独立提交:
- 每个阶段都能独立构建;
- 一旦某阶段失败,代码树仍保持干净、可回退;
- 提交按阶段进行,便于 review 与 bisect(二分定位问题)。
这与仓库 packages/core/src/Drawer/ 目录下的实际文件一一对应,我们会在后续每章给出源码落点。
二、Phase 1 — 表面 API 修复(低风险)
这一阶段不涉及手势数学,风险最低,主要围绕组件 Props / Emits / 导出 API 的兼容性展开。
2.1 snapToSequentialPoints 默认值翻转:true → false
计划要求在 DrawerRoot.vue 中把 snapToSequentialPoints 的默认值从 true 改为 false。
在 DrawerRoot.vue 的 withDefaults 中可以看到该改动已落地:
const props = withDefaults(defineProps<DrawerRootProps>(), {
open: undefined,
defaultOpen: false,
modal: true,
swipeDirection: 'down',
snapPoints: undefined,
snapPoint: undefined,
defaultSnapPoint: undefined,
snapToSequentialPoints: false, // 默认值:false(最近距离吸附)
})
对应地,Props 的 JSDoc 注释也明确了两种模式的语义差异(见 DrawerRoot.vue):
true:吸附到下一个顺序 snap point(一次只走一步,依赖滑动速度);false:按距离吸附到最近的 snap point(默认行为)。
语义影响:默认关闭顺序模式后,普通用户拖拽释放时会落到"距离最近的吸附点",而不是逐级跳转,这更符合 Base UI 的默认手感。
2.2 modal 类型扩展:boolean | 'trap-focus'
原 modal 仅是 boolean,计划将其拓宽为联合类型。在 DrawerRoot.vue 中:
export type DrawerModal = boolean | 'trap-focus'
三种取值语义(见 Props 定义 DrawerRoot.vue):
| 取值 | 行为 |
|---|---|
true(默认) |
模态:焦点陷阱 + 滚动锁定 + 外部点击关闭 |
'trap-focus' |
只做焦点陷阱,但允许外部指针事件(适用于非模态侧边面板) |
false |
完全非模态 |
该类型被 DrawerRootContext.modal 以及 DrawerContentImpl 接收,后者在 modal: 'trap-focus' 分支下需要处理「trapFocus 为 true + disable-outside-pointer-events 为 false」的组合(计划第 17 行)。
2.3 update:open 签名变更:[value, details?] 携带 reason
计划的第三项 API 改动是让 update:open 事件携带可选的关闭原因。当前 DrawerRoot.vue 中的 Emits 定义:
export type DrawerRootEmits = {
'update:open': [value: boolean, details?: DrawerOpenChangeDetails]
'update:openComplete': [value: boolean]
'update:snapPoint': [value: DrawerSnapPoint | null]
}
DrawerOpenChangeReason 枚举了所有可能的开合原因(DrawerRoot.vue):
export type DrawerOpenChangeReason
= | 'swipe' // 手势滑动关闭
| 'escape-key' // 按 Esc
| 'outside-press'// 点击外部
| 'click'
| 'cancel'
| 'trigger-press'// 触发器按下
| 'close-press' // 关闭按钮按下
实现上,handleOpenChange 只有在原因存在时才附加 details(DrawerRoot.vue):
function handleOpenChange(value: boolean, reason?: DrawerOpenChangeReason) {
if (open.value === value)
return
const details: DrawerOpenChangeDetails | undefined = reason ? { reason } : undefined
uncontrolledOpen.value = value
emit('update:open', value, details)
}
实战价值:消费方可以用
@update:open="(v, d) => d?.reason === 'swipe' && ..."区分用户是通过滑动、Esc 还是点击外部关闭抽屉,从而实现差异化的业务埋点或提示逻辑。
2.4 initialFocus / finalFocus:聚焦行为可控化
计划要求 DrawerContent.vue 新增 initialFocus / finalFocus 两个 Props 并接入 FocusScope。在 DrawerContentImpl.vue 中两者的类型均为 boolean | HTMLElement | null:
true(默认):聚焦内部第一个可聚焦元素(initialFocus)/ 聚焦触发器(finalFocus);false:不做任何聚焦;- 元素引用:聚焦到指定元素。
在 onMountAutoFocus 中可以看到实际分支处理(DrawerContentImpl.vue):当 initialFocus === false 时阻止默认聚焦;当传入 HTMLElement 时阻止默认并显式 focus(props.initialFocus, { select: true })。DrawerContentImpl 负责接受并透传这两个 Props,模板层由 FocusScope 的 @mount-auto-focus / @unmount-auto-focus 驱动。
2.5 API 别名:Backdrop / Popup / Viewport
计划的 API 对齐思路是:Base UI 的命名(Backdrop/Popup/Viewport)在 Vue 版中作为别名存在,底层复用同一组件实现。当前 index.ts 已完整落地:
// Base UI alias: Drawer.Popup === DrawerContent
export {
default as DrawerPopup,
type DrawerContentEmits as DrawerPopupEmits,
type DrawerContentProps as DrawerPopupProps,
} from './DrawerContent.vue'
// Base UI alias: Drawer.Backdrop === DrawerOverlay
export {
default as DrawerBackdrop,
type DrawerOverlayProps as DrawerBackdropProps,
} from './DrawerOverlay.vue'
而 DrawerViewport 则是一个新文件(DrawerViewport.vue),当前是一个透传包装:
- 携带
data-drawer-viewport属性,供下游选择器定位; - 转发默认插槽;
- 转发
data-state="open|closed"; - 源码注释明确指出:在 Base UI 中 viewport 拥有手势状态机,而本移植版手势逻辑直接挂在
DrawerContent/DrawerContentImpl上,因此该组件现阶段仅做 API 对齐,并作为未来提取手势逻辑的扩展点。
2.6 parseSnapPoint 容错与活动吸附点缓存
计划要求 useDrawerSnapPoints.ts 中的 parseSnapPoint 对未知单位返回 null(随后被过滤),并缓存解析后的活动吸附点。源码实现见 useDrawerSnapPoints.ts:
function parseSnapPoint(value: DrawerSnapPoint, viewportHeight: number, rootFontSize: number): number | null {
let result: number | null = null
if (typeof value === 'number')
result = (value >= 0 && value <= 1) ? value * viewportHeight : value
else if (value.endsWith('rem'))
result = Number.parseFloat(value) * rootFontSize
else if (value.endsWith('px'))
result = Number.parseFloat(value)
// 未知单位(如 '%'、'vh')与非有限/负值(如 'abcpx' → NaN、'-10px')一律丢弃
if (result == null || !Number.isFinite(result) || result < 0)
return null
return Math.round(result)
}
解析规则回顾:
0 ≤ n ≤ 1→ 视口高度百分比(如0.5即 50vh);n > 1→ 原始像素值;'148px'→ 解析为像素;'30rem'→rem × document.documentElement.fontSize;- 其他字符串(
'%'、'vh'、NaN、负数)→ 返回null被丢弃,防止NaNpx或越界偏移污染解析后的几何数据。
活动吸附点的缓存由 findActiveResolvedPoint() 承担(useDrawerSnapPoints.ts):它不仅按原始值匹配,还支持按解析高度等价匹配(如 '16rem' 与 256、0.5 与 400 互换表示),避免受控场景下释放数学回退到 offset 0 导致错误跳变。
2.7 测试类型修正
计划还包含一个小的工程性修复:Drawer.test.ts 中 SpyInstance → MockInstance(Vitest 较新版本的类型命名调整),并移除 DrawerContentImpl.vue 中临时的 nestedDepth = ? 1 : 0 逻辑(其在 Phase 3 被 nestedOpenDrawerCount 取代)。
三、Phase 2 — 手势数学修复(高价值、中风险)
这是整个计划中技术含量最高的部分,包含三个编号问题:C2、C3、C4,全部指向滑动释放瞬间的数学正确性。
3.1 C2 — 符号约定重写:直接使用阻尼增量
问题:旧实现需要从阻尼后的偏移量反推 sign / offsetX / offsetY,再重建原始增量,符号处理脆弱且易错。
修复方案:新增 applyDirectionalDamping(rawDx, rawDy, allowedDirections),返回 { x, y }:
- 允许方向上的轴线性通过;
- 不允许方向上的轴做 sqrt 阻尼(overshoot 压缩)。
该函数移植自 Base UI useSwipeDismiss.ts(约 140-180 行)。在 useSwipeDismiss.ts 中已落地:
function applyDirectionalDamping(deltaX: number, deltaY: number) {
const exponent = (value: number) => (value >= 0 ? value ** 0.5 : -((Math.abs(value)) ** 0.5))
const dampAxis = (delta: number, allowNegative: boolean, allowPositive: boolean) => {
if (!allowNegative && delta < 0)
return exponent(delta)
if (!allowPositive && delta > 0)
return exponent(delta)
return delta
}
const newDx = hasHorizontal.value
? dampAxis(deltaX, allowLeft.value, allowRight.value)
: exponent(deltaX)
const newDy = hasVertical.value
? dampAxis(deltaY, allowUp.value, allowDown.value)
: exponent(deltaY)
return { x: newDx, y: newDy }
}
随后在 processMove 中直接赋值,不再做任何单轴符号重建(useSwipeDismiss.ts):
const damped = applyDirectionalDamping(dx, dy)
dragOffset.value = { x: damped.x, y: damped.y }
setCssVars(el, damped.x, damped.y)
recordSample({ x: damped.x, y: damped.y }, time)
而 finishSwipe 的位移计算改用 getDisplacement(dir, damped.x, damped.y),得到的数值与用户实际物理移动量一致(useSwipeDismiss.ts)。
行为收益:拖拽底部抽屉向上(非关闭方向)时,你会感受到「sqrt 阻尼」的弹性回拉手感——这与 Base UI 完全一致;同时进度上报、释放判定都基于同一份阻尼增量,不再有符号漂移。
3.2 C3 — snapToNearest 接收原始增量
问题:释放时 snap 计算需要的是最后一次移动的原始增量,而不是累积的 CSS 偏移量。
修复链路(源码均已验证):
SwipeProgressDetails暴露rawDelta(已有deltaX/deltaY,见 useSwipeDismiss.ts);- DrawerContentImpl.vue 在
onProgress闭包中持续捕获最新rawDelta到lastRawDelta; onRelease中通过getDisplacement(dir, lastRawDelta.x, lastRawDelta.y)将符号统一为「关闭方向为正」,再传给snapToNearest(DrawerContentImpl.vue)。
这与计划中给出的 Base UI 公式完全一致:
dragDelta = direction === 'down' ? deltaY
: direction === 'up' ? -deltaY
: direction === 'right' ? deltaX
: -deltaX
getDisplacement 在 utils.ts 中的实现正是上述符号表,四个方向的返回值均为「沿关闭方向的位移」。
3.3 C4 — snap 释放数学重写(逐行移植)
计划要求将 Base UI DrawerViewport.tsx(约 577-714 行)的 snap 释放数学逐行移植。计划文档给出了完整的目标实现,我们在当前源码 useDrawerSnapPoints.ts 中可以看到这一版本已经落地(常量定义在第 7-10 行):
// BaseUI snap-release constants (DrawerViewport.tsx)
const SNAP_VELOCITY_THRESHOLD = 0.5
const SNAP_VELOCITY_MULTIPLIER = 300
const MAX_SNAP_VELOCITY = 4
const FAST_SWIPE_VELOCITY = 0.5
算法的核心五步,任何实现者都应原样保留:
- 取当前偏移:
currentOffset = activePoint?.offset ?? 0(0 = 完全展开,ph= 完全关闭); - 计算拖拽目标:
dragTargetOffset = clamp(currentOffset + dragDelta, 0, ph); - 速度加成:当
|velSigned| ≥ 0.5时,targetOffset = dragTargetOffset + clamp(velSigned, ±4) × 300——这是「快甩」能越过中间吸附点的数学来源; - 最近点 vs 关闭判定:先找最近 snap point;若到完全关闭位置(offset = ph)的距离严格小于到最近点距离,则关闭(
onSnapPointChange(null)); - 顺序模式:仅在速度方向与拖拽方向一致且
|vel| ≥ 0.5时前进一步,否则按物理越界(targetOffset 越过相邻点)决定是否前进。
顺序模式分支值得单独说明(源码 useDrawerSnapPoints.ts):
const dragDir = Math.sign(dragDelta) // +1 = 关闭方向, -1 = 展开方向
const velDir = Math.sign(velSigned)
const shouldAdvance = velDir === dragDir && Math.abs(velSigned) >= FAST_SWIPE_VELOCITY
const adjacentIdx = Math.max(0, Math.min(sorted.length - 1, currentIdx + dragDir))
const adjacent = sorted[adjacentIdx]
if (shouldAdvance) {
onSnapPointChange(adjacent.value)
return
}
// 物理越界判断
const crossed = dragDir > 0
? targetOffset > adjacent.offset
: targetOffset < adjacent.offset
onSnapPointChange(crossed ? adjacent.value : (activeSnapPoint.value ?? closest.value))
关键词:
SNAP_VELOCITY_THRESHOLD = 0.5(启动速度加成的阈值)、SNAP_VELOCITY_MULTIPLIER = 300(速度→像素的放大系数)、MAX_SNAP_VELOCITY = 4(速度钳制)、FAST_SWIPE_VELOCITY = 0.5(顺序模式快甩阈值)。这四个常量是释放手感的全部秘密。
四、Phase 3 — 缺失行为补齐
这一阶段解决 6 个行为缺口(P3.1-P3.6),每个都可以在源码中找到对应实现。
4.1 P3.1 — 释放时写入 --drawer-swipe-strength
计划要求:在 onRelease 中根据「剩余距离 + 速度」计算一个 0.1-1.0 的标量并写入 contentElement,公式来自 Base UI DrawerViewport.tsx 的 computeReleaseDurationScalar。
落地位置:
- 计算函数
computeSwipeReleaseScalar在 utils.ts,移植自resolveSwipeRelease; - 写入时机在 DrawerContentImpl.vue 的
onRelease回调中。
标量含义:剩余距离短 + 甩动速度快 → 标量趋近 0.1(快速释放);剩余距离长 / 速度慢 → 标量趋近 1(默认释放)。消费方可以在 CSS 中用它缩放过渡时长,例如:
transition-duration: calc(var(--drawer-swipe-strength, 1) * 300ms);
4.2 P3.2 — 滚动边缘滑动(scroll-edge swipe)
原实现对「从可滚动内容中发起滑动」采取一刀切取消(计划文档中的 355-390 行),问题在于:当用户已经把内容滚到边缘、继续朝关闭方向拖时,理应交给抽屉。
修复为滚动边缘检查:当首次移动发生在关闭轴上时,仅当可滚动祖先处于对应边缘才允许滑动:
down抽屉:scrollTop === 0;up抽屉:scrollTop + clientHeight >= scrollHeight;- 左右方向同理。
源码中该函数为 canSwipeFromScrollEdge(useSwipeDismiss.ts),移植自 Base UI useSwipeDismiss.ts:canSwipeFromScrollEdgeOnPendingMove,返回三态:
true→ 允许滑动(滚动已在边缘);false→ 阻止(用户确实在滚动内容);null→ 方向无法识别,调用方延后到下一帧重试。
调用点在 onTouchMove 中(useSwipeDismiss.ts):false 时直接 reset();true 时清除守卫标记让后续移动走正常滑动路径。
4.3 P3.3 — 父级订阅 nestedSwipeProgressStore
当子抽屉滑动关闭时,父抽屉应能「反向」联动动画。计划要求父级 DrawerContentImpl 挂载时(若存在父级上下文)订阅 rootContext.nestedSwipeProgressStore,并把进度写入自己的 --drawer-swipe-progress CSS 变量。
unsubscribeNestedProgress = rootContext.nestedSwipeProgressStore.subscribe(() => {
const progress = rootContext.nestedSwipeProgressStore.getSnapshot()
currentElement.value?.style.setProperty(DRAWER_CSS_VARS.swipeProgress, `${progress}`)
})
nestedSwipeProgressStore 是一个纯发布/订阅对象(utils.ts),不经过 Vue 响应式,从而在滑动过程中零重渲染开销。卸载时在 onUnmounted 中取消订阅(DrawerContentImpl.vue)。
4.4 P3.4 — keepHeightWhileNested
当存在嵌套抽屉且父级已测得高度时,父级的 ResizeObserver 回调应跳过高度写入,避免子抽屉动画期间父级吸附点几何抖动。落地见 DrawerContentImpl.vue:
useResizeObserver(currentElement, ([entry]) => {
if (!entry)
return
if (rootContext.hasNestedDrawer.value && rootContext.popupHeight.value > 0)
return
const h = entry.contentRect.height
rootContext.onPopupHeightChange(h)
currentElement.value?.style.setProperty(DRAWER_CSS_VARS.height, `${h}px`)
})
4.5 P3.5 — 背景层上的 data-swiping / data-swipe-direction
计划要求把 isSwiping ref 暴露到 root context,让 overlay 读取并渲染数据属性。落地见 DrawerOverlayImpl.vue:
const dataAttributes = computed(() => {
const attrs: Record<string, string | undefined> = {
'data-state': rootContext.open.value ? 'open' : 'closed',
'data-swipe-direction': rootContext.swipeDirection.value,
}
if (rootContext.isSwiping.value)
attrs['data-swiping'] = ''
return attrs
})
配合 Base UI 风格的选择器(<a href="https://link.gitcode.com/i/943055a5b0a8dcb37d94d4bbd36520e0" target="_blank">data-swiping] [data-slot="drawer-backdrop"]),消费方可以在滑动过程中实时调整背景透明度/模糊。isSwiping ref 在 [DrawerRoot.vue 定义,由 onSwipingChange 更新(DrawerRoot.vue)。
4.6 P3.6 — nestedOpenDrawerCount 取代布尔计数
计划要求 root context 增加 nestedOpenDrawerCount: Ref<number>,在 onNestedDrawerPresenceChange 中递增/递减,DrawerContentImpl 读取它写入 --nested-drawers CSS 变量。
落地见 DrawerRoot.vue:
onNestedDrawerPresenceChange(present) {
if (present)
nestedOpenDrawerCount.value++
else
nestedOpenDrawerCount.value = Math.max(0, nestedOpenDrawerCount.value - 1)
hasNestedDrawer.value = nestedOpenDrawerCount.value > 0
parentContext?.notifyParentHasNestedDrawer?.(present)
}
CSS 变量同步在 DrawerContentImpl.vue:
watch(() => rootContext.nestedOpenDrawerCount.value, (n) => {
currentElement.value?.style.setProperty(DRAWER_CSS_VARS.nestedDrawers, `${n}`)
})
与旧实现的差异:Base UI 使用运行中的计数而非布尔值,嵌套层数可以作为 CSS 缩放/偏移的乘数,实现多级嵌套的层叠视觉效果(源码注释原文:"Base UI uses a running count, not a boolean")。
4.7 配套机制:CSS 变量注册
整个手势系统依赖的 CSS 变量由 registerDrawerCssProperties 一次性注册(utils.ts),通过 CSS.registerProperty 声明语法类型与初始值:
<length>型(initialValue: '0px'):--drawer-swipe-movement-x、--drawer-swipe-movement-y、--drawer-snap-point-offset;<number>型:--drawer-swipe-progress(初值0)、--drawer-swipe-strength(初值1);- 全部
inherits: false,避免样式重算级联。
所有变量通过 element.style.setProperty 命令式写入(不经过 Vue 响应式),保证 60fps 滑动性能。完整变量清单见 utils.ts。
五、Phase 4 — 测试计划:用模拟手势锁定行为
计划要求新增独立的 Drawer.swipe.test.ts(与保留 a11y/键盘/点击测试的 Drawer.test.ts 分离),并给出一个核心测试基建——simulateSwipe 辅助函数:
simulateSwipe(el, { from, to, duration })
// 依次派发 pointerdown / pointermove / pointerup,
// 并用 stubbed 的 performance.now 控制采样时间
计划列出的 5 个测试用例,覆盖了 Phase 2/3 的全部行为边界:
| 测试用例 | 验证目标 |
|---|---|
should dismiss on downward swipe past threshold (down drawer) ×4 方向 |
四个方向的滑动关闭阈值判定 |
should cancel on reversal within threshold |
阈值内的反向拖动应取消(对应 REVERSE_CANCEL_THRESHOLD = 10) |
should snap to nearest point on release (with snap points) |
非顺序模式按距离吸附 |
should dismiss from lowest snap if targetOffset past close threshold |
「离完全关闭比离任何吸附点更近」时关闭 |
should advance sequentially on fast swipe (sequential mode) |
顺序模式快甩前进一步 |
当前仓库已存在的测试文件包括 Drawer.test.ts、Drawer.snap.test.ts 以及 composables 层的 useDrawerSnapPoints.test.ts 与 useSwipeDismiss.test.ts,说明手势数学已被单元级覆盖,simulateSwipe 的引入将补齐集成级的手势链路验证。
六、Phase 5 — 验证与提交
计划收尾阶段给出两条验证命令与提交策略:
pnpm --filter @reka-ui/core typecheck # 或项目既有的类型检查命令
pnpm --filter @reka-ui/core test Drawer # 仅运行 Drawer 相关测试
- 每个阶段独立提交,便于 review 与 bisect;
- 阶段间可独立构建,任何失败都不会污染代码树。
七、总结:一份计划的落地样本
将计划文档与当前仓库源码对照,可以看到这份计划已经完整落地:Phase 1 的 API 改动集中在 DrawerRoot.vue 与 index.ts;Phase 2 的手势数学在 useSwipeDismiss.ts 与 useDrawerSnapPoints.ts 中逐项兑现;Phase 3 的六项行为补齐分布在 DrawerContentImpl.vue、DrawerOverlayImpl.vue 与 utils.ts 中。
这套「评审 → 分阶段计划 → 逐项落地 → 测试锁定」的方法论,对任何做第三方组件移植(尤其是 React → Vue)的团队都有直接借鉴价值:优先保证行为与 API 的对齐,用别名而非重写来兼容命名差异,把数学逻辑逐行移植并用四组常量锁定手感,最后用模拟手势测试固化行为边界。如果你正在维护或移植复杂交互组件,建议将 Drawer 源码目录 与这份 实施计划 对照阅读,会发现每一行注释背后都是一次真实评审结论的沉淀。