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