---
name: "SmartGroupModel"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.5.0" }
title: "constructor"
---

## SmartGroupModel

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

> 💡 所有 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 断言，否则字面量类型推导退化。

### 描述

智能群组设备模型，提供群组设备功能点状态管理、事件监听、指令下发等核心能力

### 参数

`Params`

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `options` | `SmartGroupModelOptions` | 否 | 群组模型初始化配置，包含 abilities（高级能力列表）和 interceptors（事件拦截器）等选项 |

### 返回值

类型: `SmartGroupModel`

SmartGroupModel 实例

#### 方法

| 方法名 | 说明 |
| --- | --- |
| `init` | 异步初始化智能群组后再返回其实例 |
| `onInitialized` | 注册智能群组模型初始化完毕事件回调 |
| `offInitialized` | 取消智能群组模型初始化完毕事件监听 |
| `getDevInfo` | 获取智能群组下的第一个设备信息并和智能群组合并后的数据 |
| `getGroupInfo` | 获取智能群组信息 |
| `getDpSchema` | 获取智能群组 DP Schema（DP 功能点描述）映射表 |
| `getDpState` | 获取智能群组功能点状态 |
| `getNetwork` | 获取智能群组所处环境的网络状态 |
| `getBluetooth` | 获取智能群组所处环境的蓝牙状态 |
| `onDpDataChange` | 监听群组设备 DP 功能点变更事件 |
| `onDeviceOnlineStatusUpdate` | 监听智能群组在线状态变更 |
| `onDeviceInfoUpdated` | 监听智能群组设备信息变更事件 |
| `onGroupDpDataChangeEvent` | 监听群组设备 DP 功能点变更事件 |
| `onGroupInfoChange` | 监听智能群组信息变更事件 |
| `onNetworkStatusChange` | 监听网络状态变化事件 |
| `onBluetoothAdapterStateChange` | 监听蓝牙适配器状态变化事件 |
| `offDpDataChange` | 取消监听智能群组 DP 功能点变更事件 |
| `offDeviceOnlineStatusUpdate` | 取消监听智能群组在线状态变更 |
| `offDeviceInfoUpdated` | 取消监听智能群组设备信息变更事件 |
| `offGroupDpDataChangeEvent` | 取消监听群组设备 DP 功能点变更事件 |
| `offGroupInfoChange` | 取消监听智能群组信息变更事件 |
| `offNetworkStatusChange` | 取消监听网络状态变化事件 |
| `offBluetoothAdapterStateChange` | 取消监听蓝牙适配器状态变化事件 |
| `publishDps` | 批量控制智能群组 DP 功能点 |
| `queryDps` | 主动查询设备功能点状态（群组不支持此操作） |
| `destroy` | 销毁当前智能群组实例，同时销毁所有事件监听器 |

### 引用对象

##### `type` SmartGroupModelOptions

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `groupId` | `string` | 群组 ID，选填，默认从小程序环境启动参数自动获取 |


### 示例代码

#### 基础初始化

```typescript
import { SmartGroupModel } from '@ray-js/panel-sdk';
import { defaultSchema } from './devices/schema';

type Schema = typeof defaultSchema;
const group = new SmartGroupModel<Schema>();
await group.init();

// 初始化后即可访问群组状态
const props = group.getDpState();      // { switch_led: boolean, work_mode: string, ... }
const groupInfo = group.getGroupInfo(); // 群组信息
```