---
name: "createDpKit"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.7.0" }
title: "createDpKit - 创建 dp-kit 实例"
summary: "createDpKit 是 @ray-js/panel-sdk 提供的函数，用于创建 dp-kit 实例，通过 createDpKit 创建。核心能力包括：通过 protocols 自定义 parser/formatter，自动解析/反解析复杂类型 DP（如 colour_data→hue/saturation/value）；sendDpOption 支持 throttle 节流、debounce 防抖、delay 延迟、checkRepeat 重复过滤、ordered 顺序下发；immediate 即时更新（下发后立即刷新 UI 无需等待上报）；ignoreDpDataResponse 忽略设备上报响应（支持 whiteDpCodes 白名单、timeout 防抖超时、customRule 自定义规则）；synchronizeDevProperty 云端 DP 状态同步（支持 blackDpCodes 黑名单、defaultState 默认值）；onBeforeSendDp/onAfterSendDp 下发前后钩子。搭配 useStructuredProps/useStructuredActions 使用。typings/sdm.d.ts 提供全局 TS 类型声明。"
---

## createDpKit

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

> 💡 createDpKit 返回的 interceptors 需传入 SmartDeviceModel 构造选项，
> 搭配 useStructuredProps / useStructuredActions 使用时还需在设备初始化后调用 init。

### 描述

创建 DP 协议套件，提供功能点的结构化解析、下发拦截、节流/防抖等增强能力

### 参数

`Params`

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `option` | `CreateDpKitOptions` | 否 | dp-kit 配置选项 |

### 返回值

类型: `CreateDpKitResult`

dp-kit 实例，包含 init、interceptors、destroy 等方法

**`type` CreateDpKitResult**

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `init` | `(device: any) => void` | 初始化设备状态，在需要搭配 useStructuredProps 时须在设备模型初始化完毕后调用 |
| `interceptors` | `Record<string, any>` | dp-kit 默认拦截器配置 |
| `onDeviceInfoUpdated` | `(ctx: any) => (next: (data: any) => any) => (data: any) => any` | dp-kit onDeviceInfoUpdated 拦截器，如需单独搭配使用时可考虑 |
| `onDpDataChange` | `(ctx: any) => (next: (data: any) => any) => (data: any) => any` | dp-kit onDpDataChange 拦截器，如需单独搭配使用时可考虑 |
| `publishDps` | `(ctx: any) => (next: (dpState: Record<string, any>, options?: SendDpOption) => any) => (dpState: Record<string, any>, options?: SendDpOption) => any` | dp-kit publishDps 拦截器，如需单独搭配使用时可考虑 |
| `destroy` | `() => void` | 销毁 dp-kit，清理 flush 定时器、节流和防抖映射等资源。 应在 SmartDeviceModel 销毁时调用（如 SdmProvider 的 useEffect cleanup 中） |

### 引用对象

##### `type` CreateDpKitOptions

createDpKit 的配置项，统一描述协议解析、全局下发选项与前后置 hooks。

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `protocols` | `Record<string, CustomRawDpMap>` | DP 协议映射表，将复合字符串类型的 DP（如 colour_data）拆解为结构化对象。 key 为 dpCode，value 为自定义 Transformer  需实现 parser/formatter：`{ colour_data: new ColourTransformer() }`  - parser(raw: string) => T — 将设备上报的原始字符串解析为结构化对象 - formatter(data: T) => string — 将结构化对象序列化为下发给设备的字符串  注册后可通过 useStructuredProps / useStructuredActions 读写结构化数据 |
| `sendDpOption` | `SendDpOption` | DP 下发选项 |
| `onBeforeSendDp` | `(dpState: DpState) => any` | 下发 DP 前的钩子 |
| `onAfterSendDp` | `(dpState: DpState) => any` | 下发 DP 前的钩子 |

##### `type` CreateDpKitResult

createDpKit 的返回结果，包含一组可直接挂到 SmartDeviceModel 的拦截器，
以及初始化结构化 DP 状态所需的 `init` / `destroy` 生命周期方法。

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `init` | `(device: any) => void` | 初始化设备状态，在需要搭配 useStructuredProps 时须在设备模型初始化完毕后调用 |
| `interceptors` | `Record<string, any>` | dp-kit 默认拦截器配置 |
| `onDeviceInfoUpdated` | `(ctx: any) => (next: (data: any) => any) => (data: any) => any` | dp-kit onDeviceInfoUpdated 拦截器，如需单独搭配使用时可考虑 |
| `onDpDataChange` | `(ctx: any) => (next: (data: any) => any) => (data: any) => any` | dp-kit onDpDataChange 拦截器，如需单独搭配使用时可考虑 |
| `publishDps` | `(ctx: any) => (next: (dpState: Record<string, any>, options?: SendDpOption) => any) => (dpState: Record<string, any>, options?: SendDpOption) => any` | dp-kit publishDps 拦截器，如需单独搭配使用时可考虑 |
| `destroy` | `() => void` | 销毁 dp-kit，清理 flush 定时器、节流和防抖映射等资源。 应在 SmartDeviceModel 销毁时调用（如 SdmProvider 的 useEffect cleanup 中） |

##### `type` CustomRawDpMap

自定义 DP 协议转换器，用于将原始 DP 字符串与结构化对象互转。
适用于 raw/string 类型的复合 DP（如灯的 colour_data "00ff003e8"），
将单个字符串拆解为多个语义字段（如 { hue, saturation, value }）。

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `parser` | `(dpValue: string) => any` | 将设备上报的原始 DP 字符串解析为结构化对象 |
| `formatter` | `(parsedDpValue: any) => string` | 将结构化对象序列化为下发给设备的 DP 字符串 |

