---
name: "useCustomAlarm"
mode: "api"
versionRequirements:
  - { name: "@ray-js/panel-sdk", version: "1.0.0" }
title: "useCustomAlarm - Implemented based on sdm and alarm-ability"
summary: "useCustomAlarm is a React Hook provided by @ray-js/panel-sdk, implemented based on sdm and SmartAlarmAbility. It provides full CRUD capabilities for custom alarms. getCustomAlarmList queries the list; addCustomAlarm adds/edits rules; setCustomAlarmStatus enables/disables (via bindId+enable); deleteCustomAlarm deletes rules. Returns data (LinkageRule[]) and a loading state, and automatically triggers re-renders when the list changes. Only supports single devices, not groups."
questions:
  - "What are the data, loading, getCustomAlarmList, addCustomAlarm, setCustomAlarmStatus, and deleteCustomAlarm returned by useCustomAlarm?"
  - "getCustomAlarmList supports dpId and devId parameters. If not provided, does it query all custom alarms of the current device by default?"
  - "What alarm rule configuration does the AddCustomAlarmOptions parameter of addCustomAlarm need to include?"
  - "setCustomAlarmStatus enables or disables an alarm via bindId and enable. What do the two elements in the return value Promise<[boolean, LinkageRule[]]> represent?"
  - "Does the LinkageRule[] returned after deleteCustomAlarm deletes an alarm rule represent the complete updated list?"
  - "useCustomAlarm only supports single devices, not groups. How should this be handled in a group environment?"
  - "Before using useCustomAlarm, you need to mount SdmProvider and integrate SmartAlarmAbility. Are both required?"
  - "How to use TyList and TySwitch components to display the custom alarm list and control setCustomAlarmStatus via onChange?"
  - "In the LinkageRule type, what do bindId, enable, and triggerRuleVO.name represent?"
  - "What is the difference between useCustomAlarm and useBuiltInAlarm (custom alarms vs built-in alarms)?"
---

