---
title: 连接与离线逻辑
summary: 介绍涂鸦面板设备连接状态与离线逻辑，包括离线遮罩、蓝牙自动重连、权限引导及不同连接方式的判断逻辑。
questions:
- 设备离线时框架自动展示的离线遮罩包含哪些排查引导信息？
- 蓝牙设备离线后框架的自动重连流程是怎样的？
- useDefaultOffline 设置为 false 后如何自行实现离线交互？
- bleCover 参数控制蓝牙连接悬浮窗显示时的什么行为？
- customTop 参数如何适配自定义导航栏的蓝牙悬浮窗位置？
- 蓝牙未授权或未开启时框架会弹出什么引导提示？
- 框架如何实时监测手机端网络环境并自动显示离线遮罩？
- 蓝牙自动重连成功后离线遮罩和连接悬浮窗如何处理？
- Wi-Fi、蓝牙、双模、网关等不同连接方式的离线判断逻辑有何区别？
- 蓝牙重连失败后框架提供了哪些排查建议和引导？
---
# 连接与离线逻辑
## 1. 概述
连接与离线逻辑旨在为用户提供设备连接状态的实时反馈。在涂鸦面板体系中，“离线”是设备无法被控制的状态，而“蓝牙连接/重连”是蓝牙及双模设备在判定离线后，框架自动尝试修复连接的交互过程。
> **提示**：该能力已高度集成。在面板小程序初始化时会自动启动下述逻辑，无需开发者进行任何代码实现。
---
## 2. 逻辑流程图
基础库内置了复杂的离线判断决策树，适配了 Wi-Fi、蓝牙、双模、网关等多种连接方式，如下图所示：
---
## 3. 框架自动化行为
### 3.1 离线遮罩管理
框架会实时监听设备的在线状态。一旦设备判定为离线，面板上方会自动覆盖一层“离线遮罩”，拦截所有业务操作。
* **排查引导**：根据设备类型展示相应的排查建议。
* **网络状态感知**：实时监测手机端网络环境。针对需要联网类的设备，当手机断网时，框架会自动显示离线遮罩。
### 3.2 蓝牙自动重连行为
针对蓝牙（BLE）及双模设备，框架在检测到设备离线后，会自动启动“本地连接恢复”流程。该流程旨在通过手机蓝牙直接与设备建立通信，以实现离线状态下的近端控制。
#### 1. 前置检查与权限引导
在尝试连接前，框架会首先检查必要的通信环境。若环境不满足，将主动弹出引导提示：
* **蓝牙授权检查**：检测 App 是否拥有手机蓝牙使用权限。若未授权，将引导用户前往系统设置开启。
* **蓝牙开关状态**：检测手机系统蓝牙是否已打开。若处于关闭状态，将提醒用户开启蓝牙。
**蓝牙未授权提示**：
**蓝牙未开启提示**：
#### 2. 自动化连接流程
当通信环境就绪后，框架会启动后台静默重连：
* **连接状态反馈**：界面会显示蓝牙连接悬浮窗，告知用户当前的连接进度。
* **自动交互闭环**：若重连成功，离线遮罩与连接悬浮窗将自动消失，恢复面板控制权限。
**蓝牙连接中**：
**连接失败状态**：
#### 3. 失败排查与引导
若在规定时间内重连失败，框架会提供详细的失败原因及排查建议，引导用户通过其他方式（如检查设备供电或重启蓝牙）解决问题。
---
## 4. 常见配置说明
开发者可以通过 `initPanelEnvironment` 的参数微调上述行为：
* **`useDefaultOffline`**: 设置为 `false` 可完全禁用内置离线遮罩，由开发者自行通过状态监听实现 UI。
* **`bleCover`**: 当显示蓝牙连接悬浮窗时，是否要添加覆盖层以阻止界面交互。
* **`customTop`**: 适配自定义导航栏，调整蓝牙悬浮窗的顶部距离。
---
## 5. 注意事项
1. **功能标准化**：该离线机制属于基础库内置的统一标准能力，旨在确保所有面板应用在处理设备离线与异常交互上保持高度一致。**非必要场景建议开发者不要自行调整实现**。
2. **自定义支持**：若在特殊业务场景下需要完全自定义离线交互，开发者可通过配置 `useDefaultOffline: false` 来禁用内置离线逻辑，随后自行监听设备状态并实现交互视图。
3. **交互闭环**：在内置模式下，离线页面的所有跳转链路（如配网引导、重连页）均由框架内部闭环处理，开发者无需关注跳转协议与页面实现。