##### `type` SendDpOption

DP 下发选项，可作为 createDpKit 的全局默认配置，也可在单次 publishDps / action 调用时覆盖。
全局 `sendDpOption` 适合声明产品级默认行为；
单次下发传入的 options 适合临时覆盖节流、防抖、协议解析或乐观更新策略。
注：依赖 dp-kit 拦截器才可使用。

| 属性 | 类型 | 最低版本 | 描述 |
| --- | --- | --- | --- |
| `immediate` | `boolean` | - | 是否立即触发 state 更新，必须依赖 dp-kit 拦截器才可使用 |
| `ignoreDpDataResponse` | `boolean \| IgnoreDpChangeInterceptorOptions` | `1.11.0` | 是否忽略 DP 功能点上报，默认 false |
| `synchronizeDevProperty` | `boolean \| DevPropInterceptorOptions` | `1.11.0` | 是否将 dpData 和云端设备属性同步，默认 false |
| `ordered` | `boolean` | - | 多个 DP 是否按对象里的顺序下发，必须依赖 dp-kit 拦截器才可使用，默认 false |
| `checkRepeat` | `boolean` | - | 是否进行重复值判断不下发，必须依赖 dp-kit 拦截器才可使用，默认 false 与当前 `dpState` 进行比较，重复值检出不下发 |
| `delay` | `number` | - | 延迟下发，必须依赖 dp-kit 拦截器才可使用，默认 0，单位 ms |
| `throttle` | `number` | - | 下发节流 (与防抖冲突)，必须依赖 dp-kit 拦截器才可使用，默认 0，单位 ms |
| `debounce` | `number` | - | 下发防抖 (与节流冲突)，必须依赖 dp-kit 拦截器才可使用，默认 0，单位 ms |
| `protocols` | `Record<string, CustomRawDpMap>` | - | 单次下发时临时指定的 DP 协议转换器，必须依赖 dp-kit 拦截器才可使用。 key 为 dpCode，value 为 `{ parser, formatter }` 对象： - parser(dpValue: string) => any — 将原始 DP 字符串解析为结构化对象 - formatter(parsedValue: any) => string — 将结构化对象序列化为 DP 字符串 仅影响本次调用，不覆盖 createDpKit 中的全局 protocols 配置 |

##### `type` DpState

功能点状态对象，key 为功能点 code，value 为功能点值

```typescript
export type DpState = Record<string, DpValue>;
```

##### `type` IgnoreDpChangeInterceptorOptions

忽略 DP 数据变化拦截器的配置选项

用于配置智能设备面板中 DP 上报事件的防抖机制，避免面板操作后的
即时响应干扰用户体验或业务逻辑

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `whiteDpCodes` | `string[]` | 白名单 dp，不会忽略上报 |
| `timeout` | `number` | 防抖超时检查，毫秒，默认为 5000 - 从面板下发 dp 到收到 dp 回复之间的最大时间，超过此时间才会触发 dpDataChange。 - 用于 dp 上报事件的防抖 |
| `customRule` | `(dpState: DpState, lastSendTimestamp: number) => boolean` | 自定义忽略规则 > 优先级最高，配置了自定义规则后，whiteDpCodes 和 timeout 项将无效 |

##### `type` DevPropInterceptorOptions

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `blackDpCodes` | `string[]` | 黑名单 dp，不会同步到云端 |
| `defaultState` | `DpState` | 首次进入时，默认的设备状态, 支持异步初始化 |
| `throttle` | `number` | 下发节流，毫秒，默认为 0 如果设置为 0，则不进行节流。 |

##### `type` DpValue

功能点值类型，可能为 boolean、number、string

```typescript
export type DpValue = boolean | number | string;
```


### 示例代码

#### 基础用法

```ts
import { SmartDeviceModel, createDpKit } from '@ray-js/panel-sdk';

const schema = [
  { code: 'switch_1', type: 'bool' },
  { code: 'colour_data', type: 'raw' },
] as const;

const dpKit = createDpKit<typeof schema>({
  protocols: {
    colour_data: {
      parser: raw => JSON.parse(raw),
      formatter: structured => JSON.stringify(structured),
    },
  },
});

const sdm = new SmartDeviceModel<typeof schema>({
  interceptors: dpKit.interceptors,
});

await sdm.init();
dpKit.init(sdm);
```

#### 带协议解析和节流

```ts
const dpKit = createDpKit<typeof schema>({
  protocols: {
    colour_data: {
      parser: raw => JSON.parse(raw),
      formatter: value => JSON.stringify(value),
    },
  },
  sendDpOption: {
    throttle: 300,
  },
});

const device = new SmartDeviceModel<typeof schema>({
  interceptors: dpKit.interceptors,
});

await device.init();
dpKit.init(device);

// 后续所有下发都会继承 300ms 节流
await device.publishDps({
  colour_data: { hue: 240, saturation: 1000, value: 1000 },
});
```

#### 忽略设备上报响应

```ts
const dpKit = createDpKit<typeof schema>({
  sendDpOption: {
    immediate: true,
    ignoreDpDataResponse: {
      timeout: 5000,
      whiteDpCodes: ['switch_1'],
    },
  },
});

const device = new SmartDeviceModel<typeof schema>({
  interceptors: dpKit.interceptors,
});
```

#### 搭配 hooks 使用

```tsx
import { useStructuredActions, useStructuredProps } from '@ray-js/panel-sdk';

const colour = useStructuredProps(props => props.colour_data);
const actions = useStructuredActions();

actions.colour_data.set({
  hue: colour.hue,
  saturation: colour.saturation,
  value: 800,
});
```