智能家居 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
      }
    }
  }
}

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

命令	状态
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 på 2000 Kelvin
• tänd blått ljus i köket

设备错误

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