使用 yamaha.menu_cursor 动作控制 Yamaha 功放的屏幕菜单光标-创锋一号

使用 yamaha.menu_cursor 动作控制 Yamaha 功放的屏幕菜单光标

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

本篇技术指南以 Home Assistant 官方文档仓库中的 yamaha.menu_cursor 动作文档为骨架，系统讲解如何通过 Home Assistant 向 Yamaha 网络功放发送屏幕菜单（OSD）光标按键指令——包括上下左右移动、确认（select）与返回（return）。读完本文，你将掌握该动作在 UI 与 YAML 两种场景下的完整用法、cursor参数的合法取值，以及目标（target）选择机制，并能结合yamaha集成的配置与配套动作（yamaha.enable_output、yamaha.select_scene）搭建出完整的家庭影院自动化。

动作是什么：一条菜单光标指令

yamaha.menu_cursor是 Home Assistant 中yamaha域提供的动作（action，旧称 service），其作用等价于在 Yamaha 功放遥控器上按下一个方向键：将功放电视屏幕上显示的系统菜单光标向上、向下、向左、向右移动，或者执行确认、返回操作。

该动作面向的是Yamaha 网络功放（Network Receiver）集成，相关集成文档位于 source/_integrations/yamaha.markdown。该集成属于媒体播放器（media player）平台，支持 HTR-4065、RX-V473、RX-V573、RX-V673、RX-V773、RX-V3067 等众多型号。这一动作最初于 Home Assistant 2021.7 版本中随yamaha组件新增（见 2021.7 发布说明中 "Add a menu_cursor service to the yamaha component" 一条）。

在实际场景中，这个动作特别适合用于模拟遥控器按键：例如在自动化中先使用yamaha.select_scene切换到"看电影"场景，再用yamaha.menu_cursor在功放菜单中逐级下移并确认某个选项，无需用户手动触碰遥控器。

前置条件：先配置好 yamaha 集成

要使用yamaha.menu_cursor，首先需要将 Yamaha 功放接入 Home Assistant。根据 yamaha 集成文档，在configuration.yaml中最小配置如下：

# Example configuration.yaml entry media_player: - platform: yamaha

配置完成后需重启 Home Assistant 使配置生效。注意：必须在功放上开启网络待机（network standby），否则功放处于关机状态时会导致 Home Assistant 启动挂起。

如需更精确的控制，可结合集成支持的可选参数（详见 yamaha 集成文档的配置表格）：

# Example configuration.yaml entry media_player: - platform: yamaha host: 192.168.0.10 source_ignore: - "AUX" - "HDMI6" source_names: HDMI1: "ChromeCast" AV4: "Vinyl" zone_ignore: - "Zone_2" zone_names: Main_Zone: "Family Room"

host：功放的 IP 地址或主机名；
source_ignore：在界面上隐藏的音源列表；
source_names：将内部音源名（如HDMI1）重命名为自定义名称（如ChromeCast）；
zone_ignore：在界面上隐藏的区（zone）列表；
zone_names：将区名称（如Main_Zone）重命名为自定义名称（如Family Room）。

配置完成后，功放会以media_player实体形式出现在 Home Assistant 中（例如media_player.living_room_stereo），这就是yamaha.menu_cursor的动作目标。

在 UI 中创建自动化或脚本

如果偏好可视化编辑，可以通过 UI 分步创建使用该动作的自动化或脚本，无需编写 YAML（对应仓库中的 actions/ui_header.md 模板内容）。操作步骤如下：

进入设置>自动化与场景（Automations & scenes）。
打开一个已有的自动化或脚本，或选择创建自动化>创建新自动化。
若为新建自动化，在当（When）部分添加一个触发条件；脚本不需要触发器，脚本由其他方式调用时运行。
在然后执行（Then do）部分，选择添加动作（Add action）。
选择要控制的设备：在按目标（By target）下选择要控制的功放（目标机制的说明见下文"动作目标"一节）。
在该目标展示的动作列表中，选择Yamaha: Menu cursor。
设置要按下的Cursor键。
选择保存。

