lovelace card mod

卡模 3

允許您將 CSS 樣式應用到 Home Assistant 前端的各種元素。

安裝中

使用 HACS 安裝或參閱本指南。

性能改進

雖然 card-mod 可以作為 lovelace 資源安裝，但如果將其作為前端模組安裝，某些功能將大大受益。

為此，請將以下內容新增至您的configuration.yaml檔案並重新啟動 Home Assistant：

 frontend :
  extra_module_url :
    - /local/card-mod.js

您需要根據安裝card-mod.js位置調整該路徑。如果您透過 HACS 安裝，這可能是/hacsfiles/lovelace-card-mod/card-mod.js 。

即使在添加extra_module_url後，HACS 自動添加的任何資源定義也可以保持原樣。

快速啟動

• 在 GUI 編輯器中開啟您的卡
• 點擊底部的“顯示程式碼編輯器”按鈕
• 將以下內容加入程式碼底部：

 card_mod :
  style : |
    ha-card {
      color: red;
    }

當您鍵入時，您應該會看到卡片上的文字變成紅色。
您還應該會看到“顯示視覺編輯器”按鈕附近彈出一個小畫筆圖示。這表示該卡具有卡片模組代碼，該代碼不會在視覺化編輯器中顯示。

用法

造型卡

透過將以下內容新增至卡片配置來設定卡片樣式：

 card_mod :
  style : <STYLES>

如果是最簡單的形式， <STYLES>是一個 CSS 字串，它將被注入到卡片的<ha-card>元素中。

注意：card-mod 僅適用於包含 ha-card 元素的卡片。這包括幾乎所有可見的卡片，但不包括conditional 、 entity_filter 、 vertical-stack 、 horizontal-stack 、 grid等。

請注意，儘管這些卡通常包含其他卡，但卡片模組可以在其中工作。
請參閱每張卡片的手冊，以了解如何為所包含的卡片指定參數。

可以設定樣式的最底部元素是<ha-card> 。

Chrome DOM 檢查器中 ha-card 元素的螢幕截圖

提示：Home Assistant 主題使用 CSS 變數。這些都可以在 card-mod 中設定和使用 - 前面加上兩個破折號：

 card_mod :
  style : |
    ha-card {
      --ha-card-background: teal;
      color: var(--primary-color);
    }

設定實體、徽章和元素的樣式

在entities和glance卡中，每個實體都可以有選項。可以透過向實體配置新增card_mod參數來單獨設定這些元素的樣式。

對於這些情況，樣式將被注入到 ShadowRoot 中，從而透過:host存取最底部的元素。

這也適用於查看picture-elements卡中的徽章和元素。

 type : entities
entities :
  - entity : light.bed_light
    card_mod :
      style : |
        :host {
          color: red;
          }
  - entity : light.ceiling_lights
    card_mod :
      style : |
        :host {
          color: green;
        }
  - entity : light.kitchen_lights
    card_mod :
      style : |
        :host {
          color: blue;
        }

更改圖示

安裝了 card-mod 後， <ha-icon>元素（例如entities 、 glance和更多卡片使用）會將其圖示設為 CSS 變數--card-mod-icon （如果存在）中找到的值。

它還會將圖示顏色設定為 CSS 變數--card-mod-icon-color （如果存在）中找到的值。這會忽略實體狀態，但仍然會變暗，除非您也將--card-mod-icon-dim設為none 。

- entity : light.bed_light
  card_mod :
    style : |
      :host {
        --card-mod-icon: mdi:bed;
      }

範本

所有樣式都可能包含 jinja2 模板，這些模板將由 Home Assistant 後端處理。

card-mod 也讓以下變數可用於範本：

• config - 卡、實體或徽章的完整配置 - （ config.entity可能特別令人感興趣）
• user - 目前登入使用者的名稱
• browser - 瀏覽器的browser_id （如果您安裝了 browser_mod）
• hash - 當前 URL 中#後面的內容（僅在第一次加載時考慮。它不會動態更新）

DOM導航

Home Assistant 廣泛使用了稱為 Shadow DOM 的東西。這允許輕鬆重複使用元件（例如ha-card或ha-icon ），但在嘗試將 CSS 樣式應用於事物時會導致一些問題。

在瀏覽器元素檢查器中瀏覽卡片時，您可能會遇到一行類似「 #shadow-root (open) 」的內容（具體內容取決於您的瀏覽器），並且注意到其中的元素不會繼承來自外部的風格。

為了對影子根內的元素進行樣式設置，您需要將style:字典而不是字串。

對於每個字典條目，該鍵將用於透過修改後的querySelector()函數選擇一個或多個元素。然後條目的值將被注入到這些元素中。

