useStructuredActions - 基于 sdm 实例及 dp-kit 拦截器实现

单设备支持群组支持

useStructuredActions()

版本要求:

@ray-js/panel-sdk≥1.10.0

基于 sdm 实例及 dp-kit 拦截器实现。必须在 SdmProvider 内部使用。展开完整说明

基于 sdm 实例及 dp-kit 拦截器实现。必须在 SdmProvider 内部使用。
使用前请注意检查项目是否已挂载了 SdmProvider，项目接入可参考智能设备模型 - 使用，全新项目可直接基于 public-sdm 示例项目进行开发。
使用前请注意检查是否已配置接入了 dp-kit 拦截器，项目接入可参考拦截器 - 使用。
只返回配置了协议规则的功能点下发方法，不包含基础类型功能点（基础类型请用 useActions）。
同时支持单设备（SmartDeviceModel）和群组设备（SmartGroupModel）。与 useStructuredProps 对称使用：useStructuredProps 通过 Transformer.parser() 读取结构化数据，
useStructuredActions 通过 Transformer.formatter() 将结构化数据转为 DP 指令下发。

描述

获取经 dp-kit 协议转化后的结构化功能点下发方法集合

参数

无

返回值

类型：Record<DpCode, { set: (value: object, options?: SendDpOption) => Promise<boolean> }>

结构化功能点下发方法集合，key 为配置了 protocols 的 DP code，每个 key 提供 set(structuredValue) 方法；set 的入参类型由对应 Transformer.formatter() 的参数类型决定，内部自动调用 formatter 将结构化数据转为 DP 字符串后下发设备

引用对象

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

属性	类型	描述	最低版本
`immediate`	boolean	是否立即触发 state 更新，必须依赖 dp-kit 拦截器才可使用	-
		是否忽略 DP 功能点上报，默认 false	v1.11.0
		是否将 dpData 和云端设备属性同步，默认 false	v1.11.0
`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	-
		单次下发时临时指定的 DP 协议转换器，必须依赖 dp-kit 拦截器才可使用。 key 为 dpCode，value 为 `{ parser, formatter }` 对象： - parser(dpValue: string) => any — 将原始 DP 字符串解析为结构化对象 - formatter(parsedValue: any) => string — 将结构化对象序列化为 DP 字符串仅影响本次调用，不覆盖 createDpKit 中的全局 protocols 配置	-

typeIgnoreDpChangeInterceptorOptions忽略 DP 数据变化拦截器的配置选项用于配置智能设备面板中 DP 上报事件的防抖机制，避免面板操作后的即时响应干扰用户体验或业务逻辑

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

typeDevPropInterceptorOptions

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

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

export type DpState = Record<string, DpValue>;

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

export type DpValue = boolean | number | string;

示例代码

完整链路：读取 + 下发（以照明 colour_data 为例）

// ---- 1. devices/protocols/index.ts：实例化 parser 并映射到 DP code ----
import { protocols as sdkProtocols } from '@ray-js/panel-sdk';
import { lampSchemaMap } from '../schema';

export const protocols = {
  [lampSchemaMap.colour_data.code]: new sdkProtocols.ColourTransformer(),
  // ColourTransformer.parser()  返回 { hue, saturation, value } → useStructuredProps 读
  // ColourTransformer.formatter() 接收 { hue, saturation, value } → useStructuredActions 写
};

// ---- 2. devices/index.ts：创建 dpKit 并传给 sdm 实例 ----
import { SmartDeviceModel, createDpKit } from '@ray-js/panel-sdk';
import { protocols } from '@/devices/protocols';

export const dpKit = createDpKit({ protocols });
export const devices = {
  lamp: new SmartDeviceModel({ interceptors: dpKit.interceptors }),
};

// ---- 3. 页面组件：通过 useStructuredActions 下发结构化数据 ----
import { View, Text } from '@ray-js/ray';
import { useStructuredProps, useStructuredActions } from '@ray-js/panel-sdk';

export default function Home() {
  // 读：parser() 返回值决定 colour 的类型 { hue, saturation, value }
  const colour = useStructuredProps(props => props.colour_data);
  // 写：set() 入参类型 = formatter() 的参数类型，同为 { hue, saturation, value }
  const actions = useStructuredActions();

  return (
    <View onClick={() => actions.colour_data.set({ hue: 120, saturation: 800, value: 900 })}>
      <Text>hue: {colour.hue}</Text>
      <Text>saturation: {colour.saturation}</Text>
      <Text>value: {colour.value}</Text>
    </View>
  );
}