---
title: 开锁方式管理
summary: 门锁开锁方式管理，支持指纹、卡片、人脸等添加、绑定、删除及未绑定开锁方式的关联流程。
---

## 开锁方式管理

支持的开锁方式有：指纹、卡片、人脸、指静脉、掌静脉、虹膜。

> 注意：人脸是否支持多个由设备决定，当为支持单个人脸时，在添加人脸时，应该在设备侧做覆盖操作。

### 添加密码

可直接使用 api [addPassword](/cn/miniapp/develop/ray/api/doorlock/unlock-method/addPassword) 进行添加。

### 添加其他开锁方式

其他的开锁方式添加需要使用以下流程

```mermaid
sequenceDiagram
    participant 面板
    participant 设备
    面板->>面板: 进入添加页面
    Note right of 面板: 调用 onAddUnlockMethod <br/>注册监听步骤及结果事件
    面板->>面板: 调用 startAddUnlockMethod
    面板->>设备: 开始录入
    Note right of 面板: 展示添加中
    设备->>面板: 上报录入步骤
    Note right of 面板: onAddUnlockMethod 收到步骤上报<br/>展示步骤
    面板->>面板: 退出页面
    Note left of 面板: 在录入中退出<br/>调用 offAddUnlockMethod 注销监听步骤及结果事件<br/>调用 cancelAddUnlockMethod 取消录入
    设备->>面板: 上报录入结果
    Note right of 面板: onAddUnlockMethod 收到结果<br/>展示录入成功或失败<br/>如果成功，可调用 updateUnlockMethod 更新名称及特殊信息
    面板->>面板: 退出页面
    Note right of 面板: 调用 offAddUnlockMethod <br/>注销监听步骤及结果事件

```

说明

> - `onAddUnlockMethod` 和 `startAddUnlockMethod` API 的可以不同步调用，但如果在多个页面中分开调用这两个 API时，请确保用户在锁上操作录入步骤时，面板已经调用 `onAddUnlockMethod` 监听录入状态。
> - 在录入中途，需要注意用户操作退出录入的情况，此时需要调用 `cancelAddUnlockMethod`。
> - 当录入有结果（成功或失败）时，退出添加页面，请调用 `offAddUnlockMethod`，确保不重复监听，确保程序正常执行。
> - 如果录入失败的原因为超时时（错误码 1002），请在退出页面时，调用 `cancelAddUnlockMethod`, 确保面板超时但锁仍在添加状态的情况。

### 绑定未关联在开锁方式

未关联的开锁方式有两个种情况：

- 在日志列表中返回的开锁记录中，可能会出现未关联的开锁方式，需要调用 `bindUnlockMethodFromLog` 进行关联绑定；
- 通过 `getUnbindUnlockMethods` 获取的列表数据，需要调用 `bindUnlockMethod` 进行关联绑定。

日志中关联绑定流程

```mermaid
sequenceDiagram
participant 面板
participant 云端
面板->>云端: 获取日志列表
云端->>面板: 返回日志列表
面板->>面板: 选择关联开锁方式
面板->>云端: 获取家庭列表
云端->>面板: 返回家庭列表
面板->>面板: 选择绑定用户
面板->>云端: 关联绑定
云端->>面板: 关联绑定成功
```

通过未关联列表进行关联

```mermaid
sequenceDiagram
participant 面板
participant 云端
面板->>云端: 获取未关联列表
云端->>面板: 返回列表
面板->>面板: 选择关联开锁方式
面板->>云端: 获取家庭列表
云端->>面板: 返回家庭列表
面板->>面板: 选择绑定用户
面板->>云端: 关联绑定
云端->>面板: 关联绑定成功
```

### 向设备发起同步开锁方式指令

- SDK 在初始化时，会尝试向设备发起同步开锁方式指令；
- 开发者可能通过调用 `syncUnlockMethod` 手动向设备发起同步开锁方式指令。

### API

#### 添加密码

- 含义：为家庭成员添加密码开锁方式
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/addPassword)

#### 开始添加开锁方式

- 含义：向设备发起开始添加指令，并等待设备上报状态。
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/startAddUnlockMethod)

