智能家居 ColorSetting 特征架构

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

RGB、HSV 和色温

RGB 将颜色表示为（红、绿、蓝）三元组。RGB 是默认颜色模型。任何 RGB 三元组都可以表示为十六进制代码，相当于将三元组的十六进制值串联起来。例如，“蓝色”是 (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 布尔值

（默认值：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 整数

必填。

以十进制整数表示的 Spectrum RGB 值。
2 对象

支持颜色 HSV 频谱。
spectrumHsv 对象

必填。

频谱 HSV 值。
hue 编号

色调。

最小值：0。
saturation 编号

饱和度。

值必须介于 0 到 1 之间。
value 编号

值”。

值必须介于 0 到 1 之间。

示例

灯光颜色是什么？（暖白色）

{
  "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 整数

必填。

以十进制整数表示的 Spectrum RGB 值。如需了解详情，请参阅 RGB、HSV 和色温。
2 对象

支持颜色 HSV 频谱。
spectrumHSV 对象

必填。

频谱 HSV 值。如需了解详情，请参阅 RGB、HSV 和色温。
hue 编号

色调。

最小值：0。
saturation 编号

饱和度。

值必须介于 0 到 1 之间。
value 编号

值”。

值必须介于 0 到 1 之间。

示例

把灯光调成暖白色。

{
  "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

设备错误

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