Back to Details

ha-button-cards

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Works with Lovelace YAML dashboards and custom button-card integration.
适用于Lovelace YAML仪表盘和自定义button-card集成。

Home Assistant Button Cards

Home Assistant按钮卡片

Create interactive buttons for controlling devices, calling services, and navigating between views in Home Assistant dashboards.
为Home Assistant仪表盘创建可交互按钮，用于控制设备、调用服务和在不同视图间导航。

Overview

概述

This skill covers:
  • Native Button Card: Simple entity controls with actions
  • Custom Button Card (HACS): Advanced templating, state-based styling, multiple actions
  • Action Types: tap, hold, double-tap behaviors
  • Service Calls: Execute Home Assistant services
  • Navigation: Move between dashboard views
  • State-Based Styling: Dynamic colors and icons
本技能涵盖：
  • 原生按钮卡片：带操作功能的简单实体控制
  • 自定义按钮卡片（HACS）：高级模板、基于状态的样式、多种操作
  • 操作类型：点击、长按、双击行为
  • 服务调用：执行Home Assistant服务
  • 导航：在仪表盘视图间切换
  • 基于状态的样式：动态颜色和图标

When to Use This Skill

适用场景

Use this skill when you need to:
  • Create interactive buttons for toggling lights, switches, or climate controls
  • Add service call buttons to execute automations or scripts
  • Configure tap, hold, and double-tap actions for different behaviors
  • Build navigation buttons to move between dashboard views
  • Implement state-based styling with dynamic colors and icons
  • Use custom button-card (HACS) for advanced templating and conditional logic
Do NOT use when:
  • You only need to display sensor values without interaction (use entity card instead)
  • Building complex multi-entity cards (use entities card or custom layouts)
在以下场景中使用本技能：
  • 创建用于切换灯光、开关或温控设备的可交互按钮
  • 添加服务调用按钮以执行自动化或脚本
  • 配置点击、长按和双击操作以实现不同行为
  • 构建导航按钮以在仪表盘视图间切换
  • 实现带动态颜色和图标的基于状态样式
  • 使用自定义button-card（HACS）实现高级模板和条件逻辑
请勿在以下场景使用：
  • 仅需显示传感器数值而无需交互（请使用实体卡片）
  • 构建复杂的多实体卡片（请使用实体列表卡片或自定义布局）

Quick Start

快速开始

Basic Toggle Button

基础切换按钮

yaml
type: button
entity: light.living_room
name: Living Room
show_state: true
icon: mdi:lightbulb
tap_action:
  action: toggle
hold_action:
  action: more-info
yaml
type: button
entity: light.living_room
name: Living Room
show_state: true
icon: mdi:lightbulb
tap_action:
  action: toggle
hold_action:
  action: more-info

Service Call Button

服务调用按钮

yaml
type: button
name: Turn Off All Lights
icon: mdi:lightbulb-off
show_state: false
tap_action:
  action: perform-action
  perform_action: light.turn_off
  data:
    entity_id: all
yaml
type: button
name: Turn Off All Lights
icon: mdi:lightbulb-off
show_state: false
tap_action:
  action: perform-action
  perform_action: light.turn_off
  data:
    entity_id: all

Navigation Button

导航按钮

yaml
type: button
name: Bedroom
icon: mdi:bed
tap_action:
  action: navigate
  navigation_path: /lovelace/bedroom
yaml
type: button
name: Bedroom
icon: mdi:bed
tap_action:
  action: navigate
  navigation_path: /lovelace/bedroom

Action Types

操作类型

Home Assistant cards support three action types:
ActionTriggerUse Case
tap_action
Single tap/clickPrimary action (toggle, navigate, service call)
hold_action
Press and hold 0.5s+Secondary action (more-info, different service)
double_tap_action
Two quick tapsTertiary action (navigate, custom service)
Home Assistant卡片支持三种操作类型：
操作触发方式使用场景
tap_action
单次点击主要操作（切换、导航、服务调用）
hold_action
长按0.5秒以上次要操作（查看详情、其他服务调用）
double_tap_action
快速双击tertiary操作（导航、自定义服务）

Available Actions

可用操作

ActionDescriptionExample Use
none
Do nothingDisable interaction
toggle
Toggle entity on/offLights, switches
more-info
Show entity details dialogView sensor history
navigate
Go to another view/dashboardRoom navigation
url
Open external URLDocumentation, web apps
perform-action
(was 
call-service
)		Execute HA serviceScripts, automations, scenes
assist
Trigger voice assistantVoice commands
操作描述示例场景
none
无操作禁用交互
toggle
切换实体开关状态灯光、开关
more-info
显示实体详情对话框查看传感器历史数据
navigate
跳转到其他视图/仪表盘房间导航
url
打开外部链接文档、网页应用
perform-action
（原
call-service
）		执行Home Assistant服务脚本、自动化、场景
assist
触发语音助手语音命令

Instructions

使用说明

Using Native Button Card

使用原生按钮卡片

The native button card provides basic entity control with action support.
原生按钮卡片提供带操作支持的基础实体控制功能。

Entity Toggle Button

