ha-conditional-cards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Works with Lovelace YAML dashboards and conditional/visibility card configurations.

适用于Lovelace YAML仪表盘及条件/可见性卡片配置。

Home Assistant Conditional Cards

Control card visibility dynamically based on states, users, screen size, and complex conditions.

基于状态、用户、屏幕尺寸及复杂条件，动态控制卡片的可见性。

Overview

概述

Home Assistant provides two approaches for conditional visibility:

Conditional Card (wrapper): Shows/hides entire card based on conditions
Per-Card Visibility: Native
```
visibility
```
property on any card

Both support multiple condition types:

state: Entity matches specific state
numeric_state: Sensor value within range
screen: Screen width/media queries
user: Current user matches list
time: Current time within range
and/or: Complex logic combinations

Home Assistant提供两种实现条件可见性的方式：

Conditional Card（包装器）：根据条件显示/隐藏整个卡片
单卡片可见性：在任意卡片上使用原生
```
visibility
```
属性

两种方式均支持多种条件类型：

state：实体匹配特定状态
numeric_state：传感器数值在指定范围内
screen：屏幕宽度/媒体查询
user：当前用户匹配指定列表
time：当前时间在指定范围内
and/or：复杂逻辑组合

When to Use This Skill

适用场景

Use this skill when you need to:

Show cards only when specific conditions are met (person home, motion detected, temperature threshold)
Create responsive dashboards with mobile vs desktop layouts
Build user-specific views with different access levels
Display time-based cards (daytime vs nighttime controls)
Combine multiple conditions with AND/OR logic for complex visibility rules

Do NOT use when:

You need to modify card content based on state (use template cards instead)
Building static dashboards where all cards are always visible
Checking entity attributes directly (create template sensor first)

当你需要实现以下需求时，可使用该功能：

仅在满足特定条件时显示卡片（如有人在家、检测到移动、达到温度阈值）
创建适配移动端与桌面端的响应式仪表盘
构建具有不同访问权限的特定用户专属视图
显示基于时间的卡片（如日间/夜间控制界面）
使用AND/OR逻辑组合多个条件，实现复杂的可见性规则

请勿在以下场景使用：

需要根据状态修改卡片内容时（请使用模板卡片）
构建所有卡片始终可见的静态仪表盘时
直接检查实体属性时（请先创建模板传感器）

Quick Start

快速入门

Conditional Card (Wrapper)

Conditional Card（包装器）

yaml

type: conditional
conditions:
  - condition: state
    entity: person.john
    state: home
card:
  type: entities
  entities:
    - light.bedroom

yaml

type: conditional
conditions:
  - condition: state
    entity: person.john
    state: home
card:
  type: entities
  entities:
    - light.bedroom

Per-Card Visibility (Native)

单卡片可见性（原生）

yaml

type: entities
entities:
  - light.bedroom
visibility:
  - condition: state
    entity: person.john
    state: home

yaml

type: entities
entities:
  - light.bedroom
visibility:
  - condition: state
    entity: person.john
    state: home

Usage

使用步骤

Choose approach: Use Conditional Card wrapper for complex logic, per-card visibility for simple conditions
Select condition type: state, numeric_state, screen, user, time, and/or
Apply condition: Add
```
conditions
```
to conditional card or
```
visibility
```
to any card
Test in edit mode: Exit edit mode to test visibility (cards always show when editing)
Verify entity states: Check Developer Tools → States to debug conditions

See Condition Types Reference below for all available conditions and syntax.

选择实现方式：复杂逻辑使用Conditional Card包装器，简单条件使用单卡片可见性
选择条件类型：state、numeric_state、screen、user、time、and/or
应用条件：为Conditional Card添加
```
conditions
```
，或为任意卡片添加
```
visibility
```
在编辑模式外测试：退出编辑模式后测试可见性（编辑模式下卡片始终显示）
验证实体状态：通过开发者工具→状态页面调试条件

如需查看所有可用条件及语法，请参考下方的条件类型参考。

Condition Types Reference

条件类型参考

