智能家居 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] 的范围内（包括 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

设备出错

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