智慧型住宅 ColorSetting 特徵架構

action.devices.traits.ColorSetting - 這項特徵適用於可變更顏色或色溫的裝置，例如智慧型燈具。

RGB、HSV 和色溫

RGB 會以 (紅、綠、藍) 三元組表示顏色。RGB 是預設的色彩模式。任何 RGB 三元組都可以表示為十六進位代碼，相當於三元組的串連十六進位值。舉例來說，「藍色」是 (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 整數

必要。

以十進位整數表示的 Spectrum RGB 值。
2 物件

支援 HSV 色彩光譜。
spectrumHsv 物件

必要。

Spectrum HSV 值。
hue Number

色調。

最小值：0。
saturation Number

飽和度。

值必須介於 0 至 1 之間
value Number

價值」。

值必須介於 0 至 1 之間

範例

燈光顏色為何？(暖白色)

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

必要。

光譜 RGB 值，以十進位整數表示。詳情請參閱「RGB、HSV 和色溫」。
2 物件

支援 HSV 色彩光譜。
spectrumHSV 物件

必要。

Spectrum HSV 值。詳情請參閱「RGB、HSV 和色溫」。
hue Number

色調。

最小值：0。
saturation Number

飽和度。

值必須介於 0 至 1 之間
value Number

價值」。

值必須介於 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

裝置錯誤

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