---
title: "React 与用户偏好:尊重用户已经在 OS 里设过的那些选项"
description: "用 ReactUse 中的 usePreferredDark、usePreferredColorScheme、useColorMode、usePreferredContrast、useReducedMotion、usePreferredLanguages 和 useTextDirection 构建可访问的、感知 OS 设置的 React UI——尊重深色模式、对比度、减弱动效、语言和文字方向。"
date: 2026-05-14
canonical: https://reactuse.com/zh-Hans/blog/react-user-preferences/
---
# React 与用户偏好:尊重用户已经在 OS 里设过的那些选项
每一个现代操作系统都会在某个时刻问用户:你想要什么样的 UI。深色还是浅色。高对比还是普通。动画开还是关。从左到右还是从右到左。首选语言。用户在系统设置里选一次,从那一刻起,这台机器上每一个好好做出来的原生 App 都会尊重这个选择。而你上线的 Web App 通常不会——它自己搞一个深色模式开关,自己用一个动画库,自己默认是英文,OS 偏好变成某个 issue 跟踪器里五行字的备注。
修起来不难,API 表面也很窄。浏览器通过 `window.matchMedia` 和 `navigator.language` 暴露这些 OS 偏好,任何一个现代 React 应用一个下午就能接好。问题不是能不能,而是接线代码住在跟所有 Web 特性一样的 `useEffect`/`useState`/SSR 不一致的沼泽里,所以永远被搁置。[ReactUse](https://reactuse.com) 为此提供了 7 个聚焦的 hook,它们一起覆盖了真正重要的 4 个用户偏好维度:主题、动效、对比度、语言区域。
这篇文章逐个走一遍——它返回什么、它藏了什么 bug、最终的组件长什么样。最后把它们组合进一个 `useAppearance()` hook,一次性读取这 4 个信号。
## 1. usePreferredDark——开启主题系统的那个布尔值
最简单的一个。`usePreferredDark()` 在用户 OS 设为深色模式时返回 `true`,否则 `false`。它是对 `window.matchMedia('(prefers-color-scheme: dark)').matches` 的轻量封装,帮你处理两件你本来要自己处理的事:SSR(没有 `window`)和实时更新(用户可以在你的标签页打开的同时切 OS 开关,你应该响应)。
### 手写版
```tsx
import { useEffect, useState } from "react";
function ManualDark() {
const [dark, setDark] = useState(false);
useEffect(() => {
const mq = window.matchMedia("(prefers-color-scheme: dark)");
setDark(mq.matches);
const onChange = (e: MediaQueryListEvent) => setDark(e.matches);
mq.addEventListener("change", onChange);
return () => mq.removeEventListener("change", onChange);
}, []);
return dark ? "dark" : "light";
}
```
这是对的,但初始 `useState(false)` 是猜的——对于 SSR 渲染的页面,深色模式用户第一次打开你网站时会产生 hydration 不一致。同样的修复在真实代码库里要写 5 次,而且默认值经常不一致。
### ReactUse 版
```tsx
import { usePreferredDark } from "@reactuses/core";
function Component() {
const isDark = usePreferredDark();
return ;
}
```
[`usePreferredDark`](https://reactuse.com/browser/usePreferredDark/) 是布尔进、布尔出——丢哪都行,零配置。首次渲染返回 SSR 安全的默认值;客户端挂载后,真实的 `matchMedia` 值流进来,并随着用户切换保持同步。
## 2. usePreferredColorScheme——当"深色"不够用时
`prefers-color-scheme` 有 3 个值,不是 2 个:`'light'`、`'dark'`、`'no-preference'`。大多数应用把第三个塌缩到前两个里的一个——这没问题,直到你上线"跟随系统"模式,然后发现有用户显式设了"无偏好",而你的应用现在选错了默认值。[`usePreferredColorScheme`](https://reactuse.com/browser/usePreferredColorScheme/) 返回完整的字符串。
```tsx
import { usePreferredColorScheme } from "@reactuses/core";
function ThemeBadge() {
const scheme = usePreferredColorScheme();
// scheme: "light" | "dark" | "no-preference"
return System theme: {scheme};
}
```
三值形式最有用的地方是带"系统"选项的主题选择器:
```tsx
type Choice = "light" | "dark" | "system";
function ThemePicker({ choice, onChange }: { choice: Choice; onChange: (c: Choice) => void }) {
const scheme = usePreferredColorScheme();
const effective =
choice === "system"
? scheme === "dark"
? "dark"
: "light"
: choice;
return (
);
}
```
可见标签告诉用户"系统"现在实际意味着什么——一个很小的细节,能挡住最常见的深色模式困惑("系统选项坏了;它给了我浅色")。
## 3. useColorMode——带持久化的主题状态
`usePreferredDark` 报告 OS 偏好。`useColorMode` 更进一步:它持有应用**实际应用的**主题。它把 OS 偏好作为默认值,允许用户覆盖,把覆盖持久化到 `localStorage`,并把选中的模式写到 `` 的 class 或属性上,这样你的 CSS 就能切换。
[`useColorMode`](https://reactuse.com/browser/useColorMode/) 才是你要的真实主题切换器:
```tsx
import { useColorMode } from "@reactuses/core";
function ThemeToggle() {
const [mode, setMode] = useColorMode();
// mode: "light" | "dark" | "auto"
return (
);
}
```
一个 hook 你就拿到:
- 初始值:如果用户之前设过,从 `localStorage` 读;否则从 `prefers-color-scheme` 读
- `'auto'` 模式下实时跟踪 OS 变化
- `` 上 class 切换(`html.dark` vs `html.light`),CSS 里不用任何 JS 条件
- SSR 安全:服务端和首次客户端绘制渲染同样的模式
自己实现主题系统的常见坑:首次绘制会闪一下错误模式,因为 OS 偏好是在 hydration 之后读到的。`useColorMode` 在渲染时同步写入解析后的模式,并在 React 接管树之前从 `localStorage` 读取持久化选择,从而避开这个问题。配合 `` 里一段微小的内联 `