Condition	Parameters	Use Case
`state`	`entity` , `state`	Show when entity has specific state
`numeric_state`	`entity` , `above` , `below`	Show when sensor in range
`screen`	`media_query`	Show based on screen width
`user`	`users` (list of user IDs)	Show for specific users only
`time`	`after` , `before`	Show during specific time window
`and`	List of conditions	All conditions must be true
`or`	List of conditions	At least one condition must be true

条件类型	参数	使用场景
`state`	`entity` , `state`	当实体匹配特定状态时显示
`numeric_state`	`entity` , `above` , `below`	当传感器数值在指定范围内时显示
`screen`	`media_query`	基于屏幕宽度显示
`user`	`users` （用户ID列表）	仅对指定用户显示
`time`	`after` , `before`	在指定时间窗口内显示
`and`	条件列表	所有条件必须同时满足
`or`	条件列表	至少满足一个条件

State Conditions

状态条件

Basic State Match

基础状态匹配

yaml

type: conditional
conditions:
  - condition: state
    entity: binary_sensor.motion_living_room
    state: "on"
card:
  type: camera
  entity: camera.living_room

yaml

type: conditional
conditions:
  - condition: state
    entity: binary_sensor.motion_living_room
    state: "on"
card:
  type: camera
  entity: camera.living_room

Multiple State Options

多状态选项

yaml

visibility:
  - condition: state
    entity: climate.living_room
    state_not:
      - "off"
      - unavailable

yaml

visibility:
  - condition: state
    entity: climate.living_room
    state_not:
      - "off"
      - unavailable

State with Attributes (Workaround)

带属性的状态条件（替代方案）

Note: Native conditional cards don't support attribute conditions. Create a template sensor instead.

yaml

undefined

注意：原生条件卡片不支持直接检查属性。请先创建模板传感器。

yaml

undefined

In configuration.yaml

template:

sensor:
- name: "AC Mode Cool" state: "{{ state_attr('climate.living_room', 'hvac_mode') == 'cool' }}"

template:

sensor:
- name: "AC Mode Cool" state: "{{ state_attr('climate.living_room', 'hvac_mode') == 'cool' }}"

In dashboard

visibility:

condition: state entity: sensor.ac_mode_cool state: "True"

undefined

visibility:

condition: state entity: sensor.ac_mode_cool state: "True"

undefined

Numeric State Conditions

数值状态条件

Temperature Range

温度范围

yaml

type: entities
entities:
  - climate.bedroom
visibility:
  - condition: numeric_state
    entity: sensor.temperature
    above: 18
    below: 30

yaml

type: entities
entities:
  - climate.bedroom
visibility:
  - condition: numeric_state
    entity: sensor.temperature
    above: 18
    below: 30

Above Threshold

低于阈值

yaml

visibility:
  - condition: numeric_state
    entity: sensor.battery
    below: 20  # Show when battery < 20%

yaml

visibility:
  - condition: numeric_state
    entity: sensor.battery
    below: 20  # Show when battery < 20%

Between Values

介于两值之间

yaml

visibility:
  - condition: numeric_state
    entity: sensor.humidity
    above: 40
    below: 60  # Show when 40% < humidity < 60%

yaml

visibility:
  - condition: numeric_state
    entity: sensor.humidity
    above: 40
    below: 60  # Show when 40% < humidity < 60%

Screen/Responsive Conditions

屏幕/响应式条件

Mobile Only

仅移动端

yaml

visibility:
  - condition: screen
    media_query: "(max-width: 600px)"

yaml

visibility:
  - condition: screen
    media_query: "(max-width: 600px)"

Desktop Only

仅桌面端

yaml

visibility:
  - condition: screen
    media_query: "(min-width: 1280px)"

yaml

visibility:
  - condition: screen
    media_query: "(min-width: 1280px)"

Tablet Range

平板适配

yaml

visibility:
  - condition: screen
    media_query: "(min-width: 601px) and (max-width: 1279px)"

yaml

visibility:
  - condition: screen
    media_query: "(min-width: 601px) and (max-width: 1279px)"

