2025.3.4
首页 ▸ Dashboards ▸

实体卡片

实体卡片是最常见的卡片类型。它将项目分组到列表中。它可以用来显示实体的状态或属性，同时也可以包含按钮、网页链接等。

要将 实体卡片 添加到您的用户界面：

  1. 在屏幕右上角，选择编辑 按钮。
    • 如果这是您第一次编辑仪表板，将会出现 编辑仪表板 对话框。
      • 通过编辑仪表板，您将接管此仪表板的控制。
      • 这意味着当新的仪表板元素可用时，它将不再自动更新。
      • 一旦您接管控制，就无法将此特定仪表板恢复为自动更新状态。但是，您可以创建一个新的默认仪表板。
      • 要继续，请在对话框中选择三点菜单 ，然后选择 接管控制。
  2. 添加卡片并自定义操作和功能 到您的仪表板。

YAML 配置

在使用 YAML 模式时，或者在 UI 的代码编辑器中更喜欢使用 YAML 时，以下 YAML 选项可用。

Configuration Variables

Looking for your configuration file?
type string Required

entities

entities list Required

实体 ID 或 entity 对象或特殊行对象的列表（见下文）。

title string (Optional)

卡片标题。

icon string (Optional)

显示在标题左侧的图标。

show_header_toggle boolean (Optional, default: true)

开启/关闭所有实体的按钮。

theme string (Optional)

用任何已加载的主题覆盖此卡片使用的主题。有关主题的更多信息，请参见 前端文档。

state_color boolean (Optional, default: false)

设置为 true 时，实体处于活动状态时图标着色。

header map (Optional)

要渲染的头部小部件。请参见 头部文档。

footer map (Optional)

要渲染的底部小部件。请参见 底部文档。

实体选项

如果您将实体定义为对象而不是字符串（通过在实体 ID 之前添加 entity:），可以添加更多自定义和配置。

Configuration Variables

Looking for your configuration file?
entity string Required

实体 ID。

type string (Optional)

设置自定义卡片类型：custom:my-custom-card。它也可以用于强制以默认特殊行格式呈现的实体呈现为简单状态。您可以通过设置类型为 simple-entity 来做到这一点。例如，可以用于替换可编辑控件的助手，使其显示只读值。

name string (Optional)

重写友好名称。

icon string (Optional)

重写图标或实体图片。

image string (Optional)

重写实体图片。

secondary_info string (Optional)

显示附加信息。值：entity-id、last-changed、last-updated、last-triggered（仅适用于自动化和脚本）、position 或 tilt-position（仅适用于受支持的遮阳板）、brightness（仅适用于灯光）。

format string (Optional)

状态应如何格式化。目前仅用于时间戳传感器。有效值为：relative、total、date、time 和 datetime。

action_name string (Optional)

按钮标签（仅适用于 script 和 scene 行）。

state_color boolean (Optional, default: false)

设置为 true 时，实体处于活动状态时图标着色。

tap_action map (Optional)

行触摸时的操作。请参见 操作文档。

hold_action map (Optional)

行触摸和按住时的操作。请参见 操作文档。

double_tap_action map (Optional)

行双击时的操作。请参见 操作文档。

confirmation map (Optional)

对于在行中显示按钮元素的实体（例如，按钮、锁、脚本），此选项添加了按钮按下时的确认对话框。请参见 确认选项以获取配置选项。

特殊行元素

实体卡片不仅仅将实体状态作为文本输出，还支持多个特殊行，包括按钮、属性、网页链接、分隔符和部分等。

属性

Configuration Variables

Looking for your configuration file?
type string Required

attribute

entity string Required

实体 ID。

attribute string Required

从实体中显示的属性。

prefix string (Optional)

实体状态前的文本。

suffix string (Optional)

实体状态后的文本。

name string (Optional)

重写友好的实体名称。

icon string (Optional)

要使用的图标。默认为实体的图标。

format string (Optional)

属性值应如何格式化。目前仅支持时间戳属性。有有效值：relative、total、date、time 和 datetime。

按钮

带有（可选）图标、标签和单个文本按钮的行，该按钮位于行的末尾，可以触发定义的操作。

Configuration Variables

Looking for your configuration file?
type string Required

button

entity string (Optional)

实体 ID。需要提供 entity 或 name（或两者）。

name string (Optional)

行标签。需要提供 entity 或 name（或两者）。

Default:

如果提供，entity 的友好名称。

icon string (Optional)

要显示在主要标签左侧的图标。

action_name string (Optional, default: 运行)

按钮标签。

tap_action map Required

按钮触摸时的操作。请参见 操作文档。

hold_action map (Optional)

