跳到內容
開始使用

色彩模式切換

其他 Color Mode Toggle

上面是可以按的真實元件:左邊只有圖示,右邊加上文字。按下去會真的換掉這一頁的色彩模式,但頁首的「色彩模式」選單不會跟著改字;重新整理頁面後,以頁首的選擇為準。這一頁同時有頁首的選單和兩個切換鈕,只是為了示範;正式網站一頁只放一個。

色彩模式切換讓讀者在淺色和深色之間切換整個網站。讀者第一次來時,網站先跟著他裝置的設定;按過一次之後,網站會記住他的選擇,下次再來也一樣。它只切換淺色和深色,不切換主題:主題是網站選用的一組外觀,讀者不能換。一般用只有圖示的樣式放在頁首;空間夠、或擔心讀者看不懂圖示時,用加上文字的樣式。

部位說明
按鈕圓形的外框按鈕,大小用的是控制項的標準尺寸,用手指也好按。滑鼠移上去時換成淡淡的品牌底色和主色外框。
圖示顯示「按下去會換成什麼」:淺色時是月亮(換成深色),深色時是太陽(換成淺色)。
文字可省略。打開時在圖示旁顯示「切換至深色模式」或「切換至淺色模式」,文字是固定的,不能改。
焦點框用鍵盤選到它時出現的外框,讓不用滑鼠的人知道目前在哪裡。

不論有沒有顯示文字,螢幕閱讀器都會唸出「切換至深色模式」或「切換至淺色模式」。

類型 說明
建議 放在每一頁相同的位置(例如頁首右邊),讀者換頁後還找得到。
建議 網站要提供深色模式時才放;放了就要確定每一頁在淺色和深色下都看過、文字都看得清楚。
建議 在說明文字裡把它叫「色彩模式」或「淺色/深色」,不叫「主題」。
避免 不要用它來切換主題,它只會切換淺色和深色。
避免 不要在很窄的地方用加上文字的樣式:文字不會換行,會把旁邊的東西擠開。窄的地方用只有圖示的樣式。
避免 不要在同一個畫面放好幾個切換鈕;一個就夠,讀者才不會以為它們各管不同的東西。

目前顯示: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 (「切換至深色/淺色模式」)。

元件在 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>
<link rel="stylesheet" href="@tzuchi/tokens/tokens.css" />
<script type="module" src="@tzuchi/components/cdn"></script>
<tc-theme-toggle></tc-theme-toggle>
import { TcThemeToggle } from '@tzuchi/react';
<TcThemeToggle onTcThemeChange={(e) => console.log(e.detail.theme)} />;

下表自 Custom Elements Manifest 自動產生:

Attribute Type Default Description
theme TcTheme 'light' 目前套用的主題。會反映到屬性以供樣式與檢視使用(唯讀,請用點擊切換)。
show-label boolean false 是否在圖示旁顯示動作文字(例如「切換至深色模式」)。