自訂主題（Theme）：一次改變整個 HA 的外觀

charles · 發表於 3 天前

card-mod 是改單張卡片，主題是改全部。

而且主題是官方功能，不會因為更新而壞掉。

主題是什麼

一組 CSS 變數的值。

HA 的前端到處都在用這些變數：

卡片背景 → var(--ha-card-background)
主要文字 → var(--primary-text-color)
強調色 → var(--accent-color)

複製代碼

你只要改這些變數的值，整個介面就跟著變。

怎麼建立

第一步：建立資料夾和檔案

/config/themes/my_theme.yaml

複製代碼

第二步：告訴 HA 去讀它

# configuration.yaml
frontend:
themes: !include_dir_merge_named themes/

複製代碼

第三步：寫主題

# /config/themes/my_theme.yaml
我的主題:
# ===== 主色 =====
primary-color: "#2E9D6E"
accent-color: "#FFB300"
dark-primary-color: "#1F6E4D"
light-primary-color: "#7FD3B0"
# ===== 文字 =====
primary-text-color: "#1C2430"
secondary-text-color: "#6B7684"
text-primary-color: "#FFFFFF"
disabled-text-color: "#B0B8C4"
# ===== 背景 =====
primary-background-color: "#F5F7FA"
secondary-background-color: "#EDF1F6"
divider-color: "#E0E5EC"
# ===== 卡片 =====
card-background-color: "#FFFFFF"
ha-card-background: "#FFFFFF"
ha-card-border-radius: "16px"
ha-card-box-shadow: "0 2px 8px rgba(0,0,0,0.06)"
ha-card-border-width: "0"
# ===== 狀態顏色 =====
state-icon-color: "#8A94A6"
state-icon-active-color: "#FFB300"
error-color: "#E53935"
warning-color: "#FB8C00"
success-color: "#43A047"
info-color: "#1E88E5"
# ===== 側邊欄 =====
sidebar-background-color: "#FFFFFF"
sidebar-icon-color: "#8A94A6"
sidebar-selected-icon-color: "#2E9D6E"
sidebar-selected-text-color: "#2E9D6E"
# ===== 上方列 =====
app-header-background-color: "#2E9D6E"
app-header-text-color: "#FFFFFF"

複製代碼

第四步：套用

重新載入主題：開發者工具 → YAML → 重新載入主題
套用：左下角你的名字 → 主題 → 選你的

主題是每個使用者各自設定的 ——
你換主題不會影響家人。

深色模式

主題可以同時定義淺色和深色兩套：

我的主題:
# 共用的設定（兩種模式都套用）
ha-card-border-radius: "16px"
primary-color: "#2E9D6E"
modes:
light:
primary-text-color: "#1C2430"
card-background-color: "#FFFFFF"
primary-background-color: "#F5F7FA"
dark:
primary-text-color: "#E8EAED"
card-background-color: "#1E2530"
primary-background-color: "#141A22"
ha-card-background: "#1E2530"
divider-color: "#2C3542"

複製代碼

使用者選「自動」的話，會跟著系統的深淺色設定切換。

自動切換主題

用自動化在日落時換主題：

alias: 日落切換深色主題
triggers:
- trigger: sun
event: sunset
actions:
- action: frontend.set_theme
data:
name: 我的主題
mode: dark
mode: single

複製代碼

但老實說：讓使用者選「自動」跟著系統走，
比你寫自動化強制切換好 —— 因為每個人的偏好不同。

有哪些變數可以改

官方文件有完整清單，但實務上最常改的就這幾類：

顏色類

primary-color —— 主色，影響很多地方
accent-color —— 強調色（滑桿、選取狀態）
state-icon-active-color —— 燈開著時圖示的顏色

卡片類

ha-card-border-radius —— 圓角
ha-card-box-shadow —— 陰影
ha-card-border-width —— 邊框寬度
ha-card-background —— 背景

字體

primary-font-family: "'Noto Sans TC', sans-serif"
paper-font-common-base_-_font-family: "'Noto Sans TC', sans-serif"

複製代碼

中文字體建議：

Noto Sans TC —— Google 的開源字體，字重齊全
微軟正黑體 —— Windows 上直接有
PingFang TC —— Mac / iOS 上直接有

一個實用的寫法（依平台自動選）：

primary-font-family: >-
"PingFang TC", "Microsoft JhengHei", "Noto Sans TC", sans-serif

複製代碼

自己定義變數（進階但很好用）

你可以在主題裡定義自己的變數，然後在 card-mod 裡用。

我的主題:
# 自訂變數
my-warm-glow: "rgba(255, 193, 7, 0.15)"
my-alert-red: "#E53935"
my-card-gap: "10px"

複製代碼

card-mod 裡：

card_mod:
style: |
ha-card {
background: var(--my-warm-glow);
}

複製代碼

好處：改一個地方，所有卡片跟著變。

我用這招管理「所有警示的紅色」 ——
想換顏色只要改主題裡那一行。

找現成的主題

不想自己寫的話：

HACS → 前端，有很多現成的主題
熱門的有 Google Theme、iOS Theme、
Noctis、Metrology 等等
下載之後一樣要重新載入主題再套用

我的建議：先裝一個現成的，看它的 YAML 怎麼寫，再改成自己的。

比從零開始快很多。

除錯：怎麼知道某個東西用的是哪個變數

按 F12
點那個元素
右邊的 Styles 會顯示套用的 CSS
看到 var(--xxx) 就是那個變數

或者更快：選 html 元素，右邊會列出所有變數的目前值。

搜尋你想找的顏色，就知道是哪個變數。

三個實務建議

一、先改顏色，不要一開始就改結構

改 border-radius、box-shadow 這類很安全。

改 padding、margin、position 的話可能會在某些畫面破版。

二、在手機上測

很多主題在電腦上很好看，在手機上字太小或對比不夠。

三、深色模式的對比要夠

深色主題最常見的問題是文字太暗看不清楚。

背景 #1E2530 配文字 #E8EAED 是安全的組合
次要文字不要低於 #9AA4B2

---

下一篇：一個好用的儀表板該長什麼樣。

不講技術，講設計 —— 這是最多人做不好的部分。

		自動登入	找回密碼
密碼			立即註冊

自訂主題（Theme）：一次改變整個 HA 的外觀

瀏覽過的版塊