---
title: 使用
summary: 多设备管理使用说明，介绍 SmartDevicesManager 与 SdmProvider 的接入方式、与单设备和智能群组模型的区别，以及批量添加和异步加载多台设备的典型场景。
---

# 多设备管理使用

多设备管理能力基于 `SmartDevicesManager` 与 `SdmProvider` 的扩展，用于在同一小程序内管理多台设备的状态与下发指令。

## 与智能群组模型的关系

**智能群组模型（SGM）** 面向的是通过 App 在设备详情页手动创建出来的**群组设备**，其群组面板是由涂鸦云侧感知并分配的，开发者通过 `SmartGroupModel` 接入，行为上与单设备面板一致。

**多设备管理** 则完全不同：它不依赖云侧群组概念，而是在小程序内部**自由管理**若干台独立设备实例，更加原子化——你可以随时在小程序里 `add` / `batchAdd` 任意设备 ID，并通过多设备 Hooks 独立读取每台设备的 DP 状态和发起控制，不受群组机制约束。典型场景包括网关子设备批量控制页、多设备联动面板等。

## 与单设备的关系

- **单设备**：使用 [智能设备模型（SDM）](/cn/miniapp/solution-panel/ability/common/sdm/usage)，通过 `SdmProvider value={singleDevice}` 提供 `useProps`、`useDevice`、`useActions` 等。
- **多设备管理**：通过 `SdmProvider` 的 `deviceManager` 注入 `SmartDevicesManager`，使用多设备 Hooks：`useDevices`、`useDevicesProps`、`useDevicesActions` 等，详见 [多设备管理 - Hooks](/cn/miniapp/solution-panel/ability/common/multi-device/hooks/useDevices)。TypeScript 类型推导等说明见 [常见问题](/cn/miniapp/solution-panel/ability/common/multi-device/faq)。

## SdmProvider 多设备配置

多设备场景下，在根组件传入 `deviceManager`（`SmartDevicesManager` 实例），并可选用 `isNeedMainDeviceInitialized`、`isNeedAllDevicesInitialized` 控制何时完成初始化后再渲染子组件。

```tsx | pure
import React, { useEffect } from 'react';
import { SdmProvider, SmartDevicesManager } from '@ray-js/panel-sdk';

const deviceManager = new SmartDevicesManager();

export default function App({ children }) {
  useEffect(() => {
    deviceManager.init();
    return () => {
      deviceManager.destroy();
    };
  }, []);

  return (
    <SdmProvider
      deviceManager={deviceManager}
      isNeedMainDeviceInitialized={false}
      isNeedAllDevicesInitialized={false}
    >
      {children}
    </SdmProvider>
  );
}
```

<Callout type="info" emoji="ℹ️">
  `isNeedAllDevicesInitialized={true}` 时，SdmProvider 会等待所有已添加设备初始化完毕后再渲染子组件；`false` 时立即渲染，子组件自行处理加载状态。推荐在设备列表确定的场景下开启，不确定设备数量时设为 `false`。
</Callout>

## 典型场景

### 场景一：启动阶段即可获取所有设备 ID

适用于网关子设备批量控制等场景，启动时通过 `batchAdd` 一次性添加全部设备：

```tsx | pure
import { SmartDevicesManager, SdmProvider } from '@ray-js/panel-sdk';

const deviceManager = new SmartDevicesManager();

// 在组件外或 useEffect 中调用
deviceManager.batchAdd([
  { key: 'lamp1', deviceId: 'xxx_device_id_1' },
  { key: 'lamp2', deviceId: 'xxx_device_id_2' },
]);
```

### 场景二：主设备先就绪，子设备异步加载

主设备用 `SmartDeviceModel` 单独初始化并传给 `value`，子设备通过 `deviceManager.add` / `batchAdd` 异步添加：

```tsx | pure
import { SmartDeviceModel, SmartDevicesManager, SdmProvider } from '@ray-js/panel-sdk';

const mainDevice = new SmartDeviceModel({ deviceId: 'main_device_id' });
const deviceManager = new SmartDevicesManager();

export default function App({ children }) {
  useEffect(() => {
    mainDevice.init();
    deviceManager.init();
    // 异步获取子设备后再 add
    fetchSubDeviceIds().then(ids => {
      deviceManager.batchAdd(ids.map((deviceId, i) => ({ key: `sub${i}`, deviceId })));
    });
    return () => { deviceManager.destroy(); };
  }, []);

  return (
    <SdmProvider
      value={mainDevice}
      deviceManager={deviceManager}
      isNeedMainDeviceInitialized
      isNeedAllDevicesInitialized={false}
    >
      {children}
    </SdmProvider>
  );
}
```

API 详见 [多设备管理 - API](/cn/miniapp/solution-panel/ability/common/multi-device/api/constructor)（add、delete、batchAdd、batchDelete）。