---
name: "useCustomAlarm"
mode: "api"
versionRequirements:
- { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "useCustomAlarm - 基于 sdm 及 alarm-ability 实现"
summary: "useCustomAlarm 是 @ray-js/panel-sdk 提供的 React Hook，基于 sdm 及 SmartAlarmAbility 实现，提供自定义告警的完整增删改查能力：getCustomAlarmList 查询列表、addCustomAlarm 新增/编辑规则、setCustomAlarmStatus 启用/禁用（通过 bindId+enable）、deleteCustomAlarm 删除规则，返回 data（LinkageRule[]）和 loading 状态，列表变化时自动驱动重渲染。仅支持单设备不支持群组。"
questions:
- "useCustomAlarm 返回的 data、loading、getCustomAlarmList、addCustomAlarm、setCustomAlarmStatus、deleteCustomAlarm 分别是什么？"
- "getCustomAlarmList 支持传入 dpId 和 devId 参数，不传时默认查询当前设备的全部自定义告警吗？"
- "addCustomAlarm 方法的 AddCustomAlarmOptions 参数需要包含哪些告警规则配置？"
- "setCustomAlarmStatus 通过 bindId 和 enable 参数启用或禁用告警，返回值 Promise<[boolean, LinkageRule[]]> 中两个元素分别是什么？"
- "deleteCustomAlarm 删除告警规则后返回的 LinkageRule[] 是更新后的完整列表吗？"
- "useCustomAlarm 仅支持单设备不支持群组，在群组环境下应如何处理？"
- "使用 useCustomAlarm 前需要同时挂载 SdmProvider 和接入 SmartAlarmAbility，两者缺一不可吗？"
- "如何用 TyList 和 TySwitch 组件展示自定义告警列表并通过 onChange 控制 setCustomAlarmStatus？"
- "LinkageRule 类型中 bindId、enable、triggerRuleVO.name 分别代表什么？"
- "useCustomAlarm 与 useBuiltInAlarm 的区别是什么（自定义告警 vs 内置告警）？"
---
单设备支持
群组不支持
## useCustomAlarm
> [VERSION] @ray-js/panel-sdk >= 1.0.0
> 💡 使用前需同时满足两个条件：
> 1. 项目已挂载 SdmProvider
> 2. SmartDeviceModel 初始化时已配置 SmartAlarmAbility
### 描述
获取设备自定义告警列表与增删改查操作，仅支持单设备，不支持群组环境。
### 参数
无
### 返回值
类型: `CustomAlarmResult`
自定义告警数据、加载状态及管理方法
**`type` CustomAlarmResult**
| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `data` | `CustomAlarmRule[]` | 设备自定义的告警列表信息 |
| `loading` | `boolean` | 设备自定义的告警列表信息是否正在加载中 |
| `getCustomAlarmList` | `(options: GetCustomAlarmListParams) => Promise` | 根据设备 id 查询该设备自定义的告警列表信息 |
| `addCustomAlarm` | `(options: AddCustomAlarmOptions) => Promise<[AddCustomAlarmBindResult, CustomAlarmList]>` | 新增或编辑自定义的告警规则 |
| `setCustomAlarmStatus` | `(options: SetCustomAlarmStatusParams) => Promise<[boolean, CustomAlarmList]>` | 启用或禁用自定义的告警规则 |
| `deleteCustomAlarm` | `(options: DeleteCustomAlarmParams) => Promise<[boolean, CustomAlarmList]>` | 删除自定义的告警规则 |
### 引用对象
##### `type` CustomAlarmResult
| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `data` | `CustomAlarmRule[]` | 设备自定义的告警列表信息 |
| `loading` | `boolean` | 设备自定义的告警列表信息是否正在加载中 |
| `getCustomAlarmList` | `(options: GetCustomAlarmListParams) => Promise` | 根据设备 id 查询该设备自定义的告警列表信息 |
| `addCustomAlarm` | `(options: AddCustomAlarmOptions) => Promise<[AddCustomAlarmBindResult, CustomAlarmList]>` | 新增或编辑自定义的告警规则 |
| `setCustomAlarmStatus` | `(options: SetCustomAlarmStatusParams) => Promise<[boolean, CustomAlarmList]>` | 启用或禁用自定义的告警规则 |
| `deleteCustomAlarm` | `(options: DeleteCustomAlarmParams) => Promise<[boolean, CustomAlarmList]>` | 删除自定义的告警规则 |
##### `type` AlarmTriggerRuleVO
| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `ownerId` | `string` | 家庭 id |
| `enabled` | `boolean` | 告警规则是否启用 |
| `id` | `string` | 执行规则 id |
| `name` | `string` | 告警名称或备注 |
| `preConditions` | `AlarmPreCondition[] \| unknown[]` | 执行动作的前置条件，详见 AlarmPreCondition 定义 |
| `conditions` | `CustomAlarmCondition[] \| unknown[]` | 执行动作的条件，详见 CustomAlarmCondition 定义 |
| `actions` | `CustomAlarmSceneAction[] \| unknown[]` | 执行的动作，详见 CustomAlarmSceneAction 定义 |
##### `type` CustomAlarmRule
| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `triggerRuleId` | `string` | 告警执行的规则 id |
| `triggerRuleVO` | `AlarmTriggerRuleVO` | 触发告警规则的详细信息，详见 AlarmTriggerRuleVO 定义 |
| `bizDomain` | `string` | 业务域标识，在告警 SDK 下固定为 miniAppPanelSDKAlarm |
| `associativeEntityValue` | `string` | 当 associativeEntityId 不足以区分情况下使用，比如使用的是同一个功能点时又要区分告警类型的情况下，可以使用 DpValue，一般情况下用不到 |
| `sourceEntityId` | `string` | 和当前告警相关联的设备 ID |
| `name` | `string` | 名称或备注 |
| `icon` | `string` | 图标 |
| `bindId` | `number` | 绑定 ID |
| `associativeEntityId` | `string` | 和当前告警相关联的功能点 DP ID |
| `enable` | `boolean` | 是否启用 |
##### `type` Operator
```typescript
type Operator = '==' | '<' | '>' | '<=' | '>=';
```
##### `type` DpValue
功能点值类型，可能为 boolean、number、string
```typescript
export type DpValue = boolean | number | string;
```
##### `type` AddCustomAlarmBindResult
| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `associativeEntityValue` | `string` | 关联实体值，用于区分告警类型 |
| `associativeEntityId` | `string` | 关联实体 ID，通常为功能点 ID |
| `bindId` | `number` | 绑定 ID |
| `bizDomain` | `string` | 业务域，告警固定为 miniAppPanelSDKAlarm |
| `enable` | `boolean` | 是否启用 |
| `sourceEntityId` | `string` | 设备 ID |
##### `type` CustomAlarmList
```typescript
export type CustomAlarmList = CustomAlarmRule[];
```
##### `type` AlarmPreCondition
| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `expr` | `CustomAlarmPreConditionExpr` | 条件表达式 |
| `condType` | `"timeCheck"` | 条件类型，告警 SDK 固定为 timeCheck |
| `id` | `string` | 条件 ID |
##### `type` CustomAlarmCondition
| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `id` | `string` | 条件 ID |
| `ruleId` | `string` | 规则 ID |
| `entityId` | `string` | 数据 ID |
| `entitySubIds` | `string` | 抽象子数据 ID |
| `expr` | `string` | 条件的表达式 |
##### `type` CustomAlarmSceneAction
| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `id` | `string` | 条件 id |
| `ruleId` | `string` | 场景 id |
| `actionExecutor` | `string` | 动作类型，在告警 SDK 下固定为 appPushTrigger |
##### `type` CustomAlarmPreConditionExpr
| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `timeZoneId` | `string` | 时区 id，如 Asia/Shanghai |
| `start` | `string` | 开始时间，格式为 HH:mm，如 00:00 |
| `timeInterval` | `string` | 时间间隔，固定为 'custom' |
| `loops` | `string` | 循环日期，'1111111' 说明为一周七天均开启，其中起始时间为周日 |
| `end` | `string` | 结束时间，格式为 HH:mm，如 23:59 |
### 示例代码
#### 示例
```tsx
import { useCustomAlarm } from '@ray-js/panel-sdk';
function AlarmPage() {
const { data, loading, getCustomAlarmList, setCustomAlarmStatus } = useCustomAlarm();
React.useEffect(() => {
getCustomAlarmList();
}, []);
const handleToggle = (item) => (value) => {
setCustomAlarmStatus({ bindId: item.bindId, enable: value });
};
return data.map(item => (
));
}
```