---
name: "useBuiltInAlarm"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.8.0" }
title: "useBuiltInAlarm - 基于 sdm 及 alarm-ability 实现"
summary: "useBuiltInAlarm 是 @ray-js/panel-sdk 提供的 React Hook，基于 sdm 及 SmartAlarmAbility 实现，提供设备内置告警的查询与开关能力：getBuiltInAlarmList 查询内置告警列表、setBuiltInAlarmStatus 通过 disabled+ruleIds（逗号分隔）批量启用/禁用告警，返回 data（AlarmList[]，含 id/name/enabled）和 loading 状态，列表变化时自动驱动重渲染。仅支持单设备不支持群组。"
questions:
  - "useBuiltInAlarm 返回的 data、loading、getBuiltInAlarmList、setBuiltInAlarmStatus 分别是什么？"
  - "getBuiltInAlarmList 可选传入 devId，不传时默认查询当前设备的内置告警列表吗？"
  - "setBuiltInAlarmStatus 的参数 ISetAlarmSwitch 中 disabled 和 ruleIds 分别代表什么？"
  - "ruleIds 参数格式是用逗号分隔的字符串（如 'ruleId1,ruleId2'），可以批量操作多条规则吗？"
  - "AlarmList 类型从 @ray-js/api/lib/cloud/interface 引入，包含哪些关键字段（id、name、enabled）？"
  - "useBuiltInAlarm 仅支持单设备不支持群组，在群组环境下应如何做兼容处理？"
  - "使用 useBuiltInAlarm 前需要同时挂载 SdmProvider 和接入 SmartAlarmAbility，SmartAlarmAbility 在哪里配置？"
  - "如何用 TyList 和 TySwitch 组件展示内置告警列表并通过 handleValueChange 切换 disabled 状态？"
  - "useBuiltInAlarm 与 useCustomAlarm 的区别是什么（内置告警查询/开关 vs 自定义告警增删改查）？"
  - "useBuiltInAlarm 关联的底层 SDM API 有哪些（getBuiltInAlarmList、setBuiltInAlarmStatus）？"
---

<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>单设备支持</span>
  <span style={{ backgroundColor: '#ff4d4f', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>群组不支持</span>
</div>

## useBuiltInAlarm

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

> 💡 使用前需同时满足两个条件：
> 1. 项目已挂载 SdmProvider
> 2. SmartDeviceModel 初始化时已配置 SmartAlarmAbility

### 描述

获取设备内置告警列表与开关操作，仅支持单设备，不支持群组环境。

### 参数

无


### 返回值

类型: `BuiltInAlarmResult`

内置告警数据、加载状态、查询和设置方法

**`type` BuiltInAlarmResult**

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `data` | `BuiltInAlarmRule[]` | 设备内置的告警列表信息 |
| `loading` | `boolean` | 设备内置的告警列表信息是否正在加载中 |
| `getBuiltInAlarmList` | `(devId: string) => Promise<BuiltInAlarmRule[]>` | 根据设备 id 查询该设备内置的告警列表信息 |
| `setBuiltInAlarmStatus` | `(options: SetBuiltInAlarmStatusParams) => Promise<[boolean, BuiltInAlarmList]>` | 设置设备内置的告警列表信息 |

### 引用对象

##### `type` BuiltInAlarmResult

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `data` | `BuiltInAlarmRule[]` | 设备内置的告警列表信息 |
| `loading` | `boolean` | 设备内置的告警列表信息是否正在加载中 |
| `getBuiltInAlarmList` | `(devId: string) => Promise<BuiltInAlarmRule[]>` | 根据设备 id 查询该设备内置的告警列表信息 |
| `setBuiltInAlarmStatus` | `(options: SetBuiltInAlarmStatusParams) => Promise<[boolean, BuiltInAlarmList]>` | 设置设备内置的告警列表信息 |

##### `type` BuiltInAlarmI18nData

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `name` | `AlarmLocaleText` | 名称多语言 |
| `content` | `AlarmLocaleText` | 内容多语言 |

##### `type` BuiltInAlarmRule

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `auditStatus` | `number` | 审核状态 |
| `boundForPanel` | `boolean` | 是否被场景面板绑定 |
| `boundForWiFiPanel` | `boolean` | 是否被 WiFi 场景面板绑定 |
| `enabled` | `boolean` | 是否启用 |
| `i18nData` | `BuiltInAlarmI18nData` | 多语言数据体 |
| `id` | `string` | 规则 ID |
| `localLinkage` | `boolean` | 是否为本地联动 |
| `name` | `string` | 规则名称 |
| `newLocalScene` | `boolean` | 是否为 App 管控本地联动 |
| `stickyOnTop` | `boolean` | 场景是否显示在首页 |

##### `type` BuiltInAlarmList

```typescript
export type BuiltInAlarmList = BuiltInAlarmRule[];
```

##### `type` AlarmLocaleText

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `en` | `string` | 英文文案 |
| `zh` | `string` | 中文文案 |


### 示例代码

#### 示例

```tsx
import { useBuiltInAlarm } from '@ray-js/panel-sdk';

function AlarmPage() {
  const { data, loading, getBuiltInAlarmList, setBuiltInAlarmStatus } = useBuiltInAlarm();

  React.useEffect(() => {
    getBuiltInAlarmList();
  }, []);

  const handleToggle = (item) => (value) => {
    setBuiltInAlarmStatus({ disabled: !value, ruleIds: item.id });
  };

  return data.map(item => (
    <Switch key={item.id} checked={item.enabled} onChange={handleToggle(item)} />
  ));
}
```