---
title: matter-kit 概述
summary: matter-kit 是 @ray-js/panel-sdk（1.15.0+）提供的 SDM 拦截器工具库，面向照明品类，通过 createMatterKit 实现 Matter 与标准 DP 双向转换，可与 dp-kit 组合使用。
questions:
  - matter-kit 从哪个 SDK 版本开始提供，当前支持哪类设备？
  - Matter 与标准 DP 的四组核心映射分别是什么？
  - 与 dp-kit 组合时 publishDps 拦截器应如何排序？
  - 色温精度丢失时应用哪个 Hook 读取原始值？
---

# matter-kit

<Alert type="info">
matter-kit 自 @ray-js/panel-sdk@1.15.0 开始加入，当前仅支持**照明品类**设备。
</Alert>

轻量的 Matter 设备面板 DP 功能点处理工具库，内置 Matter 协议与标准 DP 协议之间的双向转换，自动处理设备信息、DP 状态上报与下发。

各 API 的详细说明见下文 [API 索引](#api-索引) 中的子文档链接。

## 接入指南

### 根据业务场景生成 matter-kit

> src/devices/index.ts

```ts | pure
import { SmartDeviceModel, createMatterKit } from '@ray-js/panel-sdk';
import { defaultSchema } from '@/devices/schema';

type SmartDeviceSchema = typeof defaultSchema;

export const matterKit = createMatterKit({
  debug: false, // 可选：开启调试模式
});

const options = {
  interceptors: matterKit.interceptors,
};

export const devices = {
  common: new SmartDeviceModel<SmartDeviceSchema>(options),
};
```

## 使用标准 DP 功能点

接入 matter-kit 后，您可以直接使用标准的 DP 功能点进行开发，matter-kit 会自动处理 Matter 协议与标准协议之间的转换。

```tsx | pure
import React from 'react';
import { View } from '@ray-js/ray';
import { useProps, useActions } from '@ray-js/panel-sdk';

export default function Home() {
  const power = useProps((props) => props.switch_led);
  const bright = useProps((props) => props.bright_value);
  const temp = useProps((props) => props.temp_value);
  const colour = useProps((props) => props.colour_data);
  const actions = useActions();

  return (
    <View style={{ flex: 1 }}>
      <View onClick={() => actions.switch_led.toggle()}>
        开关: {power ? '开' : '关'}
      </View>
      <View onClick={() => actions.bright_value.set(500)}>
        亮度: {bright}
      </View>
      <View onClick={() => actions.temp_value.set(600)}>
        色温: {temp}
      </View>
      <View onClick={() => actions.colour_data.set('012502ad02ee')}>
        颜色: {colour}
      </View>
    </View>
  );
}
```

## DP 功能点映射关系

matter-kit 会自动处理以下 Matter 协议与标准协议之间的转换：

| Matter 协议          | 标准协议       | 说明                          |
| -------------------- | -------------- | ----------------------------- |
| `switch`             | `switch_led`   | 开关控制                      |
| `brightness_control` | `bright_value` | 亮度控制（1-254 → 10-1000）   |
| `color_temp_control` | `temp_value`   | 色温控制（卡尔文 → 0-1000）   |
| `hs_color_set`       | `colour_data`  | 颜色控制（色相+饱和度 → HSV） |

### 转换说明

#### 开关控制

- **上报**：`switch` → `switch_led`
- **下发**：`switch_led` → `switch`

#### 亮度控制

- **上报**：`brightness_control` (1-254) → `bright_value` (10-1000)
- **下发**：`bright_value` (10-1000) → `brightness_control` (1-254)

转换公式使用线性映射，确保数值范围的正确转换。

#### 色温控制

- **上报**：`color_temp_control` (卡尔文) → `temp_value` (0-1000)
- **下发**：`temp_value` (0-1000) → `color_temp_control` (卡尔文)

转换基于色温的卡尔文值进行非线性映射，确保色温滑动条的显示效果。

> **注意**：由于色温转换会丢失精度，matter-kit 会保留原始的 `color_temp_control` 值。如需获取原始值用于 UI 展示，请使用 [useOriginMatterTemp](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/useOriginMatterTemp)。

#### 颜色控制

- **上报**：`hs_color_set` (色相+饱和度) + `brightness_control` (亮度) → `colour_data` (HSV 格式)
- **下发**：`colour_data` (HSV 格式) → `hs_color_set` (色相+饱和度) + `brightness_control` (亮度)

颜色转换会将 Matter 的色相饱和度与亮度合并为标准协议的 HSV 格式。

## 使用示例

### 基础

```tsx | pure
import React from 'react';
import { View } from '@ray-js/ray';
import { useProps, useActions, createMatterKit } from '@ray-js/panel-sdk';

const matterKit = createMatterKit();

export default function Home() {
  const power = useProps((props) => props.switch_led);
  const bright = useProps((props) => props.bright_value);
  const actions = useActions();

  return (
    <View>
      <View onClick={() => actions.switch_led.toggle()}>
        开关: {power ? '开' : '关'}
      </View>
      <View onClick={() => actions.bright_value.set(500)}>
        亮度: {bright}
      </View>
    </View>
  );
}
```

### 路数

结合 schema 判断路数、白光能力等，完整说明见 [getMatterRoad](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/getMatterRoad)。

```tsx | pure
import React from 'react';
import { View } from '@ray-js/ray';
import { useDpSchema, createMatterKit } from '@ray-js/panel-sdk';

const matterKit = createMatterKit();

export default function DeviceInfo() {
  const dpSchema = useDpSchema();
  const road = matterKit.utils.getMatterRoad(dpSchema);
  const hasWhite = matterKit.utils.checkIsMatterHasWhite(dpSchema);

  return (
    <View>
      <View>设备路数: {road} 路</View>
      <View>是否有白光: {hasWhite ? '是' : '否'}</View>
    </View>
  );
}
```

### 颜色（useColourData）

Matter 面板下颜色的 `value` 会由 matter-kit 对齐为 `bright_value`。推荐直接使用 SDK 的 **useColourData**，详见 [resolveColorData](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/resolveColorData)。

```tsx | pure
import React from 'react';
import { View } from '@ray-js/ray';
import { useColourData, useActions } from '@ray-js/panel-sdk';

export default function ColorControl() {
  const colorData = useColourData(); // { hue, saturation, value }，Matter 下 value 来自 bright_value
  const actions = useActions();

  return (
    <View>
      <View>色相: {colorData?.hue}</View>
      <View>饱和度: {colorData?.saturation}</View>
      <View>亮度: {colorData?.value}</View>
    </View>
  );
}
```

更多示例（手动 `resolveColorData`、`shouldConvert` / `debug` 等）见 [resolveColorData](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/resolveColorData)、[useOriginMatterTemp](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/useOriginMatterTemp)、[createMatterKit](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/createMatterKit)。

## 与 dp-kit 配合使用

matter-kit 可以与 dp-kit 配合使用，实现更强大的功能：

```ts | pure
import { SmartDeviceModel, createMatterKit, createDpKit } from '@ray-js/panel-sdk';
import { defaultSchema } from '@/devices/schema';
import ColourTransformer from '@ray-js/panel-sdk/lib/protocols/lamp/ColourTransformer';

type SmartDeviceSchema = typeof defaultSchema;

const matterKit = createMatterKit();
const dpKit = createDpKit<SmartDeviceSchema>({
  protocols: {
    colour_data: new ColourTransformer(),
  },
  sendDpOption: {
    immediate: true, // 立即更新状态
  },
});

const options = {
  interceptors: {
    init: {
      ...matterKit.interceptors.init,
      ...dpKit.interceptors.init,
    },
    request: {
      publishDps: [
        ...dpKit.interceptors.request.publishDps,
        ...matterKit.interceptors.request.publishDps,
      ],
    },
    response: dpKit.interceptors.response,
  },
};

export const devices = {
  common: new SmartDeviceModel<SmartDeviceSchema>(options),
};
```

> **注意**：拦截器的顺序很重要。在配合使用时，建议将 dp-kit 的 `publishDps` 拦截器放在 matter-kit 之前，这样 dp-kit 会先处理标准协议的数据，然后 matter-kit 再将其转换为 Matter 协议。

## 注意事项

1. **转换精度**：色温转换会丢失精度，如需获取原始值，请使用 [useOriginMatterTemp](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/useOriginMatterTemp)。

2. **拦截器顺序**：与 dp-kit 配合使用时，注意拦截器的顺序，建议 dp-kit 在前，matter-kit 在后。

3. **Schema 转换**：matter-kit 会自动在 schema 中新增标准 DP 功能点（如 `switch_led`、`bright_value` 等），同时保留原始的 Matter DP 功能点（如 `switch`、`brightness_control` 等），用于路数判断等功能。

4. **颜色数据**：Matter 协议的颜色数据由 `hs_color_set`（色相+饱和度）和 `brightness_control`（亮度）组成，matter-kit 会自动将其合并为标准协议的 `colour_data`（HSV 格式）。

5. **调试模式**：在生产环境中建议关闭调试模式，避免控制台输出过多日志。参见 [createMatterKit](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/createMatterKit)。

## API 索引

| 文档 | 说明 |
| ---- | ---- |
| [createMatterKit](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/createMatterKit) | 工厂函数、`CreateMatterKitOptions`（`shouldConvert`、`debug`、`config`） |
| [resolveMatterDevInfo](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/resolveMatterDevInfo) | Matter 设备信息 → 标准 schema |
| [mapMatterDpState](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/mapMatterDpState) | 上报/合并：Matter DP 状态 → 标准 DP |
| [mapPublishMatterDps](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/mapPublishMatterDps) | 下发：标准 DP → Matter DP |
| [resolveColorData](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/resolveColorData) | 颜色解析；推荐 `useColourData`，可选手动 `resolveColorData` |
| [useOriginMatterTemp](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/useOriginMatterTemp) | 读取原始 `color_temp_control`，避免精度损失 |
| [checkIsMatterDevice](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/checkIsMatterDevice) | 判断是否为 Matter 面板 |
| [checkIsMatterHasWhite](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/checkIsMatterHasWhite) | 判断是否具备白光能力 |
| [getMatterRoad](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/getMatterRoad) | 路数推断（1～5 或 0 未知） |
| [temp2Number](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/temp2Number) / [number2Temp](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/number2Temp) | 色温卡尔文 ↔ `temp_value` 数值 |
| [bright2Number](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/bright2Number) / [number2Bright](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/number2Bright) | Matter 亮度 ↔ 标准 `bright_value` |
| [getTempRgb](/cn/miniapp/solution-panel/ability/common/sdm/interceptors/matterkit/getTempRgb) | 色温（卡尔文）→ RGB 十六进制字符串（UI 色条等） |