card-mod 入門：三行 CSS 改變任何一張卡片

charles

HA 的卡片能調的東西有限。

card-mod 讓你對任何卡片套用自己的 CSS ——
想改什麼就改什麼。



安裝

• HACS → 前端 → 搜尋 card-mod → 下載
  
• Ctrl+F5 清快取
  

強烈建議：裝成「前端模組」

card-mod 有些功能裝成前端模組才會正常，而且效能好很多。

1. # configuration.yaml
2. frontend:
3.   extra_module_url:
4.     - /hacsfiles/lovelace-card-mod/card-mod.js

複製代碼

改完重啟 HA，再清一次瀏覽器快取。

最基本的用法

1. type: tile
2. entity: light.living_room
3. card_mod:
4.   style: |
5.     ha-card {
6.       border-radius: 20px;
7.       box-shadow: 0 4px 12px rgba(0,0,0,0.1);
8.     }

複製代碼

card_mod.style 裡面寫的就是 CSS。

ha-card 是什麼

每一張卡片最外面的那個框。

所以 ha-card { ... } 的意思是「對這張卡片的外框套用這些樣式」。

最常改的五個東西



一、圓角

1.     ha-card {
2.       border-radius: 20px;
3.     }

複製代碼

二、陰影

1.     ha-card {
2.       box-shadow: 0 4px 16px rgba(0,0,0,0.12);
3.     }

複製代碼

拿掉陰影（扁平風格）：

1.     ha-card {
2.       box-shadow: none;
3.       border: 1px solid var(--divider-color);
4.     }

複製代碼

三、背景色

1.     ha-card {
2.       background: rgba(255, 193, 7, 0.12);
3.     }

複製代碼

依狀態變色（這個最實用）：

1.     ha-card {
2.       background: {% if is_state('light.living_room','on') %}
3.         rgba(255, 193, 7, 0.15)
4.       {% else %}
5.         var(--ha-card-background)
6.       {% endif %};
7.       transition: background 0.5s;
8.     }

複製代碼

注意：card_mod 的 style 支援 Jinja 範本，
這是它最強大的地方。

四、邊框（用來做「警示」效果）

1.     ha-card {
2.       border: 2px solid {% if is_state('binary_sensor.front_door','on') %}
3.         #e53935
4.       {% else %}
5.         transparent
6.       {% endif %};
7.       transition: border-color 0.4s;
8.     }

複製代碼

門開著的時候卡片會有紅框。

五、高度

1.     ha-card {
2.       height: 80px;
3.     }

複製代碼

讓不同卡片高度一致，排起來比較整齊。

用 HA 的主題變數



不要寫死顏色。用 HA 的 CSS 變數，這樣切換深色模式時會自動跟著變。

1.     ha-card {
2.       background: var(--ha-card-background);
3.       color: var(--primary-text-color);
4.       border: 1px solid var(--divider-color);
5.     }

複製代碼

常用的變數：

• --primary-color —— 主色（預設是藍色）
  
• --accent-color —— 強調色
  
• --primary-text-color —— 主要文字
  
• --secondary-text-color —— 次要文字
  
• --card-background-color / --ha-card-background —— 卡片背景
  
• --divider-color —— 分隔線
  
• --state-icon-color —— 圖示顏色
  
• --error-color / --warning-color / --success-color
  

怎麼找還有哪些變數：F12 → Elements → 選 html，
右邊的 Styles 會列出所有 CSS 變數。

也可以「設定」變數

1.     ha-card {
2.       --ha-card-background: #1a2332;
3.       --primary-text-color: #e8eaed;
4.     }

複製代碼

這樣那張卡片裡面所有用到那個變數的地方都會跟著變。

改卡片內部的元素

只改外框不夠的話，要指定內部元素。

怎麼知道元素叫什麼名字：

• 按 F12 打開開發者工具
  
• 點左上角的箭頭圖示（或按 Ctrl+Shift+C）
  
• 點你想改的東西
  
• 右邊會顯示那個元素的標籤名稱
  

Tile 卡片的常見元素：

1.     ha-card {
2.       /* 外框 */
3.     }
4.     ha-tile-icon {
5.       /* 圖示 */
6.       --tile-icon-color: #ff9800;
7.     }
8.     ha-tile-info {
9.       /* 名稱和狀態那一區 */
10.     }

