useDevicesActions()

版本要求:
@ray-js/panel-sdk≥1.16.0

描述

获取关联设备的功能点操作方法集合

参数

无

返回值

类型：{ [key: string]: DpActions }
设备操作方法集合，key 为设备标识，value 为该设备的 actions 对象。
每个设备的 actions 使用方式与单设备 useActions 一致

引用对象

interfaceDpActions
属性类型描述
所有类型都有该方法，下发 DP 点，但需要根据功能点类型传入不同的值
只有 bool 类型和 bitmap 类型才有此方法，打开功能点或开启指定 bit 位
只有 bool 类型和 bitmap 类型才有此方法，关闭功能点或关闭指定 bit 位
只有 bool 类型和 bitmap 类型才有此方法，切换功能点或翻转指定 bit 位
只有 value 类型才有此方法，根据当前功能点步长 step 进行递增，
只有 value 类型才有此方法，根据当前功能点步长 step 进行递减
只有 enum 类型才有此方法，切换到前一个枚举值
只有 enum 类型才有此方法，切换到下一个枚举值
只有 enum 类型才有此方法，随机切换到一个枚举值
typeIgnoreDpChangeInterceptorOptions忽略 DP 数据变化拦截器的配置选项 用于配置智能设备面板中 DP 上报事件的防抖机制，避免面板操作后的 即时响应干扰用户体验或业务逻辑
属性类型描述
whiteDpCodesstring[]白名单 dp，不会忽略上报
timeoutnumber防抖超时检查，毫秒，默认为 5000
- 从面板下发 dp 到收到 dp 回复之间的最大时间，超过此时间才会触发 dpDataChange。
- 用于 dp 上报事件的防抖
自定义忽略规则
> 优先级最高，配置了自定义规则后，whiteDpCodes 和 timeout 项将无效
typeDevPropInterceptorOptions
属性类型描述
blackDpCodesstring[]黑名单 dp，不会同步到云端
首次进入时，默认的设备状态, 支持异步初始化
throttlenumber下发节流，毫秒，默认为 0
如果设置为 0，则不进行节流。
typeCustomRawDpMap自定义 DP 协议转换器，用于将原始 DP 字符串与结构化对象互转。 适用于 raw/string 类型的复合 DP（如灯的 colour_data "00ff003e8"）， 将单个字符串拆解为多个语义字段（如 { hue, saturation, value }）。
属性类型描述
将设备上报的原始 DP 字符串解析为结构化对象
将结构化对象序列化为下发给设备的 DP 字符串
typeDpState功能点状态对象，key 为功能点 code，value 为功能点值
export type DpState = Record<string, DpValue>;
typeDpValue功能点值类型，可能为 boolean、number、string
export type DpValue = boolean | number | string;

示例代码

控制指定设备的各类型 DP 功能点

// devices/schema.ts — as const 是类型推导的基石，set 为通用方法，其余为类型专属快捷方法
import { useDevicesActions, useDevicesProps } from '@ray-js/panel-sdk';

export const schema = [
  { code: 'switch_led',  property: { type: 'bool' }, type: 'obj', mode: 'rw', id: 1, name: '开关' },
  { code: 'brightness',  property: { type: 'value', min: 10, max: 1000, step: 1 }, type: 'obj', mode: 'rw', id: 2, name: '亮度' },
  { code: 'work_mode',   property: { type: 'enum', range: ['white', 'colour'] }, type: 'obj', mode: 'rw', id: 3, name: '模式' },
  { code: 'fault',       property: { type: 'bitmap', maxlen: 8 }, type: 'obj', mode: 'ro', id: 4, name: '故障' },
  { code: 'colour_data', property: { type: 'string', maxlen: 255 }, type: 'obj', mode: 'rw', id: 5, name: '颜色' },
] as const;

export default function MultiDeviceControl() {
  const actions = useDevicesActions();
  // 推荐：精确选用需要的状态，避免无关变化引起无意义渲染
  const mainSwitch = useDevicesProps(props => props.main?.switch_led);

  const handleToggle = () => {
    // ✅ set — 所有类型通用
    actions.main?.switch_led.set(true);            // bool
    actions.main?.brightness.set(500);             // value
    actions.main?.work_mode.set('colour');         // enum（IDE 提示 'white' | 'colour'）
    actions.main?.fault.set(3);                    // number(bitmap)
    actions.main?.colour_data.set('000003e803e8'); // string

    // bool 专属：on / off / toggle
    actions.main?.switch_led.toggle();
    actions.main?.switch_led.on();
    actions.main?.switch_led.off();

    // value 专属：inc / dec（按 step 步进，自动 clamp 到 min~max）
    actions.main?.brightness.inc();               // +1（默认 step）
    actions.main?.brightness.dec(100);            // -100

    // enum 专属：prev / next / random
    actions.main?.work_mode.next();               // 切换到下一个枚举值
    actions.main?.work_mode.prev();

    // bitmap 专属：on(idx) / off(idx) / toggle(idx)
    actions.main?.fault.on(0);                    // 置位 bit 0
    actions.main?.fault.off(1);                   // 清除 bit 1
    actions.main?.fault.toggle(2);                // 翻转 bit 2
  };

  return (
    <View onClick={handleToggle}>
      <Text>主设备: {mainSwitch ? '开' : '关'}</Text>
    </View>
  );
}