Common Media Queries

常用媒体查询

yaml

undefined

yaml

undefined

Mobile (portrait)

media_query: "(max-width: 600px)"

Tablet (portrait)

media_query: "(min-width: 601px) and (max-width: 900px)"

Desktop

media_query: "(min-width: 1280px)"

Landscape orientation

media_query: "(orientation: landscape)"

Portrait orientation

media_query: "(orientation: portrait)"

undefined

media_query: "(orientation: portrait)"

undefined

User Conditions

用户条件

Single User

单个用户

yaml

visibility:
  - condition: user
    users:
      - 1234567890abcdef  # User ID (not username)

yaml

visibility:
  - condition: user
    users:
      - 1234567890abcdef  # User ID (not username)

Multiple Users (Admin Access)

多用户（管理员权限）

yaml

type: entities
entities:
  - switch.advanced_settings
visibility:
  - condition: user
    users:
      - 1234567890abcdef  # Admin user 1
      - fedcba0987654321  # Admin user 2

Finding User IDs:

Go to Settings → People
Click on user
User ID is in the URL:
```
/config/person/USER_ID_HERE
```

yaml

type: entities
entities:
  - switch.advanced_settings
visibility:
  - condition: user
    users:
      - 1234567890abcdef  # Admin user 1
      - fedcba0987654321  # Admin user 2

查找用户ID的方法：

进入设置 → 人员
点击目标用户
用户ID位于URL中：
```
/config/person/USER_ID_HERE
```

Time Conditions

时间条件

During Daytime

日间显示

yaml

visibility:
  - condition: time
    after: "06:00:00"
    before: "22:00:00"

yaml

visibility:
  - condition: time
    after: "06:00:00"
    before: "22:00:00"

Night Mode Cards

夜间模式卡片

yaml

visibility:
  - condition: time
    after: "22:00:00"
    before: "06:00:00"

yaml

visibility:
  - condition: time
    after: "22:00:00"
    before: "06:00:00"

Business Hours

工作时间

yaml

visibility:
  - condition: time
    after: "09:00:00"
    before: "17:00:00"
    weekday:
      - mon
      - tue
      - wed
      - thu
      - fri

yaml

visibility:
  - condition: time
    after: "09:00:00"
    before: "17:00:00"
    weekday:
      - mon
      - tue
      - wed
      - thu
      - fri

Complex Logic (AND/OR)

复杂逻辑（AND/OR）

AND Condition (All Must Be True)

AND条件（需满足所有条件）

yaml

visibility:
  - condition: and
    conditions:
      - condition: state
        entity: person.john
        state: home
      - condition: numeric_state
        entity: sensor.temperature
        below: 18
      - condition: time
        after: "06:00:00"
        before: "23:00:00"

yaml

visibility:
  - condition: and
    conditions:
      - condition: state
        entity: person.john
        state: home
      - condition: numeric_state
        entity: sensor.temperature
        below: 18
      - condition: time
        after: "06:00:00"
        before: "23:00:00"

OR Condition (At Least One Must Be True)

OR条件（满足任一条件即可）

yaml

visibility:
  - condition: or
    conditions:
      - condition: state
        entity: person.john
        state: home
      - condition: state
        entity: person.jane
        state: home

yaml

visibility:
  - condition: or
    conditions:
      - condition: state
        entity: person.john
        state: home
      - condition: state
        entity: person.jane
        state: home

Nested Logic

嵌套逻辑

yaml

visibility:
  - condition: and
    conditions:
      # Show during daytime...
      - condition: time
        after: "06:00:00"
        before: "22:00:00"
      # ...AND (someone is home OR security is armed)
      - condition: or
        conditions:
          - condition: state
            entity: person.john
            state: home
          - condition: state
            entity: alarm_control_panel.home
            state: armed_away

yaml

visibility:
  - condition: and
    conditions:
      # Show during daytime...
      - condition: time
        after: "06:00:00"
        before: "22:00:00"
      # ...AND (someone is home OR security is armed)
      - condition: or
        conditions:
          - condition: state
            entity: person.john
            state: home
          - condition: state
            entity: alarm_control_panel.home
            state: armed_away

