智慧型住宅色彩設定特性結構定義

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，反之亦然。Hue 的範圍為 [0, 360) 度 (不含 360，因為其包圍在 0 度左右)。飽和度和值以 [0.0, 1.0] 範圍內的浮點值表示。

色溫代表「部分」顏色，表示在克氏是非負小數。此屬性描述了「白色」或「暖燈」的光源，並加上顏色名稱，例如「冷白色」或「陰天白燈」。支援色溫的智慧型燈具通常有 [2000, 9000] 克氏的量化範圍，這與傳統的固定度。色溫是線性比例，也是 RGB/HSV 全光譜色彩模型的子集。請參考下表提供的溫度範例和對應的色彩名稱。

溫度 (克氏)	顏色名稱
2000	燭光
2500	超暖白
3000	柔白、晨白色、閱讀白
4000	冷白色
5000	日光，白色
6000	花白
7000	雲霧白，煙霧
8000	藍色陰天
9000	藍天藍

裝置屬性

具有此特性的裝置可能會在 SYNC 作業中回報下列屬性。如要進一步瞭解如何處理 SYNC 意圖，請參閱意圖執行要求一文。

屬性	類型	說明
commandOnlyColorSetting	布林	(預設：false) 指出裝置是否支援單向 (true) 或雙向 (false) 通訊。如果裝置無法回應此特徵的 QUERY 意圖或報告狀態，請將此屬性設為 true。
包含下列任何項目：
0	物件	支援顏色模型。
colorModel	字串	必填。 裝置支援的完整頻譜色彩模型。 支援的值： 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
}

裝置狀態：STATE

具有此特性的裝置可能會在 QUERY 作業中回報下列狀態。如要進一步瞭解如何處理 QUERY 意圖，請參閱意圖執行要求一文。

州	類型	說明
color	物件	必填。 裝置目前使用的顏色設定。
內含下列其中一個項目：
0	物件	支援色溫。
temperatureK	整數	必填。 溫度 (以克耳文表示)。
1	物件	支援 RGB 頻譜。
spectrumRgb	整數	必填。 以 十進位整數表示頻譜 RGB 值。
2	物件	支援 HSV 頻譜。
spectrumHsv	物件	必填。 頻譜 HSV 值。
hue	Number	色調。
saturation	Number	飽和度。
value	Number	值。

範例

燈光顏色是什麼？(暖白色)

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

燈光顏色是什麼？(洋紅色)

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

燈光顏色是什麼？(洋紅色)

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

裝置指令

具有此特性的裝置可能會在 EXECUTE 作業中回應下列指令。如要進一步瞭解如何處理 EXECUTE 意圖，請參閱意圖執行要求一文。

action.devices.commands.ColorAbsolute

設定絕對色彩值。

參數

參數	類型	說明
color	物件	必填。 設定顏色。
name	字串	從使用者指令剖析的顏色名稱；有時可能無法使用 (即使用相對指令)。
內含下列其中一個項目：
0	物件	支援色溫。
temperature	整數	必填。 溫度 (以克耳文表示)。詳情請參閱 RGB、HSV 和色溫。
1	物件	支援 RGB 頻譜。
spectrumRGB	整數	必填。 以 十進位整數表示頻譜 RGB 值。詳情請參閱 RGB、HSV 和色溫。
2	物件	支援 HSV 頻譜。
spectrumHSV	物件	必填。 頻譜 HSV 值。詳情請參閱 RGB、HSV 和色溫。
hue	Number	色調。
saturation	Number	飽和度。
value	Number	值。

範例

將燈光設為溫暖的白光。

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

裝置錯誤：ERRORS

請參閱錯誤和例外狀況的完整清單。