#### 取消添加开锁方式

- 含义：在录入开锁方式过程中，可以调用 API 取消开锁方式
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/cancelAddUnlockMethod)

#### 注册开锁方式步骤监听器

- 含义：当用户在锁侧录入开锁方式过程中，产生的步骤数据会通过监听器的回调函数推送消息。
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/onAddUnlockMethod)

#### 注销开锁方式步骤监听器

- 含义：取消监听开锁方式的过程
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/offAddUnlockMethod)

#### 发送手机验证码

- 含义：当在更新开锁方式为特殊开锁方式时，如需要添加手机短信通知的，则需要获取验证码
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/sendVerifyCode)

#### 检查是否支持短信通知

- 含义：在特殊开锁方式时，检测是否支持短信通知服务
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/checkSpecialSupportPhone)

#### 更新开锁方式

- 含义：更新已有的开锁方式信息，仅支持更新开锁方式名称和特殊开锁方式的通知信息
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/updateUnlockMethod)

#### 删除开锁方式

- 含义：删除通用面板添加的用户所拥有的开锁方式
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/deleteUnlockMethod)

#### 获取开锁方式详细信息

- 含义：获取某个开锁方式的详细信息，可用于编辑开锁方式时展示信息
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/getUnlockMethodDetail)

#### 检测是否有未绑定的开锁方式

- 含义：检测当前锁侧所有的开锁方式是否有未关联到用户的情况
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/checkUnBindUnlockMethods)

#### 获取未关联开锁方式列表

- 含义：获取锁本地未关联到用户的开锁方式
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/getUnbindUnlockMethods)

#### 同步开锁方式

- 含义：向设备发起同步开锁方式数据到云端
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/syncUnlockMethod)

#### 解绑开锁方式

- 含义：将通过关联操作绑定到用户的开锁方式解绑，解绑后，开锁方式在锁端仍有效
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/unbindUnlockMethod)

#### 绑定开锁方式

- 含义：绑定未关联开锁方式到用户
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/bindUnlockMethod)

#### 绑定开锁方式

- 含义：绑定未关联开锁方式到用户
- 详细：[查看文档](/cn/miniapp/develop/ray/api/doorlock/unlock-method/bindUnlockMethod)

## 常见问题

### Q1: 添加开锁方式时如何显示进度？

**A:** 通过监听 `onAddUnlockMethod` 事件，当 `stage` 为 `'step'` 时，可以获取当前步骤和总步骤：

```typescript
onAddUnlockMethod((event) => {
  if (event.stage === 'step') {
    console.log(`步骤 ${event.step}/${event.total}`);
  }
});
```

### Q2: 如何取消正在添加的开锁方式？

**A:** 调用 `cancelAddUnlockMethod` API：

```typescript
await cancelAddUnlockMethod({ type: 'finger', userId: 'userId' });
```

### Q3: 什么是特殊开锁方式？

**A:** 特殊开锁方式是指配置了通知功能的开锁方式，当使用该开锁方式开锁时，会发送App通知或短信通知。仅指纹、密码等部分开锁方式支持特殊配置。

### Q4: 如何开启短信通知？

**A:** 需要：

1. 检查设备是否支持：`checkSpecialSupportPhone()`
2. 发送验证码：`sendVerifyCode({ account: '86-13800138000' })`
3. 添加时传入验证码和手机号

### Q5: 添加失败的错误码含义？

**A:** 常见错误码：

- `1015-1025`: 各种添加失败原因（如指纹已满、录入超时等）
- `1026`: 添加被取消
- `1014`: 设备不支持该开锁方式

### Q6: 用户拥有的开锁方式都能删除吗？

**A:** 不能，通过关联绑定到用户的开锁方式不能删除，但可以调用 `unbindUnlockMethod` 取消绑定。

### Q7: 如何判断开锁方式是通过关联绑定的？

**A:** 通过 `getUnlockMethodDetail` 获取详情，`isBound` 字段表示是否已绑定。

### Q8: 未绑定的开锁方式如何处理？

**A:** 可以通过 `getUnbindUnlockMethods` 获取列表，然后使用 `bindUnlockMethod` 绑定到用户。