Real-World Patterns

实际应用场景

Show Camera When Motion Detected

检测到移动时显示摄像头

yaml

type: conditional
conditions:
  - condition: state
    entity: binary_sensor.motion_living_room
    state: "on"
card:
  type: camera
  entity: camera.living_room

yaml

type: conditional
conditions:
  - condition: state
    entity: binary_sensor.motion_living_room
    state: "on"
card:
  type: camera
  entity: camera.living_room

Mobile vs Desktop Layout

移动端与桌面端差异化布局

yaml

undefined

yaml

undefined

Mobile: Compact view

type: custom:mushroom-chips-card visibility:

condition: screen media_query: "(max-width: 600px)"

type: custom:mushroom-chips-card visibility:

condition: screen media_query: "(max-width: 600px)"

Desktop: Detailed view

type: grid columns: 3 visibility:

condition: screen media_query: "(min-width: 1280px)"

undefined

type: grid columns: 3 visibility:

condition: screen media_query: "(min-width: 1280px)"

undefined

User-Specific Controls

特定用户专属控制项

yaml

type: entities
entities:
  - switch.developer_mode
visibility:
  - condition: user
    users:
      - 1234567890abcdef  # Admin user ID (Settings → People → URL)

For more patterns (low battery alerts, temperature warnings, occupied rooms, time-based controls), see

references/advanced-patterns.md

yaml

type: entities
entities:
  - switch.developer_mode
visibility:
  - condition: user
    users:
      - 1234567890abcdef  # Admin user ID (Settings → People → URL)

如需更多场景（如低电量提醒、温度预警、房间占用状态、时间控制项等），请查看

references/advanced-patterns.md

。

Best Practices

最佳实践

Combine approaches: Use conditional card for complex logic, per-card visibility for simple conditions
Test in edit mode: Exit edit mode to test visibility (cards always visible when editing)
Use helper entities: Create template sensors for attribute-based or complex conditions
Add buffer zones: Use hysteresis for numeric conditions to prevent flapping
Document user IDs: Keep reference of user IDs for maintenance
Screen conditions: Use media queries for responsive mobile/desktop layouts

组合使用两种方式：复杂逻辑用Conditional Card包装器，简单条件用单卡片可见性
在编辑模式外测试：退出编辑模式后测试可见性（编辑模式下卡片始终显示）
使用辅助实体：针对基于属性或复杂的条件，创建模板传感器
添加缓冲区间：数值条件使用滞后逻辑，避免频繁切换
记录用户ID：保存用户ID以便后续维护
屏幕条件：使用媒体查询实现移动端/桌面端响应式布局

Limitations

局限性

Cannot check attributes directly - Create template sensor to expose attribute as entity state.

No template conditions - Create template binary sensor instead.

Always visible in edit mode - Must exit edit mode to test visibility behavior.

For detailed workarounds, see

references/advanced-patterns.md

无法直接检查属性 - 需创建模板传感器，将属性转换为实体状态。

无模板条件 - 需创建模板二进制传感器替代。

编辑模式下始终可见 - 必须退出编辑模式才能测试可见性行为。

如需详细替代方案，请查看

references/advanced-patterns.md

。

Troubleshooting

支持文件

Issue	Solution
Card not hiding	Exit edit mode, check entity state, verify YAML indentation
User condition fails	Use user ID (not username), find in Settings → People → URL
Time condition fails	Use 24-hour format `"23:00:00"` , check HA timezone
Numeric condition fails	Verify sensor has numeric state (not "unknown")
Screen condition fails	Test on actual device (not browser resize)

For detailed troubleshooting, see

references/advanced-patterns.md

references/advanced-patterns.md - 复杂逻辑场景、实际应用案例、替代方案、详细故障排查、最佳实践、常用媒体查询

Supporting Files

官方文档

references/advanced-patterns.md - Complex logic patterns, real-world use cases, workarounds, detailed troubleshooting, best practices, common media queries

Official Documentation

—