UI 中的选项

选项	说明	必填
Cursor	要按下的光标键：`up`、`down`、`left`、`right`、`select`或`return`	是

在 YAML 中调用

如果需要直接编写 YAML（自动化、脚本或通过开发者工具测试），或想了解 Home Assistant 底层的精确字段行为，可参考 actions/yaml_header.md 中描述的技术参考方式：动作名称为yamaha.menu_cursor，字段名、类型与必填性如下表。

一个基本示例（来自 yamaha.menu_cursor 动作文档）：

action: yamaha.menu_cursor target: entity_id: media_player.living_room_stereo data: cursor: down

该示例会在media_player.living_room_stereo（即某台 Yamaha 功放）上按下"向下"光标键。

YAML 中的选项

字段	说明	必填	类型
`cursor`	要按下的光标键：`up`、`down`、`left`、`right`、`select`或`return`	是	string

cursor取值含义：

up/down/left/right：在屏幕菜单中按对应方向移动光标；
select：确认当前高亮的菜单项（相当于按遥控器上的确定键）；
return：返回上一层菜单（相当于按返回键）。

在自动化/脚本中的完整用法

将该动作与yamaha集成的其他能力组合，可实现完整的功放操作序列。例如，参考 yamaha 集成文档中的play_media脚本示例，我们可以构建一个包含"开机、调音量、光标导航确认"的脚本：

script: movie_night: alias: "Movie night on living room stereo" sequence: - action: media_player.turn_on target: entity_id: media_player.living_room_stereo - action: media_player.volume_set target: entity_id: media_player.living_room_stereo data: volume_level: 0.35 - action: yamaha.select_scene target: entity_id: media_player.living_room_stereo data: scene: "TV Viewing" - action: yamaha.menu_cursor target: entity_id: media_player.living_room_stereo data: cursor: select

上述示例展示了该动作在脚本序列中的典型定位：作为整个流程中的一步，向功放发送一次"按键"。

动作目标（Target）

该动作必须指定目标，目标即动作的作用对象。根据 actions/targets.md 模板，你可以把动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对目标下每一个匹配的media_player实体执行该动作：

实体（Entity）：某一个具体的media_player实体，例如media_player.living_room_stereo；
设备（Device）：属于某台设备的所有media_player实体；
区域（Area）：某个房间/区域内的所有media_player实体；
楼层（Floor）：某个楼层上的所有media_player实体；
标签（Label）：共享某个标签的所有media_player实体。

同一个动作中还可以混用不同类型的多个目标，例如同时指定一个具体实体和一个区域，动作会依次作用到两者之上。

由于 Yamaha 功放可能暴露多个区域（zone）实体（如主区与 Zone 2），通过实体级目标可以精确控制某个区；而通过设备级目标则会对该功放的所有媒体播放器实体一次性发送光标指令，请根据实际需求选择。

动作调试与常见问题

尝试运行：在 UI 中创建动作后，可参考 actions/try_it.md 的方式直接执行该动作验证效果——观察功放屏幕菜单是否发生了预期的光标移动或菜单确认/返回行为。
卡住时排查：如果动作没有生效，可参考 actions/stuck.md 的排查思路，重点检查以下几点：
1. 功放是否已成功接入 Home Assistant（实体是否可见、状态是否正常）；
2. 功放是否开启了网络待机，功放处于完全关机状态时无法接收指令；
3. 目标实体是否正确（确认entity_id与功放的 zone 命名对应）；
4. cursor参数是否在up、down、left、right、select、return六个合法值之内；
5. 屏幕菜单当前是否处于可交互状态（例如功放当前显示的是视频源而非 OSD 菜单时，光标键可能无效）。
若此前已经通过 YAML 添加过集成配置，请在修改configuration.yaml后重启 Home Assistant，参见 yamaha 集成文档。

企业官网建设流程全解析