色彩模式切換
上面是可以按的真實元件:左邊只有圖示,右邊加上文字。按下去會真的換掉這一頁的色彩模式,但頁首的「色彩模式」選單不會跟著改字;重新整理頁面後,以頁首的選擇為準。這一頁同時有頁首的選單和兩個切換鈕,只是為了示範;正式網站一頁只放一個。
用法
章節連結:用法色彩模式切換讓讀者在淺色和深色之間切換整個網站。讀者第一次來時,網站先跟著他裝置的設定;按過一次之後,網站會記住他的選擇,下次再來也一樣。它只切換淺色和深色,不切換主題:主題是網站選用的一組外觀,讀者不能換。一般用只有圖示的樣式放在頁首;空間夠、或擔心讀者看不懂圖示時,用加上文字的樣式。
組成
章節連結:組成| 部位 | 說明 |
|---|---|
| 按鈕 | 圓形的外框按鈕,大小用的是控制項的標準尺寸,用手指也好按。滑鼠移上去時換成淡淡的品牌底色和主色外框。 |
| 圖示 | 顯示「按下去會換成什麼」:淺色時是月亮(換成深色),深色時是太陽(換成淺色)。 |
| 文字 | 可省略。打開時在圖示旁顯示「切換至深色模式」或「切換至淺色模式」,文字是固定的,不能改。 |
| 焦點框 | 用鍵盤選到它時出現的外框,讓不用滑鼠的人知道目前在哪裡。 |
不論有沒有顯示文字,螢幕閱讀器都會唸出「切換至深色模式」或「切換至淺色模式」。
該做與不該做
章節連結:該做與不該做| 類型 | 說明 |
|---|---|
| 建議 | 放在每一頁相同的位置(例如頁首右邊),讀者換頁後還找得到。 |
| 建議 | 網站要提供深色模式時才放;放了就要確定每一頁在淺色和深色下都看過、文字都看得清楚。 |
| 建議 | 在說明文字裡把它叫「色彩模式」或「淺色/深色」,不叫「主題」。 |
| 避免 | 不要用它來切換主題,它只會切換淺色和深色。 |
| 避免 | 不要在很窄的地方用加上文字的樣式:文字不會換行,會把旁邊的東西擠開。窄的地方用只有圖示的樣式。 |
| 避免 | 不要在同一個畫面放好幾個切換鈕;一個就夠,讀者才不會以為它們各管不同的東西。 |
在目前主題下的樣子
章節連結:在目前主題下的樣子目前顯示:DefaultGreen Natural(示意)。在頁首的「主題」可以切換。 查看所有主題
- 預設變體: 用元件本身的預設變體。
- 和預設主題不同的地方: 沒有。這就是預設主題,其他主題沒有特別指定的地方都沿用它。
- 預設變體: 主題不決定預設變體:用元件本身的預設變體(各網站自己的預設變體要等網站設定檔,還沒有實作)。
- 和預設主題不同的地方: (以下都是示意值)只有這個元件用到的顏色:主色、品牌底色(襯在內容後的品牌色塊)、焦點框(用鍵盤選到時的外框)。其餘和預設主題一樣。 看完整的顏色對照
上方預覽會跟著頁首的「主題」和「色彩模式」一起變:圖示的顏色,以及滑鼠移上去時的外框顏色,用的是目前主題的主色。
給工程師
章節連結:給工程師以下是給工程師的安裝與 API 說明,美編(設計)、網站的編輯和致遠(廠商)可以略過。
Storybook(給工程師逐一檢查元件狀態的工具網站,在本機用 pnpm run heroui:storybook 開啟)目前只收錄 HeroUI 的元件,還沒有 <tc-theme-toggle> 的頁面;這一段的範例和 API 表就是它的說明。
<tc-theme-toggle> 切換 <html> 的 data-theme 屬性。深色色票由 @tzuchi/tokens 的
[data-theme="dark"] 區塊提供,元件僅引用語意色 token,因此整個元件庫會透過 CSS 變數
串接自動換色——切換鈕本身不需要知道任何元件的存在。
行為
章節連結:行為- 記憶:使用者點擊後寫入
localStorage["tc-theme"];下次載入沿用。 - 系統跟隨:在使用者尚未選擇前,跟隨系統
prefers-color-scheme,並即時回應系統切換。 - 同步外部變更:以
MutationObserver監看<html data-theme>,與頁面上其他切換鈕 (或 docs 內建切換)保持一致。 - 無障礙:以
role="switch"+aria-checked呈現,並提供動態aria-label(「切換至深色/淺色模式」)。
防止閃爍(anti-FOUC)
章節連結:防止閃爍(anti-FOUC)元件在 connectedCallback 才套用色彩模式,無法避免整頁載入時的閃爍。請在 <head>
最前面加入一段同步 inline script,在首次繪製前就設定好 data-theme:
<script> (function () { try { var s = localStorage.getItem('tc-theme'); var t = s === 'light' || s === 'dark' ? s : matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'; document.documentElement.setAttribute('data-theme', t); } catch (e) {} })();</script>純 HTML
章節連結:純 HTML<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" /><script type="module" src="@tzuchi/components/cdn"></script>
<tc-theme-toggle></tc-theme-toggle>React
章節連結:Reactimport { TcThemeToggle } from '@tzuchi/react';
<TcThemeToggle onTcThemeChange={(e) => console.log(e.detail.theme)} />;API
章節連結:API下表自 Custom Elements Manifest 自動產生:
| Attribute | Type | Default | Description |
|---|---|---|---|
theme | TcTheme | 'light' | 目前套用的主題。會反映到屬性以供樣式與檢視使用(唯讀,請用點擊切換)。 |
show-label | boolean | false | 是否在圖示旁顯示動作文字(例如「切換至深色模式」)。 |
相關
章節連結:相關- 色彩模式(淺色/深色) — 深色色票如何運作、如何擴充。