智慧型住宅 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 意圖，請參閱「意圖執行要求」。

屬性 類型 說明
commandOnlyColorSetting 布林值

(預設值：false)

指出裝置是否支援單向 (true) 或雙向 (false) 通訊。如果裝置無法回應此特徵的 QUERY 意圖或回報狀態，請將這個屬性設為 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 意圖，請參閱「意圖執行要求」。

州 類型 說明
color 物件

必要。

裝置目前使用的色彩設定。
包含下列其中一個項目：
0 物件

支援色溫。
temperatureK 整數

必填。

溫度值 (以克耳文為單位)。
1 物件

顏色 RGB 頻譜支援。
spectrumRgb 整數

必填。

以小數整數表示的光譜 RGB 值。
2 物件

支援 HSV 色彩光譜。
spectrumHsv 物件

必填。

Spectrum 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 String

從使用者指令解析的顏色名稱，可能無法隨時使用 (例如使用相對指令時)。
包含下列其中一個項目：
0 物件

支援色溫。
temperature 整數

必填。

溫度值以克耳文為單位。詳情請參閱「RGB、HSV 和色溫」。
1 物件

顏色 RGB 頻譜支援。
spectrumRGB 整數

必填。

Spectrum 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

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