[English](./README.md) | 简体中文

# @ray/light-dp-bind-functional-utils 开发文档

## 配置

1. 配置功能页的路由信息。

- ray 框架

```typescript
export const thing = {
  window: {
    backgroundColor: '#f2f4f6',
    navigationBarTitleText: '',
    navigationBarBackgroundColor: '#f2f4f6',
    navigationBarTextStyle: 'black',
  },
  darkmode: false,
  functionalPages: {
    settings: {
      // 设备详情页
      appid: 'tycryc71qaug8at6yt',
      entryCode: 'entrye0n05idydmmfv',
    },
    details: {
      // DP同步设备绑定功能页
      appid: 'tyavb2zybiicrluxwk',
      entryCode: 'entryeo3eejedwj6sw',
    },
  },
};
```

- 原生小程序

```json
{
  ...
  "functionalPages": {
    "settings": {
      "appid": "tycryc71qaug8at6yt",
      "entryCode": "entrye0n05idydmmfv"
    },
    "details": {
      "appid": "tyavb2zybiicrluxwk",
      "entryCode": "entryeo3eejedwj6sw",
    }
  },
  ...
}
```

## 常量

### `BIND_TYPE`

绑定类型枚举，常用于 `openDeviceOrDimmingSelect` 等接口的参数。

| 键                   | 值  | 说明                           |
|----------------------|-----|--------------------------------|
| sceneControl         | 1   | 场景控制（走联动接口）         |
| sceneDimming         | 2   | 场景调光                       |
| lightControl         | 3   | 灯光控制                       |
| curtainControl       | 4   | 窗帘控制                       |
| airConditionerControl| 5   | 空调控制                       |
| tvControl            | 6   | 电视控制                       |
| virtualControl       | 7   | 非智能灯                       |
| musicControl         | 8   | 音乐控制                       |
| voiceCentralControl  | 9   | 语音中控                       |
| distributeBle        | 10  | 分布式蓝牙                     |
| bleDimming           | 11  | 蓝牙调光                       |
| bleLight             | 12  | 蓝牙灯                         |
| bleCurtain           | 13  | 蓝牙窗帘                       |
| distributeBleDouble  | 18  | 分布式蓝牙灯光场景-双状态       |
| bleLightNegation     | 19  | 蓝牙SoC方案的灯具控制-取反      |
| bleVirtualControl    | 23  | 蓝牙虚拟设备                   |

---

## API 列表

### 获取场景列表

#### `getSceneList(params): Promise<{result: Array<any>}>`

获取可绑定的场景列表。

**参数：**

- `roomId: string` 房间ID
- `masterDpId: number` 主控设备DPID
- `masterDevId: string` 主控设备ID
- `bindType?: number` 绑定类型

---

### 获取灯光/联动/调光列表

#### `getLightAndLinkage(params: GETSceneListParams): Promise<GETSceneListResult>`

根据场景列表筛选出灯光、联动、调光。

---

### 获取指定 dp 点可用的功能列表

#### `getAvailableFunction(params: { masterDevId: string; masterDpIds: string; }): Promise<{ result: Array<any> }>`

获取哪些功能可用

**参数：**

- `masterDevId: string` 主控设备ID
- `masterDpIds?: string` 主控设备DPID，多个以英文逗号隔开

**返回值：**

- `result` 可用的功能列表, 如：[1,2,3,4,5]

#### `getAvailableFunctionList(params: { masterDevId: string; masterDpIds: string; }): Promise<Array<SceneItem>>`

获取可用功能列表，与本地配置合并

**参数：**

- `masterDevId: string` 主控设备ID
- `masterDpIds?: string` 主控设备DPID，多个以英文逗号隔开

**返回值：**

- `result` 可用的功能列表, 如：

