如何在Google Home应用中为Smart Home Action显示音量控件

算力阿峰

2026-8-28

问题描述

开发Smart Home Action过程中，已成功将soundbar类设备关联至Google Home应用，语音控制设备音量功能正常，但应用内无法看到Google Home自有设备、电视等其他扬声器类设备配备的音量控制控件。
使用测试账号关联设备后，在Google Home应用中点击对应设备，仅能看到设备设置选项，无任何控制控件。

当前设备返回的SYNC响应如下：

{
  "requestId": "7848726039212384681",
  "payload": {
    "agentUserId": "robin@mccorkell.me.uk",
    "errorCode": null,
    "debugString": null,
    "devices": [
      {
        "id": "ampcontrol@mccorkell.me.uk",
        "type": "action.devices.types.SOUNDBAR",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.MediaState",
          "action.devices.traits.Volume",
          "action.devices.traits.TransportControl"
        ],
        "name": {
          "defaultNames": null,
          "name": "Amplifier",
          "nicknames": null
        },
        "willReportState": false,
        "notificationSupportedByAgent": false,
        "roomHint": null,
        "deviceInfo": null,
        "attributes": {
          "transportControlSupportedCommands": [],
          "volumeMaxLevel": 100,
          "volumeCanMuteAndUnmute": false,
          "levelStepSize": 10,
          "queryOnlyOnOff": true
        },
        "customData": null,
        "otherDeviceIds": null
      }
    ]
  }
}

当前设备返回的QUERY响应如下：

{
  "requestId": "15675955780684435642",
  "payload": {
    "errorCode": null,
    "debugString": null,
    "devices": {
      "ampcontrol@mccorkell.me.uk": {
        "online": true,
        "status": "SUCCESS",
        "errorCode": null,
        "on": true,
        "currentVolume": 96
      }
    }
  }
}

解决方案

按以下步骤调整配置即可正常显示音量控制控件：

修复SYNC报文语法问题
原始返回的SYNC报文里，traits数组最后一项action.devices.traits.TransportControl缺少闭合双引号，会导致Google侧无法正常解析设备能力，先修正这个JSON语法错误。
清理无效/错误的trait和属性配置
- 如果没有实现播放/暂停/切歌等传输控制能力，直接把MediaState、TransportControl两个trait从traits列表删除，不要返回transportControlSupportedCommands为空数组的无效trait，空配置的trait会干扰前端对设备可交互能力的判定。如果确实要支持传输控制，就给transportControlSupportedCommands补充实际支持的命令枚举值，不要留空。
- 删除queryOnlyOnOff: true配置项：这个配置代表设备开关仅支持查询、不支持远程控制，属于只读能力。如果设备确实不支持远程开关，直接把OnOff trait从列表移除即可；如果支持开关控制，就正常实现EXECUTE处理逻辑，不要标记为只读。大量只读trait会让前端判定设备没有可交互控件，直接隐藏所有操作入口。
- 如果设备支持静音功能，把volumeCanMuteAndUnmute设为true，同时在QUERY响应中补充isMuted状态字段，在EXECUTE逻辑中增加静音/取消静音的指令处理；不支持静音也不会影响音量滑块显示，可保留为false。
校验状态返回逻辑
- 不管willReportState配置为true还是false，QUERY接口必须稳定返回所有已声明trait对应的状态字段，不能缺漏。当前返回的on、currentVolume字段符合Volume、OnOff trait的要求，保持逻辑稳定即可。
- 每次EXECUTE指令执行完成后，后续QUERY请求必须返回最新的设备状态，前端控件的初始渲染完全依赖QUERY拉取到的状态值。
配置生效操作
所有配置修改完成后，触发一次全量设备同步，或者直接解绑测试账号后重新关联设备，同时清掉Google Home应用的本地缓存再重新打开，旧的设备配置缓存最长可能留存15分钟，不手动同步/重连的话新配置不会立即生效。

内容的提问来源于stack exchange，提问作者Robin McCorkell