实体切换按钮

yaml
type: button
entity: light.bedroom
name: Bedroom Light
icon: mdi:ceiling-light
show_name: true
show_icon: true
show_state: true
tap_action:
  action: toggle
hold_action:
  action: more-info
double_tap_action:
  action: none
yaml
type: button
entity: light.bedroom
name: Bedroom Light
icon: mdi:ceiling-light
show_name: true
show_icon: true
show_state: true
tap_action:
  action: toggle
hold_action:
  action: more-info
double_tap_action:
  action: none

Climate Control Button

温控设备控制按钮

yaml
type: button
entity: climate.living_room
name: AC
icon: mdi:air-conditioner
show_state: true
tap_action:
  action: toggle
hold_action:
  action: more-info
yaml
type: button
entity: climate.living_room
name: AC
icon: mdi:air-conditioner
show_state: true
tap_action:
  action: toggle
hold_action:
  action: more-info

Scene Activation Button

场景激活按钮

yaml
type: button
name: Movie Mode
icon: mdi:movie
tap_action:
  action: perform-action
  perform_action: scene.turn_on
  target:
    entity_id: scene.movie_mode
yaml
type: button
name: Movie Mode
icon: mdi:movie
tap_action:
  action: perform-action
  perform_action: scene.turn_on
  target:
    entity_id: scene.movie_mode

Script Execution Button

脚本执行按钮

yaml
type: button
name: Good Night
icon: mdi:sleep
tap_action:
  action: perform-action
  perform_action: script.good_night
hold_action:
  action: none
yaml
type: button
name: Good Night
icon: mdi:sleep
tap_action:
  action: perform-action
  perform_action: script.good_night
hold_action:
  action: none

External URL Button

外部链接按钮

yaml
type: button
name: Router Admin
icon: mdi:router-wireless
tap_action:
  action: url
  url_path: http://192.168.1.1
yaml
type: button
name: Router Admin
icon: mdi:router-wireless
tap_action:
  action: url
  url_path: http://192.168.1.1

Assist/Voice Button

语音助手按钮

yaml
type: button
name: Voice Assistant
icon: mdi:microphone
tap_action:
  action: assist
yaml
type: button
name: Voice Assistant
icon: mdi:microphone
tap_action:
  action: assist

Service Calls

服务调用示例

Turn Off All Lights

关闭所有灯光

yaml
type: button
name: All Lights Off
icon: mdi:lightbulb-off
tap_action:
  action: perform-action
  perform_action: light.turn_off
  data:
    entity_id: all
yaml
type: button
name: All Lights Off
icon: mdi:lightbulb-off
tap_action:
  action: perform-action
  perform_action: light.turn_off
  data:
    entity_id: all

Set Climate Temperature

设置温控温度

yaml
type: button
name: Set Temp 22°C
icon: mdi:thermostat
tap_action:
  action: perform-action
  perform_action: climate.set_temperature
  target:
    entity_id: climate.living_room
  data:
    temperature: 22
yaml
type: button
name: Set Temp 22°C
icon: mdi:thermostat
tap_action:
  action: perform-action
  perform_action: climate.set_temperature
  target:
    entity_id: climate.living_room
  data:
    temperature: 22

Turn On Light with Brightness

调亮灯光

yaml
type: button
name: Dim Lights
icon: mdi:lightbulb-on-50
tap_action:
  action: perform-action
  perform_action: light.turn_on
  target:
    entity_id: light.living_room_dimmer
  data:
    brightness: 150
yaml
type: button
name: Dim Lights
icon: mdi:lightbulb-on-50
tap_action:
  action: perform-action
  perform_action: light.turn_on
  target:
    entity_id: light.living_room_dimmer
  data:
    brightness: 150

Run Automation

触发自动化

yaml
type: button
name: Trigger Automation
icon: mdi:home-automation
tap_action:
  action: perform-action
  perform_action: automation.trigger
  target:
    entity_id: automation.motion_lights
yaml
type: button
name: Trigger Automation
icon: mdi:home-automation
tap_action:
  action: perform-action
  perform_action: automation.trigger
  target:
    entity_id: automation.motion_lights

Navigation Patterns

导航模式

Simple Navigation

简单导航

yaml
type: button
name: Go to Bedroom
icon: mdi:bed
tap_action:
  action: navigate
  navigation_path: /lovelace/bedroom
yaml
type: button
name: Go to Bedroom
icon: mdi:bed
tap_action:
  action: navigate
  navigation_path: /lovelace/bedroom

Room Navigation Grid

房间导航网格

yaml
type: grid
columns: 2
cards:
  - type: button
    name: Living Room
    icon: mdi:sofa
    tap_action:
      action: navigate
      navigation_path: /lovelace/living-room

  - type: button
    name: Bedroom
    icon: mdi:bed
    tap_action:
      action: navigate
      navigation_path: /lovelace/bedroom

  - type: button
    name: Kitchen
    icon: mdi:fridge
    tap_action:
      action: navigate
      navigation_path: /lovelace/kitchen

  - type: button
    name: Outdoors
    icon: mdi:tree
    tap_action:
      action: navigate
      navigation_path: /lovelace/outdoors
