企业官网建设流程全解析

Home Assistant System Bridge send_keypress 动作详解：向设备发送键盘按键事件

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

本文讲解 Home Assistant 中system_bridge.send_keypress动作的完整用法：它如何向已接入的 System Bridge 服务器发送单个键盘按键事件（等效于在设备物理键盘上按下某个键），涵盖图形界面配置步骤、YAML 调用方式、全部参数说明、响应数据格式，以及如何与send_text、power_command等相关动作配合，实现跨设备的自动化键盘操作。

动作概述

Send keyboard keypress动作（即system_bridge.send_keypress）向一台 System Bridge 服务器发送单个键盘按键，效果等同于在该服务器的键盘上真实按下该键。它的典型用途包括触发快捷键（如enter确认对话框、audio_play播放/暂停媒体、a等字母键配合send_text完成复杂输入）。

有两个关键特性需要先了解：

1. 结果存入响应变量：该动作会把执行结果写入response_variable指定的变量，供同一自动化或脚本的后续步骤使用（例如根据结果中的type判断按键是否成功发出）。
2. 不支持 targets：与其他动作不同，此动作不使用target（区域、设备、实体、标签均不可选）。目标服务器通过Bridge字段单独指定。

前提条件

在使用该动作之前，需要满足以下条件（依据 System Bridge 集成文档）：

• 已在目标电脑上安装并运行System Bridge应用（要求版本4.0.2 及以上，低版本不兼容）；
• 已获得 System Bridge 的token，并已通过配置流程将其接入 Home Assistant（该集成ha_config_flow: true，即通过 UI 配置流程添加）；
• 该集成以device类型接入（ha_integration_type: device），提供 sensor、binary_sensor、update、media_player、notify 等平台，同时提供多个自动化动作。

bridge参数需要填写的是这台服务器的device ID（一串十六进制 ID，形如1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d）。

通过图形界面使用

在 UI 中添加该动作的步骤：

1. 进入设置 > 自动化与场景；
2. 打开现有自动化或脚本，或选择创建新建一个；
3. 如果是新建自动化，先在When区域添加触发条件（脚本无需触发条件）；
4. 在Then do区域选择添加动作；
5. 在搜索框中搜索并选择System Bridge: Send keyboard keypress；
6. 选择Bridge服务器，选择或输入要按下的Key；
7. 选择保存。

UI 中的选项

通过 YAML 调用

在 YAML 中，该动作的名称为system_bridge.send_keypress。建议始终搭配response_variable保存执行结果，以便在后续步骤中引用：

action: action: system_bridge.send_keypress data: bridge: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d key: "a" response_variable: result

YAML 选项说明

键名采用 RobotJS 风格的命名：普通字符（如a、1）、特殊键（如enter、tab、esc）、以及媒体功能键（如audio_play、audio_pause、audio_mute等）。如果不确定某个键的写法，可在 Actions 工具中先试验再写入 YAML。

响应数据结构

执行成功后，响应变量中包含以下字段，用于确认按键已发出：

• id：请求的 ID；
• type：结果类型，例如KEYBOARD_KEY_PRESSED；
• data：所发送的数据，例如被按下的key；
• message：人类可读的结果消息。

一个典型的响应示例：

id: abc123 type: KEYBOARD_KEY_PRESSED data: key: a message: Key pressed

在后续步骤中可以通过result.type或result.message校验本次按键是否被成功处理，实现带反馈的自动化流程。

与相关动作配合

send_keypress常与同域动作组合使用，形成更完整的设备控制：

• Send keyboard text（system_bridge.send_text）：发送一段完整文本让设备输入。适合"输入一段文字后按 Enter 提交"的场景——先用send_text输入内容，再用send_keypress按下enter。
• Power command（system_bridge.power_command）：发送hibernate、lock、logout、restart、shutdown、sleep等电源命令。例如自动化中先按键解锁或暂停媒体，再让设备休眠。

三个动作的响应结构一致（id/type/data/message），因此可以统一处理响应变量。

快速验证（无需写 YAML）

配置前可以先在开发者工具中实测：打开设置 > 工具 > 动作，搜索该动作并填入bridge与key，选择执行动作即可在真实设备上看到效果，无需编写任何 YAML。确认键名可用后，再将其固化到自动化或脚本中。

如果配置后动作无反应，优先检查：System Bridge 版本是否 ≥ 4.0.2、token 是否正确、bridge字段填写的 device ID 是否对应当前目标服务器。也可以向 Home Assistant 社区寻求帮助，发帖时附上调用的动作与预期行为，便于他人定位问题。

参考

• 动作源文档：system_bridge.send_keypress
• 集成总览：System Bridge 集成
• 相关动作：send_text、power_command

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io