---
name: "SmartAlarmAbility.addCustomAlarm"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.8.0" }
title: "addCustomAlarm - 新增或修改自定义的告警规则。"
summary: "新增或修改自定义的告警规则，支持配置功能点条件、前置条件和持续时间。"
---

## SmartAlarmAbility.addCustomAlarm

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

> 💡 仅支持单设备，不支持群组环境。
> 注意，返回示例仅供参考，其包含字段大于返回参数定义范围，请勿使用除本文返回参数定义以外的返回数据，否则可能会导致程序异常。

### 描述

新增或编辑自定义的告警规则

### 参数

`Params`

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `options` | `AddCustomAlarmOptions` | 是 | 告警规则配置 |

### 返回值

类型: `Promise<AddCustomAlarmResult>`

元组 [新增/更新的规则, 更新后的完整规则列表]

### 引用对象

##### `type` AddCustomAlarmOptions

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `devId` | `string` | 设备 ID，默认从默认设备环境中取 |
| `name` | `string` | 告警的名称或备注 |
| `preCondition` | `Object` | 告警触发的前置条件 |
| `condition` | `[DpId, "==" \| "<" \| ">" \| "<=" \| ">=", boolean \| number \| string][]` | 告警触发的功能点条件，[DpId, Operator, DpValue][] |
| `duration` | `number` | 告警触发的功能点条件持续多久才会触发执行 action 动作，单位为秒 |

##### `type` AddCustomAlarmResult

```typescript
[AddCustomAlarmBindResult, CustomAlarmList]
```

##### `type` DpId

```typescript
type DpId = number;
```

##### `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` 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` AlarmTriggerRuleVO

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `ownerId` | `string` | 家庭 id |
| `enabled` | `boolean` | 告警规则是否启用 |
| `id` | `string` | 执行规则 id |
| `name` | `string` | 告警名称或备注 |
| `preConditions` | `AlarmPreCondition[] \| unknown[]` | 执行动作的前置条件，详见 AlarmPreCondition 定义 |
| `conditions` | `CustomAlarmCondition[] \| unknown[]` | 执行动作的条件，详见 CustomAlarmCondition 定义 |
| `actions` | `CustomAlarmSceneAction[] \| unknown[]` | 执行的动作，详见 CustomAlarmSceneAction 定义 |

##### `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 |

##### `type` AddCustomAlarmOptions.preCondition

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `startTime` | `string` | 告警可触发的开始时间，默认全天，即 00:00 |
| `endTime` | `string` | 告警可触发的结束时间，默认全天，即 23:59 |
| `loops` | `string` | 告警可触发的日期，默认全周，即 '1111111' |


### 示例代码

#### 示例

```typescript
const [newRule, allRules] = await sdm.alarm.addCustomAlarm({
  name: '高温告警',
  condition: [['temp_current', '>', 40]],
  preCondition: {
    startTime: '08:00',
    endTime: '22:00',
    loops: '1111111',
  },
});
console.log('新增规则:', newRule.bindId);
```