欢迎使用 Google Home 开发者中心,这是一个学习如何开发智能家居 Action 的新平台。注意:构建 Action 的工作仍需在 Actions 控制台中完成。

智能家居 ColorSetting 特征架构

action.devices.traits.ColorSetting - 此特征适用于可更改颜色或色温的设备(例如智能灯)。

RGB、HSV 和色温

RGB 表示(红色、绿色、蓝色)三元组的颜色。RGB 是默认颜色模型。任何 RGB 三元组均可表示为十六进制代码,相当于串联的三元组的十六进制值。例如,“blue”为 (0, 0, 255) 和 #0000FF。 您可以使用 RGB 颜色空间中的任意值,即 RGB(x, y, z),其中 x、y、z 在 [0, 255](含)范围内。

HSV 以(色相、饱和度、值)三元组表示颜色。HSV 中的任何颜色值都可以转换为 RGB,反之亦然。色相范围为 [0, 360) 度(不含 360 度,因为它环绕着 0 度)。饱和度和值由 [0.0, 1.0] 范围内的浮点数表示。

色温表示某些颜色(以开尔文的非负十进制值表示)。此属性描述“白色”或“温暖”光源,其颜色名称为“冷白色”或“阴天”。支持色温的智能灯通常范围为 [2000, 9000] 开尔文,与采用固定开尔文的传统灯相对应。色温是线性比例和 RGB/HSV 全光谱颜色模型的子集。如需了解一些示例温度和相应的颜色名称,请参见下表。

温度(开尔文) 颜色名称
2000蜡烛灯
2500超白色
3000柔白色、上午白色、阅读白色
4000冷白色
5000日光,白色
6000花白色
7000多云日光,白烟
8000蓝色阴
9000蓝天

设备属性

具有此特征的设备可以在 SYNC 操作中报告以下属性。如需详细了解如何处理 SYNC intent,请参阅 intent 执行方式

属性 类型 说明
commandOnlyColorSetting Boolean

(默认:false

指示设备是否支持单向 (true) 或双向 (false) 通信。如果设备无法响应此特征的 QUERY intent 或报告状态,请将此属性设为 true。

包含以下任意内容
0 对象

颜色模型支持。

colorModel String

必填。

设备支持的完整光谱颜色模型。

支持的值:

rgb
hsv
1 对象

支持色温。

colorTemperatureRange 对象

必填。

开尔文支持的色温范围。

temperatureMinK 整数

必填。

支持开尔文的最低色温。

temperatureMaxK 整数

必填。

支持的最大色温(开尔文)。

示例

同时支持 RGB 频谱颜色模型和色温的设备

{
  "colorModel": "rgb",
  "colorTemperatureRange": {
    "temperatureMinK": 2000,
    "temperatureMaxK": 9000
  }
}

仅支持 HSV 频谱颜色模型的设备

{
  "colorModel": "hsv"
}

仅支持色温的设备

{
  "colorTemperatureRange": {
    "temperatureMinK": 2000,
    "temperatureMaxK": 9000
  }
}

仅支持 HSV 颜色模型命令的设备

{
  "colorModel": "hsv",
  "commandOnlyColorSetting": true
}

设备状态

具有此特征的实体可以在 QUERY 操作中报告以下状态。如需详细了解如何处理 QUERY intent,请参阅 intent 执行方式

类型 说明
color 对象

必填。

设备上当前使用的颜色设置。

包含下列某一项
0 对象

支持色温。

temperatureK 整数

必填。

开尔文的温度值。

1 对象

支持颜色 RGB 光谱。

spectrumRgb 整数

必填。

以十进制整数表示的频谱 RGB 值。

2 对象

支持颜色 HSV 频谱。

spectrumHsv 对象

必填。

频谱 HSV 值。

hue 编号

色调

saturation 编号

饱和度。

value 编号

值。

示例

灯的颜色是什么?(暖白色)

{
  "color": {
    "temperatureK": 3000
  }
}

灯的颜色是什么?(洋红色)

{
  "color": {
    "spectrumRgb": 16711935
  }
}

灯的颜色是什么?(洋红色)

{
  "color": {
    "spectrumHsv": {
      "hue": 300,
      "saturation": 1,
      "value": 1
    }
  }
}

设备命令

具有此特征的设备可能会在 EXECUTE 操作中响应以下命令。如需详细了解如何处理 EXECUTE intent,请参阅 intent 执行方式

action.devices.commands.ColorAbsolute

设置绝对颜色值。

参数

参数 类型 说明
color 对象

必填。

要设置的颜色。

name String

通过用户的命令解析的颜色名称;有时可能无法使用(即使用相对命令时)。

包含下列某一项
0 对象

支持色温。

temperature 整数

必填。

开尔文的温度值。如需了解详情,请参阅 RGB、HSV 和色温

1 对象

支持颜色 RGB 光谱。

spectrumRGB 整数

必填。

以十进制整数表示的频谱 RGB 值。如需了解详情,请参阅 RGB、HSV 和色温

2 对象

支持颜色 HSV 频谱。

spectrumHSV 对象

必填。

频谱 HSV 值。如需了解详情,请参阅 RGB、HSV 和色温

hue 编号

色调

saturation 编号

饱和度。

value 编号

值。

示例

将灯光调成白色。

{
  "command": "action.devices.commands.ColorAbsolute",
  "params": {
    "color": {
      "name": "Warm White",
      "temperature": 3000
    }
  }
}

将洋红色调为品红色。

{
  "command": "action.devices.commands.ColorAbsolute",
  "params": {
    "color": {
      "name": "Magenta",
      "spectrumRGB": 16711935
    }
  }
}

将洋红色调为品红色。

{
  "command": "action.devices.commands.ColorAbsolute",
  "params": {
    "color": {
      "name": "Magenta",
      "spectrumHSV": {
        "hue": 300,
        "saturation": 1,
        "value": 1
      }
    }
  }
}

请注意,命令和状态参数的参数名称略有不同。这样可以避免与已废弃的 ColorSpectrumColorTemperature 特征的状态参数发生冲突。

命令 状态
temperature temperatureK
spectrumRGB spectrumRgb
spectrumHSV spectrumHsv

示例话语

de-DE

  • Stell die Farbe der Lampe auf blau
  • Stelle die Farbtemperatur auf 3000 Kelvin ein.

en-US

  • can you adjust my lights color to 4000 kelvins
  • set the lights to blue

es-ES

  • pon azul la luz de la cocina
  • pon la luz a 2000 k de temperatura de color

fr-FR

  • Allume la lampe de la chambre à 3500 kelvins .
  • mets les lampes en rose dans la chambre

hi-IN

  • तुम लाइट को ब्लू कर दो
  • लैम्प 2000 केल्विन पर लगाओ।

it-IT

  • Imposta la lampada a 2000 K .
  • metti la luce gialla

ja-JP

  • 照明 の色を にして
  • 照明 の色温度を 5000K にセットして

ko-KR

  • 조명 색깔 흰색 으로 바꿔 줘
  • 주방 전등 색 온도를 5000 켈빈 으로 설정해

nl-NL

  • Zet de keukenlamp op 2000 Kelvin .
  • maak het licht rood

pt-BR

  • Colocar a lâmpada em 2000 K .
  • Define a lâmpada para 2000 K .
  • colocar a luz da sala em azul
  • põe a luz da sala a vermelho

sv-SE

  • Ställ in lampan 2000 Kelvin
  • tänd blått ljus i köket

设备错误

查看错误和异常的完整列表。