ha-sankey-chart 是如何構(gòu)建的Lit TypeScript Web 組件架構(gòu)完全指南【免費下載鏈接】ha-sankey-chartA Home Assistant lovelace card to display a sankey chart. For example for power consumption項目地址: https://gitcode.com/gh_mirrors/ha/ha-sankey-chartha-sankey-chart 是一款為 Home Assistant 打造的愛樂色Lovelace?；鶊D卡片用直觀的流向圖展示家庭電力、水等能耗數(shù)據(jù)。本文將帶你拆解它的完整構(gòu)建方案從 Lit 2.8 Web 組件框架、TypeScript 嚴(yán)格模式到 Rollup 打包與 Jest 測試體系帶你完整理解一個生產(chǎn)級 HA 自定義卡片 Web 組件架構(gòu)的搭建方法。技術(shù)?？傆[一張表看懂架構(gòu)選型項目只有 3 個運行時依賴其余全是開發(fā)工具鏈——這是輕依賴的典型做法角色技術(shù)版本用途UI 框架Lit2.8Web Components、響應(yīng)式屬性、模板渲染類型系統(tǒng)TypeScript4.4strict: true嚴(yán)格模式開發(fā)HA 集成custom-card-helpers1.9卡片接口約定setConfig、編輯器時間計算date-fns2.29time_period_from時間區(qū)間解析打包Rollup 7 個插件2.58TypeScript 編譯、壓縮、開發(fā)服務(wù)測試Jest ts-jest jsdom299 個測試文件 快照測試版本信息統(tǒng)一由 package.json 管理入口文件甚至直接import { version } from ../package.json加載時在瀏覽器控制臺打印帶樣式的版本橫幅方便用戶排查版本問題。項目目錄結(jié)構(gòu)每個文件一個職責(zé)src/ ├── ha-sankey-chart.ts # 卡片入口數(shù)據(jù)獲取 自動配置748 行 ├── chart.ts # 圖表渲染組件 sankey-chart-base829 行 ├── section.ts / label.ts # 單列渲染與標(biāo)簽計算 ├── layout.ts # 橫/豎向布局自動切換僅 13 行 ├── energy.ts # Home Assistant 能源數(shù)據(jù)聚合邏輯 ├── reconcile.ts # 父子數(shù)值不一致時的對齊策略 ├── migrate.ts # 舊版 v3 配置自動遷移 ├── subscribe-mixin.ts # 復(fù)刻官方 HassSubscribe 數(shù)據(jù)訂閱機制 ├── types.ts # 全局配置與節(jié)點類型定義單一事實來源 ├── utils.ts # 配置規(guī)范化、狀態(tài)格式化等純函數(shù) ├── editor/ # 可視化配置編輯器獨立組件 └── localize/ # 5 種語言的多語言文案 JSON組件分層架構(gòu)外層管數(shù)據(jù)內(nèi)層管渲染這是整個架構(gòu)最值得學(xué)習(xí)的設(shè)計——一張卡片被拆成兩層 Web 組件數(shù)據(jù)層sankey-chart入口 ha-sankey-chart.ts 用裝飾器注冊自定義元素并繼承SubscribeMixin(LitElement)customElement(sankey-chart) class SankeyChart extends SubscribeMixin(LitElement) { property({ attribute: false }) public hass!: HomeAssistantReal; state() private config!: Config; state() private states: HassEntities {};property接收 HA 注入的hass對象state的變化自動觸發(fā)重新渲染——Lit 的響應(yīng)式循環(huán)替代了所有手動 DOM 操作模塊頂層還會把卡片注冊進window.customCards讓它直接出現(xiàn)在 HA 的卡片選擇器里數(shù)據(jù)流從 YAML 到屏幕的三步走第 1 步配置校驗。HA 調(diào)用setConfig()時先做類型檢查再經(jīng)normalizeConfig()遷移、歸一化見 utils.ts配置最終只有一種內(nèi)存形態(tài)。第 2 步按需拉數(shù)據(jù)。hassSubscribe()按三種模式分發(fā)energy_date_selection輪詢等待同屏的 energy-date-selection 卡片就緒然后訂閱 Energy Dashboard 數(shù)據(jù)流time_period_from用setInterval按throttle間隔輪詢統(tǒng)計數(shù)據(jù)rate 模式power / water_flow讀取能源偏好一次性生成圖結(jié)構(gòu)之后由hass.states實時驅(qū)動。第 3 步狀態(tài)驅(qū)動渲染。統(tǒng)計結(jié)果寫入state() states子組件自動更新。渲染層sankey-chart-basechart.ts 是純渲染組件亮點在shouldUpdate里實現(xiàn)了 throttle 節(jié)流——高頻狀態(tài)變化下自動丟棄中間幀保證儀表盤不掉幀。布局決策被抽成一個 13 行的純函數(shù)layout.ts 中的shouldBeVertical()當(dāng)可用寬度小于各 section 最小寬度之和時layout: auto自動從橫向翻轉(zhuǎn)為縱向手機和桌面都能自適應(yīng)。父子數(shù)據(jù)對不齊比如總耗電 ≠ 各房間之和由 reconcile.ts 按should_be/reconcile_to配置做數(shù)值對齊避免出現(xiàn)負(fù)流量?？梢暬庉嬈鱯ankey-chart-editor編輯器是第三個獨立元素editor/index.ts實現(xiàn)custom-card-helpers的LovelaceCardEditor接口由卡片的靜態(tài)方法getConfigElement()動態(tài)創(chuàng)建。關(guān)鍵在于編輯器與圖表共用 types.ts 中的SankeyChartConfig接口YAML 里能寫的選項在 UI 里都能點出來且編輯器打開時自動把舊版 v3 配置遷移成 v4 結(jié)構(gòu)老用戶無感升級。國際化五語言包 英文兜底src/localize/localize.ts 打包了 en、cz、sk、nl、pt-BR 五套 JSON 文案讀取localStorage中的selectedLanguage決定語言任何缺失鍵自動回退到英文——多語言支持幾乎沒有增加運行時復(fù)雜度。構(gòu)建工具鏈Rollup 打出單文件產(chǎn)物rollup.config.js 的插件鏈?zhǔn)菢?biāo)準(zhǔn) HA 卡片配方nodeResolve → commonjs → typescript → json → babel → (prod) minifyHTML terserexport default [{ input: src/ha-sankey-chart.ts, output: { dir: dist, format: es }, plugins: [...plugins], }];生產(chǎn)構(gòu)建npm run build先 ESLint 再打包額外壓縮模板字面量并用 terser 混淆產(chǎn)出單文件dist/ha-sankey-chart.js開發(fā)模式npm startrollup -w監(jiān)聽 本地 3000 端口靜態(tài)服務(wù)配合 rollup.config.dev.js 在真實 HA 環(huán)境里熱調(diào)試hacs.json 只需聲明filename: ha-sankey-chart.jsHACS 用戶一條命令裝好這個 bundle。單 bundle 發(fā)布不是偶然HA 前端加載自定義卡片只信任一個腳本地址把 Lit、語言包、類型全部打進一個文件用戶零配置。測試體系Jest jsdom 快照jest.config.js 選用ts-jest預(yù)設(shè) jsdom 環(huán)境模擬瀏覽器 DOMtests/setupTests.ts 統(tǒng)一 mockcustom-card-helpers。9 個測試文件分工明確autoconfig.test.ts996 行覆蓋樓層/區(qū)域分組、碳強度拆分等自動配置全場景basic.test.ts snapshotsDOM 快照測試防止渲染結(jié)構(gòu)被無意改動migrate.test.tsv3 → v4 配置遷移的兼容性回歸。值得注意的一個細節(jié)Lit 的 CSS 模板字面量在 Jest 里會干擾 babel 轉(zhuǎn)譯配置里用transformIgnorePatterns和moduleNameMapper精確放行l(wèi)it/系列包——這是 Lit 項目寫測試的常見坑。架構(gòu)設(shè)計要點總結(jié)雙層元素拆分sankey-chart負(fù)責(zé)數(shù)據(jù)與配置sankey-chart-base只管畫——數(shù)據(jù)層壞了不用動渲染層反之亦然單一事實來源types.ts 的配置接口同時服務(wù)卡片、編輯器、測試三處杜絕結(jié)構(gòu)漂移純函數(shù)下沉布局判斷、配置遷移、狀態(tài)格式化全是無副作用函數(shù)如 utils.ts 的formatState單元測試成本極低數(shù)據(jù)層復(fù)刻官方模式subscribe-mixin.ts 移植自 HA 前端源碼訂閱/取消訂閱生命周期與官方卡片完全一致不泄漏連接單文件 ES Module 產(chǎn)物匹配 HA 的卡片加載模型HACS 一鍵安裝用戶體驗最簡。這套Lit TS 嚴(yán)格模式 Rollup 單 bundle Jest 快照的架構(gòu)是開發(fā)任何 HA 自定義卡片都可直接套用的完整參考模板。【免費下載鏈接】ha-sankey-chartA Home Assistant lovelace card to display a sankey chart. For example for power consumption項目地址: https://gitcode.com/gh_mirrors/ha/ha-sankey-chart創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考