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

## ColourTransformer

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

> 💡 适用于灯类产品的彩光控制 DP（如 colour_data），将前端 HSV 色值（hue/saturation/value）
> 与 12 位十六进制 DP 字符串互转。每个分量占 4 位十六进制（2 字节）。

### 描述

彩光标准 DP 协议转换器，用于 HSV 色值与设备 DP 十六进制协议的双向转换

### 参数

`Params`

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

### 返回值

类型: `ColourTransformer`

ColourTransformer 实例

#### 方法

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

### 引用对象

##### `type` TColorData

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


### 示例代码

#### 示例

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

const transformer = new ColourTransformer();
// 解析 DP 字符串为 HSV 对象
const hsv = transformer.parser('000003e803e8');
// => { hue: 0, saturation: 1000, value: 1000 }

// 将 HSV 对象格式化为 DP 字符串
const dpStr = transformer.formatter({ hue: 120, saturation: 800, value: 900 });
// => '007803200384'
```