---
title: "React 與使用者偏好:尊重使用者已經在 OS 裡設過的那些選項"
description: "用 ReactUse 中的 usePreferredDark、usePreferredColorScheme、useColorMode、usePreferredContrast、useReducedMotion、usePreferredLanguages 和 useTextDirection 建構可存取的、感知 OS 設定的 React UI——尊重深色模式、對比度、減弱動效、語言和文字方向。"
date: 2026-05-14
canonical: https://reactuse.com/zh-Hant/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` 讀取持久化選擇,從而避開這個問題。配合 `` 裡一段微小的內聯 `