yaml
type: grid
columns: 2
cards:
  - type: button
    name: Living Room
    icon: mdi:sofa
    tap_action:
      action: navigate
      navigation_path: /lovelace/living-room

  - type: button
    name: Bedroom
    icon: mdi:bed
    tap_action:
      action: navigate
      navigation_path: /lovelace/bedroom

  - type: button
    name: Kitchen
    icon: mdi:fridge
    tap_action:
      action: navigate
      navigation_path: /lovelace/kitchen

  - type: button
    name: Outdoors
    icon: mdi:tree
    tap_action:
      action: navigate
      navigation_path: /lovelace/outdoors

Back to Home Button

返回主页按钮

yaml
type: button
name: Home
icon: mdi:home
tap_action:
  action: navigate
  navigation_path: /lovelace/home
yaml
type: button
name: Home
icon: mdi:home
tap_action:
  action: navigate
  navigation_path: /lovelace/home

Custom Button Card (HACS)

自定义Button Card（HACS）

Installation: HACS → Frontend → Search "button-card"
The custom button-card provides extensive templating, state-based styling, and advanced action configurations. For complete template examples and advanced patterns, see references/custom-button-card-templates.md.
安装方法：HACS → 前端 → 搜索“button-card”
自定义button-card提供丰富的模板功能、基于状态的样式和高级操作配置。完整的模板示例和高级模式请参考references/custom-button-card-templates.md。

Basic Custom Button

基础自定义按钮

yaml
type: custom:button-card
entity: light.bedroom
name: Bedroom Light
show_state: true
icon: mdi:ceiling-light
tap_action:
  action: toggle
hold_action:
  action: more-info
yaml
type: custom:button-card
entity: light.bedroom
name: Bedroom Light
show_state: true
icon: mdi:ceiling-light
tap_action:
  action: toggle
hold_action:
  action: more-info

State-Based Styling

基于状态的样式

yaml
type: custom:button-card
entity: light.bedroom
name: Bedroom Light
show_state: true
icon: mdi:ceiling-light
color: auto
state:
  - value: "on"
    color: rgb(255, 200, 100)  # Warm white when on
    icon: mdi:ceiling-light-on
  - value: "off"
    color: rgb(100, 100, 100)  # Gray when off
    icon: mdi:ceiling-light-off
tap_action:
  action: toggle
See references/custom-button-card-templates.md for advanced examples including temperature thresholds, multiple service calls, and icon-specific tap actions.
yaml
type: custom:button-card
entity: light.bedroom
name: Bedroom Light
show_state: true
icon: mdi:ceiling-light
color: auto
state:
  - value: "on"
    color: rgb(255, 200, 100)  # 开启时为暖白色
    icon: mdi:ceiling-light-on
  - value: "off"
    color: rgb(100, 100, 100)  # 关闭时为灰色
    icon: mdi:ceiling-light-off
tap_action:
  action: toggle
更多高级示例（包括温度阈值、多服务调用、图标专属点击操作等）请参考references/custom-button-card-templates.md。

Troubleshooting

故障排除

Button Not Responding

按钮无响应

  • Check entity exists in HA (Developer Tools → States)
  • Verify service name is correct (
    perform-action
    not 
    call-service
    in newer HA)
  • Check browser console for errors (F12)
  • 检查实体是否存在于Home Assistant中（开发者工具 → 状态）
  • 确认服务名称正确（新版本Home Assistant中使用
    perform-action
    而非
    call-service
    ）
  • 查看浏览器控制台错误（F12）

Service Call Fails

服务调用失败

  • Test service in Developer Tools → Services first
  • Verify entity_id or target format
  • Check service data syntax (YAML indentation)
  • 先在开发者工具 → 服务中测试服务
  • 确认entity_id或target格式正确
  • 检查服务数据语法（YAML缩进）

Navigation Not Working

导航功能失效

  • Ensure view path is defined (e.g., 
    path: bedroom
    )
  • Use full navigation path: 
    /lovelace/bedroom
  • Check for typos in navigation_path
  • 确保视图路径已定义（例如
    path: bedroom
    ）
  • 使用完整导航路径：
    /lovelace/bedroom
  • 检查navigation_path是否有拼写错误

Custom Button Card Not Loading

自定义Button Card无法加载

  • Verify HACS installation (Frontend category)
  • Clear browser cache (Ctrl+Shift+R)
  • Check Lovelace resources (Settings → Dashboards → Resources)
  • 确认已通过HACS安装（前端分类）
  • 清除浏览器缓存（Ctrl+Shift+R）
  • 检查Lovelace资源设置（设置 → 仪表盘 → 资源）

References

参考资料

For advanced configurations, see:
  • references/action-reference.md - Complete action type documentation
  • references/service-calls.md - Common service call patterns
  • references/custom-button-card-templates.md - Reusable button templates
高级配置请参考：
  • references/action-reference.md - 完整操作类型文档
  • references/service-calls.md - 常见服务调用模式
  • references/custom-button-card-templates.md - 可复用按钮模板

Official Documentation

官方文档