当前位置：首页 > news >正文

button-card JavaScript模板实战：动态内容与条件渲染的终极教程

news 2026/4/20 7:14:01

button-card JavaScript模板实战：动态内容与条件渲染的终极教程

【免费下载链接】button-card❇️ Lovelace button-card for home assistant项目地址: https://gitcode.com/gh_mirrors/bu/button-card

button-card是Home Assistant Lovelace界面中一款功能强大的自定义卡片，它允许用户通过JavaScript模板实现动态内容展示和条件渲染，极大地提升了界面的交互性和个性化程度。本教程将带你全面掌握JavaScript模板的使用方法，从基础语法到高级技巧，让你轻松打造出专业级的智能家庭控制界面。

什么是JavaScript模板？

JavaScript模板是button-card提供的一项高级功能，它允许在特定配置字段中嵌入JavaScript代码。这些代码会在卡片渲染时被执行，其返回结果将作为该配置字段的值。通过这种方式，用户可以实现动态内容生成、条件判断、数据处理等复杂逻辑，使卡片能够根据实体状态、时间或其他条件实时更新显示内容。

支持JavaScript模板的配置字段在官方文档中以标识，包括name、state_display、label、icon、styles等多个核心属性。完整的支持字段列表可以在docs/source/advanced/js-templates.md中查看。

快速入门：JavaScript模板基础语法

使用JavaScript模板非常简单，只需将代码包裹在三重方括号[[[ ... ]]]中即可。这种特殊格式告诉button-card这是一段需要执行的JavaScript代码，而非普通文本。

基本用法示例

name: '[[[ if (entity.state > 42) return "Above 42"; else return "Below 42" ]]]'

对于多行代码，可以使用YAML的多行字符串语法：

name: > [[[ if (entity.state > 42) return "Above 42"; else return "Below 42"; ]]]

支持的返回类型

根据不同的配置字段，JavaScript模板需要返回不同类型的值：

文本类字段（如name、label）：返回字符串或html``对象
样式类字段（如styles）：返回CSS属性值字符串
布尔类字段（如lock.enabled、hidden）：返回布尔值
实体图片和图标（如entity_picture、icon）：返回路径字符串或mdi图标名称

核心功能：动态内容生成与条件渲染

实体状态动态显示

JavaScript模板最常用的场景之一是根据实体状态动态调整显示内容。例如，我们可以根据温度传感器的值显示不同的文本和颜色：

type: custom:button-card entity: sensor.temperature name: '[[[ return `当前温度: ${entity.state}°C` ]]]' state_display: '[[[ if (entity.state < 18) return "偏冷"; else if (entity.state < 26) return "舒适"; else return "偏热"; ]]]' styles: state: - color: '[[[ if (entity.state < 18) return "blue"; else if (entity.state < 26) return "green"; else return "red"; ]]]'

时间相关动态内容

利用内置的日期时间格式化工具，我们可以创建与时间相关的动态内容，如显示设备最后更新时间：

label: '[[[ return `最后更新: ${helpers.formatDateTime(entity.last_updated)}` ]]]'

或者显示相对时间：

label: '[[[ return helpers.relativeTime(entity.last_changed, true) ]]]'

条件样式设置

通过JavaScript模板，我们可以根据不同条件为卡片元素应用不同的样式。例如，当开关打开时显示绿色图标，关闭时显示灰色图标：

type: custom:button-card entity: switch.light icon: mdi:lightbulb styles: icon: - color: '[[[ return entity.state === "on" ? "yellow" : "gray" ]]]' - animation: '[[[ return entity.state === "on" ? "blink 2s ease-in-out infinite" : "none" ]]]'

高级技巧：变量与模块化开发

变量的定义与使用

button-card允许定义变量并在模板中复用，这极大地提高了代码的可维护性和复用性。变量可以是任何类型，包括数字、字符串、对象甚至函数。

type: custom:button-card entity: switch.skylight variables: color_on: green color_off: red is_on: '[[[ return entity.state === "on"; ]]]' color: | [[[ return variables.is_on ? variables.color_on : variables.color_off; ]]] styles: icon: - color: '[[[ return variables.color; ]]]' name: - color: '[[[ return variables.color; ]]]'

函数式变量

我们可以将变量定义为函数，实现更复杂的逻辑复用：

type: custom:button-card variables: formatTemperature: | [[[ return (temp) => { return `${temp}°C (${temp * 9/5 + 32}°F)`; } ]]] name: '[[[ return variables.formatTemperature(entity.state); ]]]'

变量依赖与高级用法

变量之间可以建立依赖关系，但要注意避免循环依赖。对于需要在每次卡片更新时都执行的代码，可以使用force_eval: true强制变量求值：

variables: alwayRun: force_eval: true value: | [[[ // 这段代码会在每次卡片更新时执行 if (!window.myUtils) { window.myUtils = { formatTime: (time) => { /* 自定义时间格式化逻辑 */ } } } ]]]

实战案例：构建智能温控面板

下面我们通过一个综合案例，展示如何使用JavaScript模板创建一个功能丰富的智能温控面板。

案例效果

实现代码

type: custom:button-card entity: climate.living_room variables: target_temp: '[[[ return entity.attributes.temperature; ]]]' current_temp: '[[[ return entity.attributes.current_temperature; ]]]' is_heating: '[[[ return entity.state === "heat"; ]]]' temp_diff: '[[[ return Math.abs(variables.current_temp - variables.target_temp); ]]]' color: | [[[ if (variables.is_heating) return "orange"; if (variables.temp_diff > 2) return "red"; return "green"; ]]] name: '[[[ return `客厅空调 ${variables.is_heating ? "加热中" : "已关闭"}` ]]]' state_display: '[[[ return `当前: ${variables.current_temp}°C / 目标: ${variables.target_temp}°C` ]]]' icon: '[[[ return variables.is_heating ? "mdi:radiator" : "mdi:radiator-off" ]]]' styles: card: - background: '[[[ return variables.is_heating ? "linear-gradient(135deg, #fff3e0 0%, #ffe0b2 100%)" : "white" ]]]' icon: - color: '[[[ return variables.color; ]]]' - animation: '[[[ return variables.is_heating ? "pulse 2s infinite" : "none" ]]]' state: - font-weight: bold - color: '[[[ return variables.color; ]]]' custom_fields: temp_diff: | [[[ return html` <div style="font-size: 0.8em; color: ${variables.temp_diff > 2 ? 'red' : 'gray'}"> ${variables.temp_diff > 2 ? `温度差过大: ${variables.temp_diff}°C` : '温度正常'} </div> `; ]]]