--- title: "React useReducedMotion Hook：尊重 prefers-reduced-motion（2026）" description: "一篇实用的 useReducedMotion 上手指南：读取操作系统级的 prefers-reduced-motion 设置，为前庭功能障碍用户禁用或简化动画，并搞清楚 WCAG 真正要求你去掉的是哪些动效。只是 useMediaQuery 上的一行封装，SSR 安全，且能响应系统设置的实时变化。" date: 2026-07-08 canonical: https://reactuse.com/zh-Hans/blog/react-usereducedmotion-hook/ --- # React useReducedMotion Hook：尊重 prefers-reduced-motion（2026） 一个铺满整屏的视差首图。一个自动滚动的轮播图。一个又转又弹又跳的加载动画。对大多数用户来说这只是「够现代」。但对有前庭功能障碍、先兆偏头痛或梅尼埃病的用户来说，这可能会引发真实的恶心、眩晕，或者严重到直接关掉页面的头痛——这不是「不爽」，而是实实在在的生理症状。这正是为什么每个主流操作系统都自带「减弱动态效果」开关（iOS 从 2013 年起、macOS、Windows、Android、GNOME），也是为什么 CSS 把它暴露给了 Web，也就是 [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) 媒体特性。 `useReducedMotion` 就是把这个设置读进 React state 的 hook——响应式的，用户一切换系统开关就立刻更新；也是安全的，不会在 SSR 期间碰 `window`。本文讲清楚真实的 [`@reactuses/core`](https://reactuse.com) API、`prefers-reduced-motion` 到底要求你去掉什么动效（它比「完全不能动」要窄得多），以及你会真正用到的三种整合模式。 ## 最朴素的写法 最直觉的做法是在 effect 里手写 `window.matchMedia`： ```tsx function Hero() { const [reduce, setReduce] = useState(false); useEffect(() => { const mql = window.matchMedia('(prefers-reduced-motion: reduce)'); setReduce(mql.matches); // 🐛 忘了这行，值就再也不会更新了 const onChange = () => setReduce(mql.matches); mql.addEventListener('change', onChange); return () => mql.removeEventListener('change', onChange); }, []); return
; } ``` 实践中这会以三种方式出问题。第一，`window` 在服务端不存在，所以这整块一旦跑在 Next.js、Remix 或 Astro 上就需要守卫——而人们很容易图省事，在渲染逻辑里到处撒 `typeof window !== 'undefined'`，而不是把它收敛进一个 effect。第二，很多人只用 `mql.matches` 初始化一次 state，然后干脆省掉 `change` 监听——这在大多数情况下没问题，直到用户在标签页开着的时候*真的*切换了这个设置（笔记本从电池切到插电，在某些系统上就会触发它，而这一点 QA 几乎从不测）。第三，每个关心动效偏好的组件都在重写同一套 `matchMedia` + 监听器 + 清理的舞步。 ## API [`useReducedMotion`](https://reactuse.com/browser/usereducedmotion/) 只是一次调用： ```ts const prefersReducedMotion = useReducedMotion(defaultState?: boolean): boolean; ``` - **`defaultState`** —— 可选，默认 `false`。这是 SSR 期间以及客户端首次渲染时（媒体查询还没来得及求值之前）返回的值。 - **返回值** —— 一个从 `defaultState` 开始的布尔值，会在用户改变操作系统级动效偏好时实时更新。不用手写监听器，也没有清理逻辑要忘。 在底层，实现真就这么简单——整个实现就是对 [`useMediaQuery`](https://reactuse.com/browser/usemediaquery/) 的一行调用： ```ts export function useReducedMotion(defaultState?: boolean) { return useMediaQuery('(prefers-reduced-motion: reduce)', defaultState); } ``` 真正干活的是 `useMediaQuery`——它在 effect 内部构造 `MediaQueryList`（所以渲染期间和服务端都不会碰 `matchMedia`），并替你订阅它的 `change` 事件。`useReducedMotion` 只是把查询字符串钉死了。这就是它的全部价值：你每次都能拿到正确、拼写正确、接线正确的那个查询。 ## 模式一：关掉单个动画 最小的用法——用这个标志控制单个 CSS transition 或类名： ```tsx import { useReducedMotion } from '@reactuses/core'; function Hero() { const reduce = useReducedMotion(); return (

Welcome

); } ``` `.hero--parallax` 带着那个滚动联动的 `transform: translateY(...)` 动画；基础的 `.hero` 类没有。当 `reduce` 为 `true` 时，根本没有任何 JS 动画逻辑在跑——你不只是跳过了*视觉上*的动效，也跳过了驱动它的那个滚动监听器或 `requestAnimationFrame` 循环，这在低端设备上同样是实打实的性能收益。 ## 模式二：接入 Framer Motion / GSAP 如果你在用动画库，hook 的值可以直接接进它的 duration/transition 配置，而不是切换类名： ```tsx import { motion } from 'framer-motion'; import { useReducedMotion } from '@reactuses/core'; function Card({ children }: { children: React.ReactNode }) { const reduce = useReducedMotion(); return ( {children} ); } ``` 注意这里并没有去掉淡入——`opacity` 不属于 `prefers-reduced-motion` 想管的那类动效（见下一节）。它去掉的是*位移*：`reduce` 为真时 `y` 永远不动，过渡也是瞬时的，所以卡片只是「出现」而已。Framer Motion 自己也带了一个 [`useReducedMotion`](https://www.framer.com/motion/use-reduced-motion/) hook，做的是同样的 `matchMedia` 读取——如果你已经在用 `@reactuses/core` 处理别的一切，用这个 hook 能让你保持一个真相来源，而不是两个库各自独立读同一个媒体查询。 ## 模式三：一个全局开关，而不是 N 处判断 一旦设计系统里有几十个带动画的组件，逐个用 `reduce ? ... : ...` 判断的写法会很难扩展。真正能扩展的模式是：在靠近应用根部的地方读一次这个 hook，用它驱动一个 `data-` 属性，让全局样式表来响应。 ```tsx function App({ children }: { children: React.ReactNode }) { const reduce = useReducedMotion(); return (
{children}
); } ``` ```css [data-motion="reduce"] *, [data-motion="reduce"] *::before, [data-motion="reduce"] *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; scroll-behavior: auto !important; } ``` 这和那个经典的、[直接建在媒体查询上的 CSS 通配符规则](https://web.dev/prefers-reduced-motion/)是同一个形状——区别是这里的 `data-motion` 属性由 React state 驱动，所以同一个标志既能给你的 JS 动画逻辑用（模式二），也能给这里的 CSS 用，而不用把媒体查询读两遍、也不用担心两边会不同步。 ## 「减弱」不等于什么 `prefers-reduced-motion: reduce` 不是「禁用一切动效」。[WCAG 2.3.3](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html) 和各平台厂商真正针对的是**大范围、非必要的动效**：视差滚动、自动播放的背景视频、缩放/平移式的首图动画、自动轮播、装饰性的弹跳/旋转加载动画。而那些承载信息或确认交互的动效——复选框的打勾动画、按钮短暂的按压状态、指示「仍在加载」的加载指示器、拖放反馈——一般可以保留，理想情况下只是更短、更平静一些。把*每一个*像素的移动都去掉，包括一个 `:hover` 的颜色过渡，并不是这个设置想要的，反而可能让界面显得像是坏了，而不是变得无障碍。拿不准的时候可以这样判断：「这个动效是不是铺满了屏幕的大部分区域，或者在没有用户操作的情况下持续运行？」——这才是该去掉的那类动效。 还有一点值得知道：如果你只需要在 CSS 里用它，从来不需要在 JS 逻辑里用，Tailwind 的 [`motion-reduce:`](https://tailwindcss.com/docs/animation#accounting-for-reduced-motion-preferences) 变体（或者一段普通的 `@media (prefers-reduced-motion: reduce)` 规则）就能零 JavaScript 搞定。真正需要用到这个 hook 的场景，是这个判断需要深入到渲染或 effect 逻辑里的时候——比如在自动播放的 `