<div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
  <span style={{ backgroundColor: '#52c41a', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Device Support</span>
  <span style={{ backgroundColor: '#ff4d4f', color: 'white', padding: '2px 8px', borderRadius: '4px', fontSize: '12px' }}>Group Not Support</span>
</div>

## useCustomAlarm

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

> 💡 Before use, both conditions must be met:
> 1. SdmProvider is mounted in the project
> 2. SmartAlarmAbility is configured during SmartDeviceModel initialization

### Description

Get the device’s custom alarm list and CRUD operations; supports single devices only, not groups

### Parameters

None


### Return Value

Type: `CustomAlarmResult`

Custom alarm data, loading state, and management methods

**`type` CustomAlarmResult**

| Property | Type | Description |
| --- | --- | --- |
| `data` | `CustomAlarmRule[]` | Custom alarm list for the device |
| `loading` | `boolean` | Whether the device’s custom alarm list is loading |
| `getCustomAlarmList` | `(options: GetCustomAlarmListParams) => Promise<CustomAlarmRule[]>` | Query the device’s custom alarm list by device ID |
| `addCustomAlarm` | `(options: AddCustomAlarmOptions) => Promise<[AddCustomAlarmBindResult, CustomAlarmList]>` | Add or edit a custom alarm rule |
| `setCustomAlarmStatus` | `(options: SetCustomAlarmStatusParams) => Promise<[boolean, CustomAlarmList]>` | Enable or disable custom alarm rules |
| `deleteCustomAlarm` | `(options: DeleteCustomAlarmParams) => Promise<[boolean, CustomAlarmList]>` | Delete custom alarm rules |

### Referenced Types

##### `type` CustomAlarmResult

| Property | Type | Description |
| --- | --- | --- |
| `data` | `CustomAlarmRule[]` | Custom alarm list for the device |
| `loading` | `boolean` | Whether the device’s custom alarm list is loading |
| `getCustomAlarmList` | `(options: GetCustomAlarmListParams) => Promise<CustomAlarmRule[]>` | Query the device’s custom alarm list by device ID |
| `addCustomAlarm` | `(options: AddCustomAlarmOptions) => Promise<[AddCustomAlarmBindResult, CustomAlarmList]>` | Add or edit a custom alarm rule |
| `setCustomAlarmStatus` | `(options: SetCustomAlarmStatusParams) => Promise<[boolean, CustomAlarmList]>` | Enable or disable custom alarm rules |
| `deleteCustomAlarm` | `(options: DeleteCustomAlarmParams) => Promise<[boolean, CustomAlarmList]>` | Delete custom alarm rules |

##### `type` AlarmTriggerRuleVO

| Property | Type | Description |
| --- | --- | --- |
| `ownerId` | `string` | Home ID |
| `enabled` | `boolean` | Whether the alarm rule is enabled |
| `id` | `string` | Execution rule ID |
| `name` | `string` | Alarm name or note |
| `preConditions` | `AlarmPreCondition[] \| unknown[]` | Preconditions for executing actions; see AlarmPreCondition |
| `conditions` | `CustomAlarmCondition[] \| unknown[]` | Conditions for executing actions; see CustomAlarmCondition |
| `actions` | `CustomAlarmSceneAction[] \| unknown[]` | Actions to execute; see CustomAlarmSceneAction |

##### `type` CustomAlarmRule

| Property | Type | Description |
| --- | --- | --- |
| `triggerRuleId` | `string` | ID of the rule executed by the alarm |
| `triggerRuleVO` | `AlarmTriggerRuleVO` | Details of the rule that triggers the alarm; see AlarmTriggerRuleVO |
| `bizDomain` | `string` | Business domain identifier, fixed as miniAppPanelSDKAlarm in the alarm SDK |
| `associativeEntityValue` | `string` | Used when associativeEntityId is not sufficient to distinguish cases—for example, when the same DP is used but alarm types must be differentiated. You can use DpValue; generally not required. |
| `sourceEntityId` | `string` | Device ID associated with the current alarm |
| `name` | `string` | Name or note |
| `icon` | `string` | Icon |
| `bindId` | `number` | Binding ID |
| `associativeEntityId` | `string` | DP ID associated with the current alarm |
| `enable` | `boolean` | Whether enabled |

##### `type` Operator

```typescript
type Operator = '==' | '<' | '>' | '<=' | '>=';
```

##### `type` DpValue

Datapoint value type, which can be boolean, number, or string.

```typescript
export type DpValue = boolean | number | string;
```

##### `type` AddCustomAlarmBindResult

| Property | Type | Description |
| --- | --- | --- |
| `associativeEntityValue` | `string` | Associated entity value, used to distinguish alarm types |
| `associativeEntityId` | `string` | Associated entity ID, typically the DP ID |
| `bindId` | `number` | Binding ID |
| `bizDomain` | `string` | Business domain, fixed as miniAppPanelSDKAlarm for alarms |
| `enable` | `boolean` | Whether enabled |
| `sourceEntityId` | `string` | Device ID |

##### `type` CustomAlarmList

```typescript
export type CustomAlarmList = CustomAlarmRule[];
```

##### `type` AlarmPreCondition

| Property | Type | Description |
| --- | --- | --- |
| `expr` | `CustomAlarmPreConditionExpr` | Condition expression |
| `condType` | `"timeCheck"` | Condition type, fixed as timeCheck in the alarm SDK |
| `id` | `string` | Condition ID |

##### `type` CustomAlarmCondition

| Property | Type | Description |
| --- | --- | --- |
| `id` | `string` | Condition ID |
| `ruleId` | `string` | Rule ID |
| `entityId` | `string` | Data ID |
| `entitySubIds` | `string` | Abstract sub-data ID |
| `expr` | `string` | Condition expression |

##### `type` CustomAlarmSceneAction

| Property | Type | Description |
| --- | --- | --- |
| `id` | `string` | Condition ID |
| `ruleId` | `string` | Scene ID |
| `actionExecutor` | `string` | Action type, fixed as appPushTrigger in the alarm SDK |

##### `type` CustomAlarmPreConditionExpr

| Property | Type | Description |
| --- | --- | --- |
| `timeZoneId` | `string` | Time zone ID, e.g., Asia/Shanghai |
| `start` | `string` | Start time in HH:mm, e.g., 00:00 |
| `timeInterval` | `string` | Time interval, fixed as 'custom' |
| `loops` | `string` | Repeat days; '1111111' means all seven days are on, starting from Sunday |
| `end` | `string` | End time in HH:mm, e.g., 23:59 |


### Examples

#### Example

```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 => (
    <Switch key={item.bindId} checked={item.enable} onChange={handleToggle(item)} />
  ));
}
```