---
name: "HSColourSetTransformer"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "HSColourSetTransformer"
summary: "HSColourSetTransformer 用于解析照明 hs_color_set DP，实现 HS 颜色的解析与格式化。"
questions:
  - "HSColourSetTransformer 的作用是什么？"
  - "HSColourSetTransformer 如何解析 HS 颜色？"
  - "HSColourSetTransformer 的输入和输出是什么？"
  - "HSColourSetTransformer 的转换规则是什么？"
---

## HSColourSetTransformer

> [VERSION] @ray-js/panel-sdk >= 1.0.0

> 💡 适用于 Zigbee 灯类产品的 HS 颜色设置 DP（如 hs_color_set），将前端 hue(0-360)/saturation(0-1000)
> 与设备协议的 2 字节（0-254 范围）十六进制格式互转。
> 注意：此转换器会对 hue 和 saturation 做范围映射（hue: 0-360 <-> 0-254，saturation: 0-1000 <-> 0-254）。

### 描述

HS 颜色设置协议转换器，用于 HS 色值与 Zigbee DP 协议格式的双向转换

### 参数

`Params`

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `uuid` | `string` | 否 | DP 标识符，默认为 'hs_color_set' |
| `defaultValue` | `TColorData` | 否 | 默认 HS 值，当解析失败时返回此值 |

### 返回值

类型: `HSColourSetTransformer`

HSColourSetTransformer 实例

#### 方法

| 方法名 | 说明 |
| --- | --- |
| `parser` | 将 DP 十六进制字符串解析为 HS 色值对象 |
| `formatter` | 将 HS 色值对象格式化为 DP 十六进制字符串 |

### 引用对象

##### `type` TColorData

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `hue` | `number` | 色相 |
| `saturation` | `number` | 饱和度 |
| `value` | `number` | 亮度 |


### 示例代码

#### 示例

```ts
import { HSColourTransformer } from '@ray-js/panel-sdk';

const transformer = new HSColourTransformer();
// 解析 DP 字符串为 HS 对象
const hs = transformer.parser('fefe');
// => { hue: 360, saturation: 1000 }

// 将 HS 对象格式化为 DP 字符串
const dpStr = transformer.formatter({ hue: 180, saturation: 500 });
```