QtShadcn
组件

动效 Token

theme 的时长/缓动语义层,以及弹层通用过渡件。

组件的过渡时长与缓动统一走 theme 上的语义 token,组件内不写字面量。

为什么要有这一层

改动前全库的时长是散落的字面量:100(13 处) / 120(8) / 150(3) / 200(1) / 700(3)。想统一调「弹层进场快一点」得翻遍所有组件,漏一处就不一致。

更具体的浪费:ShadcnDialog / ShadcnDropdownMenu / ShadcnSelect 三处的 enter / exit transition 一字不差地重复了 24 行。

时长档位

token值用途
durationInstant100弹层进出、hover 反馈这类「立即响应」
durationQuick120颜色 / 边框过渡(输入聚焦、hover 变色)
durationNormal150位移类(开关滑块)
durationSlow200高度展开(accordion / collapsible)

缓动:easingOut(OutCubic) / easingIn(InCubic) / easingInOut(InOutSine), 用法是 easing.type: theme.easingOut。

700ms 不在这里面。 Spinner 的旋转周期、Skeleton 的呼吸周期是循环动画 的周期,语义是「一轮多久」,不是「状态 A 到 B 用多久」。两者改动的动机也不同 (前者影响观感节奏,后者影响交互响应),混在一起会让调参变得没法推理。

减弱动画

theme.reducedMotion = true      // 全局:所有走 motionDuration() 的过渡归零

桌面端没有系统的 prefers-reduced-motion 对接,做成显式属性。组件侧统一写 duration: theme.motionDuration(theme.durationInstant),开关一开全部瞬间切换。

ShadcnFadeZoomTransition

弹层通用过渡(fade + zoom-95),替代三处重复的 24 行:

Dialog {
    enter: ShadcnFadeZoomTransition { shown: true }
    exit:  ShadcnFadeZoomTransition { shown: false }
}
属性默认说明
showntruetrue = 进场(0→1、0.95→1);false = 退场
zoomFrom0.95缩放起止幅度(zoom-95)
durationMs100时长
enterEasing / exitEasingOutCubic / InCubic进快停、退慢起
reducedMotionfalse时长归零

一个 Qt 结构限制

Transition 的默认属性 animations 只接受 Animation 派生类,任何 QtObject 都放不进去(QtShadcnTheme、甚至裸 QtObject 都会报 incompatible-type)。 所以这个组件里没法挂 QtShadcnTheme { id: theme } 去读 token,时长/缓动只能做成 可写属性、默认值写在这里。

若后续把 motion 下沉到 C++ ThemeManager 的 token 字典,就能改成直接读单例, 届时这个折中可以去掉。

Copyright © 2026