Kiosker 黑屏遮罩完全指南用kiosker.blackout_set动作掌控你的 iPad/iPhone 信息屏【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.iokiosker.blackout_set是 Home Assistant 中Kiosker集成提供的核心动作Action用于在 Kiosker 设备iPad/iPhone 上的 Web Kiosk 应用上显示或隐藏一个全屏黑屏遮罩blackout overlay。本文以 kiosker.blackout_set 官方动作文档 为骨架结合 Kiosker 集成文档 中的实体与能力说明完整讲解该动作的 UI 配置、YAML 参数、完整示例与实用注意事项读完即可在自动化与脚本中熟练运用会议中锁屏、离家熄屏、状态提示等典型场景。动作概览这个动作能做什么kiosker.blackout_set在 Kiosker 设备上显示一个覆盖整个屏幕的全屏遮罩。它天然适合以下场景会议进行中隐藏信息屏上正在显示的页面家中无人时黑屏以免显示隐私内容或消耗注意力显示一条状态消息如马上回来配合图标、配色与提示音在某个条件未满足前如expire: 0一直阻断屏幕内容直到条件清除。隐藏遮罩的方式有两种再次调用本动作并将Visible设为关闭visible: false或使用 Kiosker 集成提供的Clear blackout按钮实体见 source/_integrations/kiosker.markdown。该动作自 Home Assistant 2026.5 起可用与 Kiosker 集成同期发布并与其姊妹动作 kiosker.navigate_url导航到指定 URL配合使用效果最佳。使用前提先完成 Kiosker 集成配置要使用kiosker.blackout_set前提是已在 Home Assistant 中配置好 Kiosker 集成Kiosker App 需为Pro 版本或有有效订阅官方提供 7 天免费试用设备需运行Kiosker 26.4.1 或更高版本集成才能完全正常工作在 Kiosker 设置中启用 API 服务器生成访问令牌access token并确认设备的 IP 地址在 Home Assistant 中通过配置流程添加设备填入 HostIP 或主机名、API Token并按需启用 SSL 与证书校验。集成配置细节可参阅 Kiosker 集成文档。配置完成后设备实体出现在 Home Assistant 中自动化与脚本即可调用kiosker.blackout_set。从 UI 使用可视化配置黑屏遮罩如果你习惯在界面中构建自动化和脚本可以完全通过表单完成配置无需编写 YAML。官方文档给出的操作路径如下见 kiosker.blackout_set.markdown进入SettingsAutomations scenes打开现有自动化或脚本或选择Create automationCreate new automation若是新建自动化在When部分添加触发条件脚本无需触发条件在Then do部分选择Add action在搜索框中搜索并选择Kiosker: Set blackout在Device下选择目标 Kiosker 设备打开Visible开关以显示遮罩关闭则以隐藏遮罩可选添加消息文本、自定义颜色、图标或关闭按钮点击Save保存。UI 选项说明选项说明是否必填Device要应用黑屏遮罩的 Kiosker 设备必填Visible显示或隐藏黑屏遮罩默认开启选填Text遮罩上显示的消息文本选填Background遮罩背景色RGB 格式例如[10, 10, 60]默认黑色选填Foreground遮罩文字颜色RGB 格式默认白色选填Icon遮罩上显示的图标填入 SF Symbols 名称例如person.2.fill选填Expire遮罩自动消失前的停留秒数设为0则保持显示直到手动清除默认 60 秒选填Dismissible开启后遮罩上出现一个按钮用户点击即可关闭遮罩默认关闭选填Button background关闭按钮的背景色RGB 格式默认白色选填Button foreground关闭按钮的文字颜色RGB 格式默认黑色选填Button text关闭按钮的标签文字选填Sound遮罩出现时播放的提示音填入 SystemSoundID 编号例如1007选填在 YAML 中使用参数完整参考如果你直接编写 YAML或在界面配置时想确切了解底层字段需要以kiosker.blackout_set作为动作名来引用。官方给出的基础示例见 kiosker.blackout_set.markdownaction: kiosker.blackout_set data: device_id: YOUR_DEVICE_ID visible: true text: Be right back expire: 300YAML 参数说明字段类型必填默认值说明device_idstring是—要应用黑屏遮罩的 Kiosker 设备 IDvisibleboolean否true显示或隐藏黑屏遮罩textstring否—遮罩上显示的消息文本backgroundlist否[0, 0, 0]黑色遮罩背景色RGB 格式三个 0–255 的整数红、绿、蓝foregroundlist否[255, 255, 255]白色遮罩文字颜色RGB 格式三个 0–255 的整数iconstring否—遮罩上显示的 SF Symbols 图标名称如person.2.fillexpireinteger否60遮罩自动消失前的停留秒数0表示保持显示直到手动清除最大 3600 秒dismissibleboolean否false用户是否可通过点击按钮关闭遮罩button_backgroundlist否[255, 255, 255]白色关闭按钮背景色RGB 格式button_foregroundlist否[0, 0, 0]黑色关闭按钮文字颜色RGB 格式button_textstring否—关闭按钮的标签文字soundstring否—遮罩出现时播放的提示音SystemSoundID 编号如1007注意两点颜色参数一律是三个 0–255 整数组成的列表expire有 3600 秒的上限需要更长时间保持遮罩时应使用0。实战示例示例一带自定义配色的可关闭遮罩适用于会议场景——显示一条会议进行中的消息用户看完可点击Dismiss按钮自行关闭见 kiosker.blackout_set.markdownActionKiosker: Set blackoutDeviceMeeting room displayVisibleonTextMeeting in progressBackground[10, 10, 60]Iconperson.2.fillExpire3600DismissibleonButton textDismiss对应的 YAMLaction: kiosker.blackout_set data: device_id: YOUR_DEVICE_ID visible: true text: Meeting in progress background: - 10 - 10 - 60 foreground: - 255 - 255 - 255 icon: person.2.fill expire: 3600 dismissible: true button_background: - 255 - 255 - 255 button_foreground: - 10 - 10 - 60 button_text: Dismiss sound: 1007示例二全家离家时黑屏当所有人离开家时覆盖屏幕使空屋中的信息屏不再显示任何内容见 kiosker.blackout_set.markdown。注意expire: 0表示遮罩会一直保持直到你主动清除automation: alias: Black out display when no one is home triggers: - trigger: zone.occupancy_cleared options: zone: zone.home actions: - action: kiosker.blackout_set data: device_id: YOUR_DEVICE_ID visible: true expire: 0示例三有人回家时清除黑屏当第一个人到家时移除遮罩并恢复正常显示见 kiosker.blackout_set.markdown。这里的核心是visible: false——清除遮罩不需要新动作再次调用本动作并关闭可见性即可automation: alias: Clear kiosk blackout on arrival triggers: - trigger: zone.occupancy_detected options: zone: zone.home actions: - action: kiosker.blackout_set data: device_id: YOUR_DEVICE_ID visible: false将示例二与示例三组合就构成了离家自动熄屏、回家自动恢复的完整闭环这也是该动作最典型的用法之一。示例四与导航动作联动kiosker.blackout_set与kiosker.navigate_url是官方标注的关联动作见文档 front matter 的related_actions字段。典型思路是夜间用 kiosker.navigate_url 将屏幕导航回主面板而用kiosker.blackout_set在特定时段或条件下直接遮盖屏幕。二者的device_id字段语义一致可以互相替换使用。值得注意的行为细节遮罩是全屏且绝对的它会覆盖屏幕上的一切包括浏览器和其下所有内容见 kiosker.blackout_set.markdown。expire计时器可重置设置了expire后遮罩会按秒数自动消失而每次显示新的遮罩都会重置该计时器。清除方式再次调用动作并传visible: false或使用 Kiosker 设备页上的Clear blackout按钮实体。SF Symbols图标字段使用的是苹果 SF Symbols 图标库的名称如person.2.fill可在 Apple SF Symbols 页面浏览可用图标。SystemSoundID提示音字段填入的是 iOS 系统声音编号如1007可在 iOS 系统声音库中查阅可用编号。物理功能限制受苹果设备控制策略限制此集成无法控制屏幕开关、设备休眠等物理功能见 source/_integrations/kiosker.markdown黑屏遮罩是软件层的覆盖而非真正的熄屏。与实体联动监控与手动控制黑屏状态Kiosker 集成围绕黑屏功能暴露了多组实体见 source/_integrations/kiosker.markdown可与kiosker.blackout_set联动实现状态监控与手动兜底二进制传感器Blackout state显示屏幕当前是否处于黑屏状态可用于自动化触发条件判断二进制传感器Blackout dismissible默认禁用显示当前黑屏是否可被用户关闭传感器均默认禁用Blackout text当前遮罩文本、Blackout iconSF Symbols 图标名、Blackout background color/Blackout foreground color以十六进制字符串报告颜色如#000000、Blackout expiry遮罩剩余秒数、Blackout button background color/Blackout button foreground color/Blackout button text/Blackout sound关闭按钮与提示音相关状态。所有传感器在没有可见黑屏时默认为 unknown按钮实体Clear blackout手动清除当前黑屏作为 UI 层兜底手段集成每 15 秒从设备拉取一次数据见 source/_integrations/kiosker.markdown因此实体状态存在最多 15 秒的刷新延迟。快速验证Try it yourself想不写一行 YAML 就验证效果官方建议打开SettingsToolsActions开发者工具中的服务调用界面搜索kiosker.blackout_set填写字段后点击Perform action即可在真实设备上立即看到遮罩效果非常适合用来调试配色、文本与提示音参数。如果自动化触发了动作但设备没有反应可参考 Kiosker 集成文档 的排障清单确认 Kiosker App 在前台运行、API 已启用、令牌未变更、Host/IP 正确、IP 过滤白名单包含主机、TLS 证书有效且受信任若令牌被重新生成Home Assistant 会触发重新认证流程选择Reconfigure并输入新令牌即可无需重建实体与自动化。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Kiosker 黑屏遮罩完全指南：用 `kiosker.blackout_set` 动作掌控你的 iPad/iPhone 信息屏
Kiosker 黑屏遮罩完全指南用kiosker.blackout_set动作掌控你的 iPad/iPhone 信息屏【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.iokiosker.blackout_set是 Home Assistant 中Kiosker集成提供的核心动作Action用于在 Kiosker 设备iPad/iPhone 上的 Web Kiosk 应用上显示或隐藏一个全屏黑屏遮罩blackout overlay。本文以 kiosker.blackout_set 官方动作文档 为骨架结合 Kiosker 集成文档 中的实体与能力说明完整讲解该动作的 UI 配置、YAML 参数、完整示例与实用注意事项读完即可在自动化与脚本中熟练运用会议中锁屏、离家熄屏、状态提示等典型场景。动作概览这个动作能做什么kiosker.blackout_set在 Kiosker 设备上显示一个覆盖整个屏幕的全屏遮罩。它天然适合以下场景会议进行中隐藏信息屏上正在显示的页面家中无人时黑屏以免显示隐私内容或消耗注意力显示一条状态消息如马上回来配合图标、配色与提示音在某个条件未满足前如expire: 0一直阻断屏幕内容直到条件清除。隐藏遮罩的方式有两种再次调用本动作并将Visible设为关闭visible: false或使用 Kiosker 集成提供的Clear blackout按钮实体见 source/_integrations/kiosker.markdown。该动作自 Home Assistant 2026.5 起可用与 Kiosker 集成同期发布并与其姊妹动作 kiosker.navigate_url导航到指定 URL配合使用效果最佳。使用前提先完成 Kiosker 集成配置要使用kiosker.blackout_set前提是已在 Home Assistant 中配置好 Kiosker 集成Kiosker App 需为Pro 版本或有有效订阅官方提供 7 天免费试用设备需运行Kiosker 26.4.1 或更高版本集成才能完全正常工作在 Kiosker 设置中启用 API 服务器生成访问令牌access token并确认设备的 IP 地址在 Home Assistant 中通过配置流程添加设备填入 HostIP 或主机名、API Token并按需启用 SSL 与证书校验。集成配置细节可参阅 Kiosker 集成文档。配置完成后设备实体出现在 Home Assistant 中自动化与脚本即可调用kiosker.blackout_set。从 UI 使用可视化配置黑屏遮罩如果你习惯在界面中构建自动化和脚本可以完全通过表单完成配置无需编写 YAML。官方文档给出的操作路径如下见 kiosker.blackout_set.markdown进入SettingsAutomations scenes打开现有自动化或脚本或选择Create automationCreate new automation若是新建自动化在When部分添加触发条件脚本无需触发条件在Then do部分选择Add action在搜索框中搜索并选择Kiosker: Set blackout在Device下选择目标 Kiosker 设备打开Visible开关以显示遮罩关闭则以隐藏遮罩可选添加消息文本、自定义颜色、图标或关闭按钮点击Save保存。UI 选项说明选项说明是否必填Device要应用黑屏遮罩的 Kiosker 设备必填Visible显示或隐藏黑屏遮罩默认开启选填Text遮罩上显示的消息文本选填Background遮罩背景色RGB 格式例如[10, 10, 60]默认黑色选填Foreground遮罩文字颜色RGB 格式默认白色选填Icon遮罩上显示的图标填入 SF Symbols 名称例如person.2.fill选填Expire遮罩自动消失前的停留秒数设为0则保持显示直到手动清除默认 60 秒选填Dismissible开启后遮罩上出现一个按钮用户点击即可关闭遮罩默认关闭选填Button background关闭按钮的背景色RGB 格式默认白色选填Button foreground关闭按钮的文字颜色RGB 格式默认黑色选填Button text关闭按钮的标签文字选填Sound遮罩出现时播放的提示音填入 SystemSoundID 编号例如1007选填在 YAML 中使用参数完整参考如果你直接编写 YAML或在界面配置时想确切了解底层字段需要以kiosker.blackout_set作为动作名来引用。官方给出的基础示例见 kiosker.blackout_set.markdownaction: kiosker.blackout_set data: device_id: YOUR_DEVICE_ID visible: true text: Be right back expire: 300YAML 参数说明字段类型必填默认值说明device_idstring是—要应用黑屏遮罩的 Kiosker 设备 IDvisibleboolean否true显示或隐藏黑屏遮罩textstring否—遮罩上显示的消息文本backgroundlist否[0, 0, 0]黑色遮罩背景色RGB 格式三个 0–255 的整数红、绿、蓝foregroundlist否[255, 255, 255]白色遮罩文字颜色RGB 格式三个 0–255 的整数iconstring否—遮罩上显示的 SF Symbols 图标名称如person.2.fillexpireinteger否60遮罩自动消失前的停留秒数0表示保持显示直到手动清除最大 3600 秒dismissibleboolean否false用户是否可通过点击按钮关闭遮罩button_backgroundlist否[255, 255, 255]白色关闭按钮背景色RGB 格式button_foregroundlist否[0, 0, 0]黑色关闭按钮文字颜色RGB 格式button_textstring否—关闭按钮的标签文字soundstring否—遮罩出现时播放的提示音SystemSoundID 编号如1007注意两点颜色参数一律是三个 0–255 整数组成的列表expire有 3600 秒的上限需要更长时间保持遮罩时应使用0。实战示例示例一带自定义配色的可关闭遮罩适用于会议场景——显示一条会议进行中的消息用户看完可点击Dismiss按钮自行关闭见 kiosker.blackout_set.markdownActionKiosker: Set blackoutDeviceMeeting room displayVisibleonTextMeeting in progressBackground[10, 10, 60]Iconperson.2.fillExpire3600DismissibleonButton textDismiss对应的 YAMLaction: kiosker.blackout_set data: device_id: YOUR_DEVICE_ID visible: true text: Meeting in progress background: - 10 - 10 - 60 foreground: - 255 - 255 - 255 icon: person.2.fill expire: 3600 dismissible: true button_background: - 255 - 255 - 255 button_foreground: - 10 - 10 - 60 button_text: Dismiss sound: 1007示例二全家离家时黑屏当所有人离开家时覆盖屏幕使空屋中的信息屏不再显示任何内容见 kiosker.blackout_set.markdown。注意expire: 0表示遮罩会一直保持直到你主动清除automation: alias: Black out display when no one is home triggers: - trigger: zone.occupancy_cleared options: zone: zone.home actions: - action: kiosker.blackout_set data: device_id: YOUR_DEVICE_ID visible: true expire: 0示例三有人回家时清除黑屏当第一个人到家时移除遮罩并恢复正常显示见 kiosker.blackout_set.markdown。这里的核心是visible: false——清除遮罩不需要新动作再次调用本动作并关闭可见性即可automation: alias: Clear kiosk blackout on arrival triggers: - trigger: zone.occupancy_detected options: zone: zone.home actions: - action: kiosker.blackout_set data: device_id: YOUR_DEVICE_ID visible: false将示例二与示例三组合就构成了离家自动熄屏、回家自动恢复的完整闭环这也是该动作最典型的用法之一。示例四与导航动作联动kiosker.blackout_set与kiosker.navigate_url是官方标注的关联动作见文档 front matter 的related_actions字段。典型思路是夜间用 kiosker.navigate_url 将屏幕导航回主面板而用kiosker.blackout_set在特定时段或条件下直接遮盖屏幕。二者的device_id字段语义一致可以互相替换使用。值得注意的行为细节遮罩是全屏且绝对的它会覆盖屏幕上的一切包括浏览器和其下所有内容见 kiosker.blackout_set.markdown。expire计时器可重置设置了expire后遮罩会按秒数自动消失而每次显示新的遮罩都会重置该计时器。清除方式再次调用动作并传visible: false或使用 Kiosker 设备页上的Clear blackout按钮实体。SF Symbols图标字段使用的是苹果 SF Symbols 图标库的名称如person.2.fill可在 Apple SF Symbols 页面浏览可用图标。SystemSoundID提示音字段填入的是 iOS 系统声音编号如1007可在 iOS 系统声音库中查阅可用编号。物理功能限制受苹果设备控制策略限制此集成无法控制屏幕开关、设备休眠等物理功能见 source/_integrations/kiosker.markdown黑屏遮罩是软件层的覆盖而非真正的熄屏。与实体联动监控与手动控制黑屏状态Kiosker 集成围绕黑屏功能暴露了多组实体见 source/_integrations/kiosker.markdown可与kiosker.blackout_set联动实现状态监控与手动兜底二进制传感器Blackout state显示屏幕当前是否处于黑屏状态可用于自动化触发条件判断二进制传感器Blackout dismissible默认禁用显示当前黑屏是否可被用户关闭传感器均默认禁用Blackout text当前遮罩文本、Blackout iconSF Symbols 图标名、Blackout background color/Blackout foreground color以十六进制字符串报告颜色如#000000、Blackout expiry遮罩剩余秒数、Blackout button background color/Blackout button foreground color/Blackout button text/Blackout sound关闭按钮与提示音相关状态。所有传感器在没有可见黑屏时默认为 unknown按钮实体Clear blackout手动清除当前黑屏作为 UI 层兜底手段集成每 15 秒从设备拉取一次数据见 source/_integrations/kiosker.markdown因此实体状态存在最多 15 秒的刷新延迟。快速验证Try it yourself想不写一行 YAML 就验证效果官方建议打开SettingsToolsActions开发者工具中的服务调用界面搜索kiosker.blackout_set填写字段后点击Perform action即可在真实设备上立即看到遮罩效果非常适合用来调试配色、文本与提示音参数。如果自动化触发了动作但设备没有反应可参考 Kiosker 集成文档 的排障清单确认 Kiosker App 在前台运行、API 已启用、令牌未变更、Host/IP 正确、IP 过滤白名单包含主机、TLS 证书有效且受信任若令牌被重新生成Home Assistant 会触发重新认证流程选择Reconfigure并输入新令牌即可无需重建实体与自动化。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考