按钮触摸和按住时的操作。请参见 操作文档。

double_tap_action map (Optional)

按钮双击时的操作。请参见 操作文档。

按钮组

多个按钮并排显示在同一行中。请参见下面的示例。

Configuration Variables

Looking for your configuration file?
type string Required

buttons

entities list Required

要显示的实体列表。每个条目是实体 ID 或映射。

entity string Required

实体 ID。

icon string (Optional)

重写实体图标。

image string (Optional)

重写实体图像。

name string (Optional, default: 实体名称)

重写友好的实体名称。

show_name boolean (Optional, default: false)

如果为 false，则不显示按钮名称。

show_icon boolean (Optional, default: true)

如果为 false，则不显示图标。

tap_action map (Optional)

按钮触摸时的操作。请参见 操作文档。

hold_action map (Optional)

按钮触摸和按住时的操作。请参见 操作文档。

double_tap_action map (Optional)

按钮双击时的操作。请参见 操作文档。

Cast

特殊行以启动 Home Assistant Cast。

Configuration Variables

Looking for your configuration file?
type string Required

cast

dashboard string (Optional)

需要显示的视图的仪表板路径。

view string Required

需要显示的视图的路径。

name string (Optional, default: Home Assistant Cast)

在行中显示的名称。

icon string (Optional)

要使用的图标。

Default:

hass:television

hide_if_unavailable boolean (Optional, default: false)

如果浏览器中不支持投放，则隐藏此行。

条件

特殊行，根据实体状态进行显示。

Configuration Variables

Looking for your configuration file?
type string Required

conditional

conditions list Required

要检查的条件列表。请参见 可用条件。

row map Required

如果所有条件匹配则显示的行。可以是本页面描述的各种支持的行中的任何一种。

分隔符

Configuration Variables

Looking for your configuration file?
type string Required

divider

style map (Optional)

使用 CSS 样式化元素。

Default:

height: 1px, background-color: var(–divider-color)

部分

Configuration Variables

Looking for your configuration file?
type string Required

section

label string (Optional)

部分标签。

网页链接

Configuration Variables

Looking for your configuration file?
type string Required

weblink

url string Required

网站 URL（或内部 URL，例如 /hassio/dashboard 或 /panel_custom_name）。

name string (Optional, default: URL 路径)

链接标签。

icon string (Optional, default: mdi:link)

要显示的图标（例如，mdi:home）。

new_tab boolean (Optional, default: false)

在新标签中打开链接。如果链接是外部 URL 或下载链接，则该选项将自动为 true。如果内部 URL 应在新标签中打开，则使用此选项。

download boolean (Optional, default: false)

链接是否为下载？

示例

实体行 

type: entities
title: 实体卡片示例
show_header_toggle: true
header:
  image: "https://www.home-assistant.io/images/dashboards/header-footer/balloons-header.png"
  type: picture
entities:
  - entity: alarm_control_panel.alarm
    name: 警报面板
  - device_tracker.demo_paulus
  - switch.decorative_lights
  - group.all_lights
  - group.all_locks

按钮行

分隔符上方是常规实体行，下方是类型为 buttons 的行。请注意，常规实体行会自动显示实体名称，而按钮则需要明确指定标签/名称。

按钮行的屏幕截图 按钮行的屏幕截图。 

type: entities
entities:
  - entity: light.office_ceiling
  - entity: light.dining_ceiling
  - type: divider
  - type: buttons
    entities:
      - entity: light.office_ceiling
        name: 办公室天花板
      - entity: light.dining_ceiling
        name: 餐厅天花板

其他特殊行

其他特殊行的屏幕截图 其他特殊行的屏幕截图。 

type: entities
title: 实体卡片示例
entities:
  - type: button
    icon: mdi:power
    name: 床灯过渡
    action_name: 切换灯光
    tap_action:
      action: perform-action
      perform_action: light.toggle
      data:
        entity_id: light.bed_light
        transition: 10
  - type: divider
  - type: attribute
    entity: sun.sun
    attribute: elevation
    name: 太阳高度
    prefix: "~"
    suffix: 单位
  - type: conditional
    conditions:
      - entity: sun.sun
        state: above_horizon
    row:
      entity: sun.sun
      type: attribute
      attribute: azimuth
      icon: mdi:angle-acute
      name: 太阳方位
  - type: section
    label: 部分示例
  - type: weblink
    name: Home Assistant
    url: https://www.home-assistant.io/
    icon: mdi:home-assistant
  - type: button
    name: 重启 LibreELEC
    icon: mdi:power-cycle
    tap_action:
      action: perform-action
      confirmation:
        text: 确定要重启吗？
      perform_action: script.libreelec_power_cycle

相关主题