複製代碼

Shadow DOM 的問題



這是 card-mod 最讓人困惑的地方。

HA 的元件用了 Shadow DOM（一種把內部結構封裝起來的技術），
外面的 CSS 進不去。

card-mod 的解法：用巢狀的 style 一層一層進去。

1. card_mod:
2.   style:
3.     ha-tile-icon$: |
4.       .shape {
5.         border-radius: 8px !important;
6.       }
7.     .: |
8.       ha-card {
9.         border-radius: 20px;
10.       }

複製代碼

語法說明：

• 元素名稱$ —— 進入那個元素的 shadowRoot
  
• . —— 代表「這一層本身」
  

老實說這個語法很難記。

我的建議：

• 九成的情況只需要 ha-card { ... }
  
• 要改內部元素的話，先去 card-mod 的社群討論串搜尋 ——
    你想改的東西大概率有人問過，而且有現成的程式碼
  
• 不要花太多時間自己摸索 Shadow DOM
  

card-mod 不能用在哪些卡片

card-mod 只對有 `ha-card` 元素的卡片有效。

不能用的：

• conditional
  
• entity_filter
  
• vertical-stack
  
• horizontal-stack
  
• grid
  

為什麼：這些是「容器型」卡片，它們自己沒有外框，
只是把別的卡片包起來。

解法：對裡面的卡片各自用 card-mod。

1. type: vertical-stack
2. cards:
3.   - type: tile
4.     entity: light.living_room
5.     card_mod:          # ← 放這裡
6.       style: |
7.         ha-card { border-radius: 20px; }
8.   - type: tile
9.     entity: light.kitchen
10.     card_mod:          # ← 也要各自寫
11.       style: |
12.         ha-card { border-radius: 20px; }

複製代碼

三個實用的完整範例

範例一：異常時卡片變紅

1. type: tile
2. entity: binary_sensor.kitchen_leak
3. card_mod:
4.   style: |
5.     ha-card {
6.       background: {% if is_state(config.entity,'on') %}
7.         rgba(229,57,53,0.15)
8.       {% else %}
9.         var(--ha-card-background)
10.       {% endif %};
11.       border: 2px solid {% if is_state(config.entity,'on') %}
12.         #e53935
13.       {% else %}
14.         transparent
15.       {% endif %};
16.       transition: all 0.4s;
17.     }

複製代碼

注意 config.entity —— 這是 card-mod 提供的變數，
指「這張卡片設定的實體」。

用它的好處：同一段 CSS 可以複製到任何卡片上，不用改實體 ID。

範例二：不可用時變半透明

1. card_mod:
2.   style: |
3.     ha-card {
4.       opacity: {% if states(config.entity) in ['unavailable','unknown'] %}
5.         0.4
6.       {% else %}
7.         1
8.       {% endif %};
9.       transition: opacity 0.3s;
10.     }

複製代碼

一眼看出哪些裝置掉線了。

範例三：警報時脈動

1. card_mod:
2.   style: |
3.     @keyframes card-blink {
4.       0%, 100% { background: rgba(229,57,53,0.25); }
5.       50%      { background: rgba(229,57,53,0.05); }
6.     }
7.     ha-card {
8.       {% if is_state(config.entity,'on') %}
9.       animation: card-blink 1.2s ease-in-out infinite;
10.       {% endif %}
11.     }

複製代碼

幾個除錯建議

• 完全沒效果 → card-mod 沒裝好，或沒清快取
  
• 範本沒生效 → style 要用 | 區塊，不要用引號包一行
  
• 改了內部元素沒反應 → Shadow DOM 問題，要用 $ 語法
  
• 被別的樣式蓋過去 → 加 !important
  
• 容器卡片沒反應 → 那些卡片不支援，要對裡面的卡片寫
  

一個提醒

card-mod 是社群外掛。

• HA 大版本更新可能會讓某些選擇器失效
  
• 用得越深，之後壞掉的機會越高
  
• 我的建議：只用在 ha-card 層級的簡單樣式，
    不要把整個儀表板的外觀都依賴它
  

如果你發現自己寫了兩百行 card-mod，那大概該考慮換一個主題或自訂卡片了。

---

下一篇：Bubble Card ——
一個不需要 card-mod 也能高度客製的卡片組。