```json
[
  {
    "title": "绑定常规场景",
    "desc": "完成“普通场景”绑定以后，单击按键可以执行相应的场景。",
    "tip": "（单状态）",
    "icon": "/_assets/mode_scene-ADC62VSZ.png",
    "nextPage": "/pages/sceneSelection/index?type=1",
    "isBindDevice": false,
    "showNoRoom": {
        "isSupport": true,
        "notSupport": true
    }
},
{
    "title": "绑定蓝牙分布式场景",
    "desc": "完成“常规场景（单状态）”绑定以后，单击按键可以执行相应的场景。",
    "tip": "（单状态）",
    "icon": "/_assets/mode_scene-ADC62VSZ.png",
    "bindType": 10,
    "nextPage": "/pages/deviceSelection/index?type=10",
    "isBindDevice": false,
    "showNoRoom": {
        "isSupport": true,
        "notSupport": false
    }
}
]
```

---

### 获取绑定信息

#### `getBindInfo(params: { masterDevId: string; masterDpIds: string; }): Promise<{ result: Array<any> }>`

获取绑定信息

**参数：**

- `masterDevId: string` 主控设备ID
- `masterDpIds?: string` 主控设备DPID，多个以英文逗号隔开

**返回值：**

- `result` 绑定信息列表, 如：

```json
[
{
    "bindStatus": 2,
    "bindType": 1,
    "masterDevId": "vdevo174789587785064",
    "masterDpId": 1,
    "slaveBizIcon": "https://images.tuyacn.com/smart/rule/glyphicons/label.png",
    "slaveBizIconId": 25,
    "slaveBizId": "S5rKLicwZjLM9cEq",
    "slaveBizName": "\"测试\" 剩余可用电量清零:清零关",
    "slaveBizType": 8
}
]
```

---

### 查询主控设备是否可以创建群组（继电器）

#### `checkGroupCreatable(ids: string, devId?: string): Promise<any>`

- `ids` 主控设备的 DPID, 多个以英文逗号隔开
- `devId` 主控设备ID（可选）

---

### 打开设备选择或调光选择

#### `openDeviceOrDimmingSelect(params: DeviceSelectParams): Promise<void>`

**参数结构：**

```ts
{
  type: BIND_TYPE[keyof typeof BIND_TYPE]; // 绑定类型
  buttonId: string; // 按键ID
  dpId: number; // DPID
  code: string; // 设备code
  homeId?: number; // 家庭ID（可选，未传会自动获取）
  preset?: Record<string, any>; // 预设内容（可选）
}
```

---

### 打开场景选择（一键执行）

#### `openSceneSelect(params: SceneSelectParams): Promise<void>`

**参数结构同上，去掉 type 字段。**

---

### 绑定或查看虚拟设备详情

#### `openVirtualDeviceBind(params: VirtualDeviceBindParams): Promise<void>`

**参数结构：**

```ts
{
  buttonId: string;
  dpId: number;
  code: string;
  homeId?: number;
  groupExecuteDpId?: number; // 群组执行dpId
  bindRule?: any; // 绑定规则
  preset?: Record<string, any>;
}
```

---

### 打开绑定详情（除虚拟设备外）

#### `openBindDetail(params: BindDetailParams): Promise<void>`

**参数结构：**

```ts
{
  buttonId: string;
  dpId: number;
  code: string;
  homeId?: number;
  bindRule?: any;
  preset?: Record<string, any>;
}
```

---

### 打开继电器配置页面（单独配置所有继电器的页面）

#### `openRelayConfig(params?: RelayConfigParams): Promise<void>`

**参数结构：**

```ts
{
  homeId?: number | string; // 家庭ID（可选，未传会自动获取）
}
```

---

### 打开睡眠模式配置页面

#### `openSleepModeConfig(params?: SleepModeConfigParams): Promise<void>`

**参数结构：**

```ts
{
  homeId?: number | string; // 家庭ID（可选，未传会自动获取）
}
```

---

## 预设参数说明

所有 `openXXX` 方法均支持 `preset` 参数，可用于预设内容。例如：

```ts
openDeviceOrDimmingSelect({
  ...,
  preset: {
    actions: {
      '1': { icon: require('@/res/button.png'), title: '灯光1', desc: '描述1' },
    }
  }
})
```

---

## 相关文件

- index.ts
- api.ts
- interface.d.ts

如需详细类型定义，请参考 interface.d.ts。