usePreferredColorScheme

prefers-color-scheme 媒體查詢

usePreferredColorScheme 使用 prefers-color-scheme 媒體查詢偵測使用者的系統色彩方案偏好。它回傳一個字串值："dark"、"light" 或 "no-preference"，並在使用者更改系統設定時即時更新。

使用場景

• 根據使用者的系統偏好自動設定應用程式主題
• 在應用程式中顯示使用者目前的系統色彩方案設定
• 根據系統偏好預先載入適當的主題資源

注意事項

• SSR 安全：接受一個 defaultState 參數（預設："no-preference"），在 window.matchMedia 不可用的伺服器端渲染時回傳。
• 響應式：當使用者切換系統色彩方案時（例如在作業系統設定中啟用深色模式）即時更新。
• 相關 hooks：另請參閱 usePreferredDark 用於更簡單的布林值檢查，useColorMode 用於多主題管理，以及 useDarkMode 用於帶持久化的明暗切換。

Usage

function Demo() {
  const color = usePreferredColorScheme();

  return <div>首選色彩方案：{color}</div>;
};

API

usePreferredColorScheme

Returns

ColorScheme: prefers-color-scheme的媒體查詢值

Arguments

ColorScheme

Type

export type ColorScheme = 'dark' | 'light' | 'no-preference'