import { onGroupDpDataChangeEvent, onGroupInfoChange, onNetworkStatusChange, onBluetoothAdapterStateChange, onDeviceOnlineStatusUpdate, onDeviceInfoUpdated, queryDps } from '@ray-js/ray'; import { PromisifyTTT, GetTTTEventListener } from '../types'; import { LogConfig } from './utils'; import { ReadonlyDpSchemaList, SmartDeviceModelAbility, SmartDeviceModelAbilities, GetSmartDeviceModelProps, GetSmartDeviceModelWatch, GetSmartDeviceModelActions, GetSmartGroupModelGroupInfo, GetSmartDeviceModelDpSchema, PublishDpsInterceptor, OnNetworkStatusChangeInterceptor, OnBluetoothAdapterStateChangeInterceptor, OnGroupDpDataChangeInterceptor, OnGroupInfoChangeInterceptor, OnDeviceOnlineStatusUpdateInterceptor, OnDeviceInfoUpdatedInterceptor, GetSmartDeviceDpCodes, InitDpStateInterceptor, InitDevInfoInterceptor } from './types'; import { publishDps } from '../kit'; type SmartGroupModelOptions = { /** * 群组 ID,选填,默认从小程序环境启动参数自动获取 */ groupId?: string; /** * 智能群组能力列表 * @internal */ abilities?: SmartDeviceModelAbilities; /** * @internal */ mixin?: SmartGroupModel[]; /** * 日志配置 * @internal */ logConfig?: LogConfig; /** * 智能群组模型拦截器,非稳定 API * @internal * @unstable */ interceptors?: { /** * 初始化拦截器配置 */ init?: { /** * DP 状态转换拦截器 * 在以下时机被调用: * - 模型初始化时(action: 'init') * - dp 数据变化时(action: 'onGroupDpDataChangeEvent' | 'dp-kit') * - 设备信息更新时(action: 'onGroupInfoChange') * * 拦截器接收完整的 dpState 和本次变更的 newDpState,返回处理后的 dpState * @default [logger] */ initDpState?: InitDpStateInterceptor[]; /** * 设备信息转换拦截器 * 在以下时机被调用: * - 模型初始化时(action: 'init') * - 群组信息更新时(action: 'onGroupInfoChange') * @default [logger] */ initDevInfo?: InitDevInfoInterceptor[]; }; /** * 请求拦截器配置 */ request?: { /** * @default [logger] */ publishDps?: PublishDpsInterceptor[]; }; /** * 响应拦截器配置 */ response?: { /** * @default [logger] */ onDpDataChange?: OnGroupDpDataChangeInterceptor[]; /** * @default [logger] */ onDeviceOnlineStatusUpdate?: OnDeviceOnlineStatusUpdateInterceptor[]; /** * @default [logger] */ onDeviceInfoUpdated?: OnDeviceInfoUpdatedInterceptor[]; /** * @default [logger] */ onGroupDpDataChangeEvent?: OnGroupDpDataChangeInterceptor[]; /** * @default [logger] */ onGroupInfoChange?: OnGroupInfoChangeInterceptor[]; /** * @default [logger] */ onNetworkStatusChange?: OnNetworkStatusChangeInterceptor[]; /** * @default [logger] */ onBluetoothAdapterStateChange?: OnBluetoothAdapterStateChangeInterceptor[]; }; }; }; declare const queryDpsAsync: PromisifyTTT; /** * 智能群组设备模型,提供群组设备功能点状态管理、事件监听、指令下发等核心能力 * @public * @since @ray-js/panel-sdk 1.5.0 * @typeParam S - 当前智能群组模型的 DpSchema 功能点描述定义 * @typeParam A - 当前智能群组模型的自定义高级能力定义 * @remarks * 所有 DP 相关 API 的类型均由泛型 S(ReadonlyDpSchemaList)在编译期推导, * S 来自业务项目 devices/schema.ts 中 as const 声明的 Schema 常量。 * * Schema property.type 与 TypeScript 类型映射: * - bool → boolean(true/false) * - value → number(受 property.min/max/step 运行时约束,类型仅为 number) * - enum → props 为 string;publishDps 入参为 property.range 字面量联合(如 'white' | 'colour') * - bitmap → number(位运算值,配合 actions 的 on(idx)/off(idx) 操作指定 bit 位) * - string → string * - raw(外层 type='raw')→ string * * 与 SmartDeviceModel 类似,但专用于群组设备场景。 * 群组设备共享同一套 DP Schema,控制指令会下发给群组内所有设备。 * * Schema 必须使用 as const 断言,否则字面量类型推导退化。 * @param options - 群组模型初始化配置,包含 abilities(高级能力列表)和 interceptors(事件拦截器)等选项 * @example 基础初始化 * ```typescript * import { SmartGroupModel } from '@ray-js/panel-sdk'; * import { defaultSchema } from './devices/schema'; * * type Schema = typeof defaultSchema; * const group = new SmartGroupModel(); * await group.init(); * * // 初始化后即可访问群组状态 * const props = group.getDpState(); // { switch_led: boolean, work_mode: string, ... } * const groupInfo = group.getGroupInfo(); // 群组信息 * ``` */ export default class SmartGroupModel { /** * @param options - 群组模型初始化配置,包含 abilities(高级能力列表)和 interceptors(事件拦截器)等选项 */ constructor(options?: SmartGroupModelOptions); /** * 异步初始化智能群组后再返回其实例 * @public * @since @ray-js/panel-sdk 1.5.0 * @param groupId - 群组 ID,不传则从小程序环境启动参数自动获取 * @returns 初始化完成的智能群组设备模型实例 * @typeOverride returns Promise * @remarks * 与 SmartDeviceModel.init 类似,但针对群组设备。 * 群组设备共享同一套 DP Schema,控制指令会下发给群组内所有设备。 * @example 基础初始化 * ```typescript * import { SmartGroupModel } from '@ray-js/panel-sdk'; * * const schema = [ * { code: 'switch_led', property: { type: 'bool' }, type: 'obj', mode: 'rw', id: 1, name: 'Switch' }, * { code: 'brightness', property: { type: 'value', min: 10, max: 1000, step: 1 }, type: 'obj', mode: 'rw', id: 2, name: 'Brightness' }, * ] as const; * * type Schema = typeof schema; * const group = new SmartGroupModel(); * await group.init(); // 自动从小程序启动参数获取 groupId * await group.init('your-group-id'); // 或指定 groupId * ``` */ init: (groupId?: string) => Promise; /** * 初始化智能群组的标准高级能力 * @internal */ initAbilities: () => { syncAbilities: never[]; asyncAbilities: never[]; }; /** * 注册智能群组模型初始化完毕事件回调 * @public * @since @ray-js/panel-sdk 1.5.0 * @param listener - 初始化完毕后触发的回调函数,接收当前群组实例作为参数 * @typeOverride listener (instance: SmartGroupModel) => void * @returns 监听器 ID,用于通过 offInitialized 取消监听 * @example * ```typescript * const id = group.onInitialized((instance) => { * console.log('群组初始化完成', instance.getGroupInfo().name); * }); * ``` */ onInitialized: (listener: (instance: SmartGroupModel) => void) => number; /** * 取消智能群组模型初始化完毕事件监听 * @public * @since @ray-js/panel-sdk 1.5.0 * @param id - onInitialized 返回的监听器 ID * @returns void * @example * ```typescript * const id = group.onInitialized(() => { console.log('已初始化'); }); * // 需要时取消监听 * group.offInitialized(id); * ``` */ offInitialized: (id: number) => void; /** * 初始化事件监听器自增索引 * @internal */ initializedIdx: number; /** * 初始化事件监听器集合 * @internal */ initializedListeners: Record) => void>; /** * 智能群组是否已初始化完毕 * @internal */ initialized: boolean; /** * 智能群组模型初始化配置 * @internal */ options: SmartGroupModelOptions; /** * 获取智能群组下的第一个设备信息并和智能群组合并后的数据 * @public * @since @ray-js/panel-sdk 1.5.0 * @returns 合并后的设备信息对象,包含群组信息及第一个子设备信息 * @typeOverride returns DevInfo * @remarks * * 这样设计是为了尽可能让使用智能设备模型 SDK 的开发者在绝大多数场景下不需要关心当前是单设备还是群组设备 * @example * ```typescript * const devInfo = group.getDevInfo(); * console.log(devInfo.name); // 群组名称 * ``` */ getDevInfo: () => { type: number; name: string; time: number; dpName: {}; isShare: boolean; pcc: string; productId: string; meshId: string; groupId: string; iconUrl: string; deviceList: ty.device.DeviceInfo_xd4g2r[]; deviceNum: number; localKey: string; pv: number; productInfo: {}; localId: string; groupKey: string; dpCodes: { readonly [Dp in S[number]["code"]]: import("./types").GetDpValueBySchema>; }; dps: { readonly [DpId in S[number]["id"]]: import("./types").GetDpValueBySchema>; }; idCodes: { readonly [DpId_1 in S[number]["id"]]: Extract["code"]; }; codeIds: { readonly [Dp_1 in S[number]["code"]]: Extract["id"]; }; schema: S; attribute: number; capability: number; ability: number; icon: string; devId: string; verSw: string; bv: string; uuid: string; panelConfig: any; activeTime: number; devAttribute: number; nodeId: string; parentId: string; category: string; standSchemaModel: {}; bizAttribute: number; sigmeshId: string; meta: any; isLocalOnline: boolean; isOnline: boolean; originJson: any; dpsTime: {}; secCategory: string; }; /** * 获取智能群组信息 * @public * @since @ray-js/panel-sdk 1.5.0 * @returns 群组信息对象,包含 groupId、name、deviceList、schema、dps 等 * @typeOverride returns GroupInfo * @remarks * 此方法为 SmartGroupModel 特有,SmartDeviceModel 上不可用。 * @example * ```typescript * const groupInfo = group.getGroupInfo(); * console.log(groupInfo.name); // 群组名称 * console.log(groupInfo.deviceList); // 群组内子设备列表 * ``` */ getGroupInfo: () => GetSmartGroupModelGroupInfo; /** * 获取智能群组 DP Schema(DP 功能点描述)映射表 * @public * @since @ray-js/panel-sdk 1.5.0 * @returns 功能点模型映射对象,key 为功能点 code,value 包含 attr、mode、property、type 等 * @typeOverride returns Record * @remarks * 群组内所有设备共享同一套 DP Schema。 * @example * ```typescript * const dpSchema = group.getDpSchema(); * console.log(dpSchema.switch_led.property.type); // 'bool' * ``` */ getDpSchema: () => GetSmartDeviceModelDpSchema; /** * 获取智能群组功能点状态 * @public * @since @ray-js/panel-sdk 1.5.0 * @returns 全量功能点状态对象,key 为功能点 code,value 类型由 Schema 推导 * @typeOverride returns DpState * @example * ```typescript * const dpState = group.getDpState(); * console.log(dpState.switch_led); // true * ``` */ getDpState: () => GetSmartDeviceModelProps; /** * 获取智能群组所处环境的网络状态 * @public * @since @ray-js/panel-sdk 1.5.0 * @returns 网络状态对象,包含 isConnected、networkType、signalStrength * @typeOverride returns NetworkState * @example * ```typescript * const network = group.getNetwork(); * console.log(network.isConnected); // true * ``` */ getNetwork: () => import("../types").NetworkState; /** * 获取智能群组所处环境的蓝牙状态 * @public * @since @ray-js/panel-sdk 1.5.0 * @returns 蓝牙状态对象,包含 available(蓝牙是否可用) * @example * ```typescript * const bluetooth = group.getBluetooth(); * console.log(bluetooth.available); // true * ``` */ getBluetooth: () => { available: boolean; }; /** * 智能群组模型 * @internal */ model: { props: GetSmartDeviceModelProps; watch: GetSmartDeviceModelWatch; actions: GetSmartDeviceModelActions; abilities: A; }; /** * SGM 类标识 */ __flag__: symbol; /** * 智能群组信息,实际通过 devInfo 代理获取 */ private __groupInfo__; /** * 智能群组 DP Schema(DP 功能点描述)映射表 */ private __dpSchema__; /** * 智能群组内部状态,实际通过 model.props 代理获取 */ private __dpState__; /** * 智能群组所处环境的网络状态,实际通过 network 代理获取 */ private __network__; /** * 智能群组所处环境的蓝牙状态,实际通过 bluetooth 代理获取 */ private __bluetooth__; /** * 智能群组内部内置的通用事件监听器 */ private __watches__; /** * 智能群组内部内置的 DP 事件监听器 */ private __dpWatches__; /** * 智能群组内置的事件监听器数量,持续递增 */ private __watchesCount__; /** * 智能群组模型拦截器 */ private __interceptors__; /** * 监听群组设备 DP 功能点变更事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param listener - 事件回调,接收包含 groupId、dps(变更的功能点 ID->值映射)等信息的参数 * @returns 监听器 ID,用于通过 offDpDataChange 取消监听 * @remarks * * 在群组设备环境中,原生 `@ray-js/ray` 的 `onDpDataChange` 实际上不会触发。 * 为了同时自动适配单设备和群组设备环境,这里会在底层 `onGroupDpDataChangeEvent` 触发时同步执行该回调。 * @example * ```typescript * const id = group.onDpDataChange((data) => { * console.log('DP 变更:', data.dps); * }); * // 需要时取消监听 * group.offDpDataChange(id); * ``` */ onDpDataChange: (listener: GetTTTEventListener) => number; /** * 监听智能群组在线状态变更 * @public * @since @ray-js/panel-sdk 1.5.0 * @param listener - 事件回调,接收包含设备在线状态等信息的参数 * @returns 监听器 ID,用于通过 offDeviceOnlineStatusUpdate 取消监听 * @remarks * * 在群组设备环境中,`onDeviceOnlineStatusUpdate` 正常情况下不会触发,因为群组目前没有在线状态变更事件。 * @example * ```typescript * const id = group.onDeviceOnlineStatusUpdate((data) => { * console.log('在线状态变更:', data); * }); * // 需要时取消监听 * group.offDeviceOnlineStatusUpdate(id); * ``` */ onDeviceOnlineStatusUpdate: (listener: GetTTTEventListener) => number; /** * 监听智能群组设备信息变更事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param listener - 事件回调,接收包含设备信息变更等数据的参数 * @returns 监听器 ID,用于通过 offDeviceInfoUpdated 取消监听 * @remarks * * 在群组设备环境中,原生 `@ray-js/ray` 的 `onDeviceInfoUpdated` 实际上不会触发。 * 为了同时自动适配单设备和群组设备环境,这里会在底层 `onGroupInfoChange` 触发时同步执行该回调。 * @example * ```typescript * const id = group.onDeviceInfoUpdated((data) => { * console.log('群组信息变更:', data); * }); * // 需要时取消监听 * group.offDeviceInfoUpdated(id); * ``` */ onDeviceInfoUpdated: (listener: GetTTTEventListener) => number; /** * 监听群组设备 DP 功能点变更事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param listener - 事件回调,接收包含 groupId、dps(变更的功能点 ID->值映射)等信息的参数 * @returns 监听器 ID,用于通过 offGroupDpDataChangeEvent 取消监听 * @example * ```typescript * const id = group.onGroupDpDataChangeEvent((data) => { * console.log('群组 DP 变更:', data.dps); * }); * // 需要时取消监听 * group.offGroupDpDataChangeEvent(id); * ``` */ onGroupDpDataChangeEvent: (listener: GetTTTEventListener) => number; /** * 监听智能群组信息变更事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param listener - 事件回调,接收包含 groupId 等群组信息变更数据的参数 * @returns 监听器 ID,用于通过 offGroupInfoChange 取消监听 * @example * ```typescript * const id = group.onGroupInfoChange((data) => { * console.log('群组信息变更:', data.groupId); * }); * // 需要时取消监听 * group.offGroupInfoChange(id); * ``` */ onGroupInfoChange: (listener: GetTTTEventListener) => number; /** * 监听网络状态变化事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param listener - 事件回调,接收包含 isConnected、networkType 等信息的参数 * @returns 监听器 ID,用于通过 offNetworkStatusChange 取消监听 * @example * ```typescript * const id = group.onNetworkStatusChange((data) => { * console.log('网络状态变化:', data.isConnected, data.networkType); * }); * // 需要时取消监听 * group.offNetworkStatusChange(id); * ``` */ onNetworkStatusChange: (listener: GetTTTEventListener) => number; /** * 监听蓝牙适配器状态变化事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param listener - 事件回调,接收包含 available 等信息的参数 * @returns 监听器 ID,用于通过 offBluetoothAdapterStateChange 取消监听 * @example * ```typescript * const id = group.onBluetoothAdapterStateChange((data) => { * console.log('蓝牙状态变化:', data.available ? '可用' : '不可用'); * }); * // 需要时取消监听 * group.offBluetoothAdapterStateChange(id); * ``` */ onBluetoothAdapterStateChange: (listener: GetTTTEventListener) => number; /** * 取消监听智能群组 DP 功能点变更事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param id - onDpDataChange 返回的监听器 ID * @returns void * @example * ```typescript * // 先注册监听 * const id = group.onDpDataChange((data) => { * console.log('DP 变更:', data.dps); * }); * // 需要时取消监听 * group.offDpDataChange(id); * ``` */ offDpDataChange: (id: number) => void; /** * 取消监听智能群组在线状态变更 * @public * @since @ray-js/panel-sdk 1.5.0 * @param id - onDeviceOnlineStatusUpdate 返回的监听器 ID * @returns void * @example * ```typescript * const id = group.onDeviceOnlineStatusUpdate((data) => { * console.log('在线状态变更:', data); * }); * // 需要时取消 * group.offDeviceOnlineStatusUpdate(id); * ``` */ offDeviceOnlineStatusUpdate: (id: number) => void; /** * 取消监听智能群组设备信息变更事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param id - onDeviceInfoUpdated 返回的监听器 ID * @returns void * @example * ```typescript * const id = group.onDeviceInfoUpdated((data) => { * console.log('群组信息变更:', data); * }); * // 需要时取消 * group.offDeviceInfoUpdated(id); * ``` */ offDeviceInfoUpdated: (id: number) => void; /** * 取消监听群组设备 DP 功能点变更事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param id - onGroupDpDataChangeEvent 返回的监听器 ID * @returns void * @example * ```typescript * const id = group.onGroupDpDataChangeEvent((data) => { * console.log('群组 DP 变更:', data.dps); * }); * // 需要时取消 * group.offGroupDpDataChangeEvent(id); * ``` */ offGroupDpDataChangeEvent: (id: number) => void; /** * 取消监听智能群组信息变更事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param id - onGroupInfoChange 返回的监听器 ID * @returns void * @example * ```typescript * const id = group.onGroupInfoChange((data) => { * console.log('群组信息变更:', data.groupId); * }); * // 需要时取消 * group.offGroupInfoChange(id); * ``` */ offGroupInfoChange: (id: number) => void; /** * 取消监听网络状态变化事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param id - onNetworkStatusChange 返回的监听器 ID * @returns void * @example * ```typescript * const id = group.onNetworkStatusChange((data) => { * console.log('网络状态变化:', data.isConnected, data.networkType); * }); * // 需要时取消 * group.offNetworkStatusChange(id); * ``` */ offNetworkStatusChange: (id: number) => void; /** * 取消监听蓝牙适配器状态变化事件 * @public * @since @ray-js/panel-sdk 1.5.0 * @param id - onBluetoothAdapterStateChange 返回的监听器 ID * @returns void * @example * ```typescript * const id = group.onBluetoothAdapterStateChange((data) => { * console.log('蓝牙状态变化:', data.available ? '可用' : '不可用'); * }); * // 需要时取消 * group.offBluetoothAdapterStateChange(id); * ``` */ offBluetoothAdapterStateChange: (id: number) => void; /** * 批量控制智能群组 DP 功能点 * @public * @since @ray-js/panel-sdk 1.5.0 * @param data - 要下发的功能点键值对。键为 DP Code,值类型由 Schema 推导: * bool -> boolean, value -> number, enum -> property.range 字面量联合, * bitmap -> number, string/raw -> string * @typeOverride data Record * @param options - 下发配置选项 * @typeOverride options SendDpOption * @returns 是否下发成功 * @remarks * 群组模式下,指令会下发给群组内所有设备。 * 与 useProps 不同,enum 类型的入参为 property.range 的字面量联合 *(如 'white' | 'colour'),IDE 会在编译期校验枚举值合法性。 * @example * ```typescript * // 控制群组内所有设备开关 * await group.publishDps({ switch_led: true }); * // 支持批量下发多个功能点 * await group.publishDps({ switch_led: true, brightness: 800 }); * ``` */ publishDps: (data: Partial>, options?: Parameters['1']) => Promise; /** * 主动查询设备功能点状态(群组不支持此操作) * @public * @since @ray-js/panel-sdk 1.5.0 * @param params - 查询参数 * @typeOverride params { groupId?: string; dpIds: number[]; } * @returns 提示信息,群组模式下不支持 queryDps * @remarks * 群组设备不支持主动查询功能点状态,调用后会输出警告并直接 resolve。 * @example * ```typescript * // 群组不支持,会输出警告 * const result = await group.queryDps({}); * ``` */ queryDps: (params: Partial['0']>) => Promise; /** * 将当前智能群组与其他智能群组进行组合,合并 model.abilities 里的能力 * @internal * @since @ray-js/panel-sdk 1.5.0 * @param m - 要组合的其他智能群组模型实例数组 * @returns 组合后的智能群组模型实例 * @example * ```typescript * import { SmartGroupModel } from '@ray-js/panel-sdk'; * * const mainGroup = new SmartGroupModel(); * const subGroup = new SmartGroupModel(); * * // 组合后,mainGroup 将拥有 subGroup 的 abilities * const composedGroup = mainGroup.compose([subGroup]); * ``` */ compose: >(m: SmartGroupModel[]) => SmartGroupModel; /** * 销毁当前智能群组实例,同时销毁所有事件监听器 * @public * @since @ray-js/panel-sdk 1.5.0 * @remarks * 销毁后实例不可再使用,所有通过 on* 系列方法注册的监听器均被移除。 * @example * ```typescript * group.destroy(); * ``` */ destroy: () => void; /** * 获取智能群组初始化所需的基础数据 */ protected __initializeDeviceEnv__: (gId?: string) => Promise; /** * 给涉及的方法挂载上 interceptors */ private __withInterceptors__; /** * 给对应的方法挂载上拦截器 */ private __withInterceptor__; /** * 注册所有和智能群组有关联的事件 */ private __registerDeviceEventsHandler__; /** * 销毁所有和智能群组有关联的事件 */ private __unregisterDeviceEventsHandler__; private __publishDps__; private __initDpState__; private __initDevInfo__; /** * 智能群组 DP 状态变动处理器,会给 watch 推送并更新 this.dpState */ private __dpDataChangeHandler__; /** * 群组 DP 名称和群组名称变更处理器,会更新 this.__groupInfo__ */ private __deviceInfoUpdateHandler__; /** * 智能群组所处环境的网络状态变化处理器,会更新 this.__network__ */ private __networkStatusChangeHandler__; /** * 智能群组所处环境的蓝牙适配器状态变化处理器,会更新 this.__bluetooth__ */ private __bluetoothAdapterStateChangeHandler__; } export {};