注意：修改後的querySelector()函數將在選擇器中以#shadow-root取代美元符號 ( $ )。

該過程是遞歸的，因此該值也可能是字典。 「 . 」鍵（句點）將選擇目前元素。

例子：

讓我們更改 Markdown 卡中所有第三級標題（ ### like this ）的顏色，並更改其背景。

如果我們在 chrome 的元素檢查器中查看卡片，它看起來像這樣：

<ha-card>元素是基礎，從那裡我們看到我們需要通過一個#shadow-root才能到達<h3> 。 #shadow-root位於<ha-markdown>元素內，因此我們的選擇器將是：

 ha-markdown$

它將找到第一個<ha-markdown>元素，然後找到其中的所有#shadow-root 。

要將背景新增至<ha-card> ，我們希望將樣式直接套用於基本元素，該元素具有鍵

 .

這給出了最終的樣式：

 card_mod :
  style :
    ha-markdown$ : |
      h3 {
        color: purple;
      }
    . : |
      ha-card {
        background: teal;
      } 

注意：隊列的選擇器鏈將一次尋找一個由空格或「 $ 」分隔的元素。
對於每個步驟，僅選擇第一個符合項目。
但對於鏈的最終選擇器（即在給定的字典鍵中），所有匹配的元素將被選擇。為了方便起見，以$結尾的鍊是一種特殊情況，選擇所有元素的影子根。

例如，以下命令將選擇地圖卡上第一個標記中的div元素：

 "ha-map $ ha-entity-marker $ div" : |

但以下將選擇地圖卡上所有地圖標記中的 div 元素（因為我們結束ha-entity-marker $選擇器上的第一個鍵，並在每個結果中開始新的搜尋div ）：

 " ha-map $ ha-entity-marker $ " :
  "div" : |

註 2：繼上述註解之後；由於 Home Assistant 中使用了高水準的載入順序最佳化，因此無法保證在 card-mod 尋找ha-entity-marker元素時存在它們。如果你再次打破鏈條：

 " ha-map $ " :
  " ha-entity-marker $ " :
    "div" : |

那麼card-mod將能夠在稍後的時間重試從ha-map $點查找，這可能會導致更穩定的結果。

簡而言之;如果事情似乎間歇性地進行 - 嘗試將鏈條分成幾個步驟。

調試技巧

DOM 導航在前幾次可能很難正確，但您最終會掌握它的竅門。

為了幫助您，您可以使用瀏覽器的元素檢查器來查看 card-mod 採取了哪些步驟。

• 開啟元素檢查器並找到基本元素（例如<ha-card> ）。無論您是否指定樣式，它都應該包含<card-mod>元素。
• 確保選擇了<card-mod>元素。
• 開啟瀏覽器控制台（在 Chrome 中，您可以按 Esc 鍵同時開啟控制台和檢視器）。
• 輸入$0.card_mod_input並按 Enter 鍵。
  這是鏈的步驟給出的樣式資訊。如果這是一個字串，那麼您位於鏈的末尾。如果它是一個對象，您可以繼續下一步。
• 輸入$0.card_mod_children並按 Enter 鍵。
  這是任何鏈的下一步中的任何<card-mod>元素的集合。點擊設定項目的value:中的「card-mod」會將您帶到檢查器中的<card-mod>元素，您可以繼續檢查鏈的其餘部分。
• 您也可以使用$0.card_mod_parent來尋找鏈中任何<card-mod>元素的父元素。

有關更多信息，您可以在遇到問題的卡的配置中使用以下內容。它可能會也可能不會幫助你。

 card_mod :
  debug : true

不使用<ha-card>元素設定卡片樣式

沒有<ha-element>的卡片仍然可以使用提供的custom:mod-card卡進行樣式設定。

這僅在極少數情況下是必要的，並且可能帶來的問題多於其解決的問題。

您的卡很可能包含另一張卡，在這種情況下，您應該將樣式套用到該卡。

足夠的警告。

我知道我在做什麼

 type : custom:mod-card
card :
  type : vertical-stack # for example
  ...
card_mod :
  style : |
    ha-card {
      ...
    }

mod-card 將創建一個<ha-card>元素 - 刪除背景和邊框 - 並將您的卡片放入其中。

更多範例

我的所有測試案例都可以在test/views目錄中找到。

您可以透過前往test目錄並執行以下命令在 docker 中進行示範：

 docker-compose up

然後造訪http://localhost:8125並使用使用者名稱dev和密碼dev登入。

或者您可以使用 vscode devcontainer 並執行任務「 Run hass 」。

主題

有關如何開發卡片模組主題的說明，請參閱 README-themes.md。

發展

若要為自訂卡新增卡片模組樣式功能，請參閱 README-developers.md。

---