---
title: 面板环境初始化
summary: 介绍 initPanelEnvironment 面板环境初始化 API 的用法、配置选项及集成的离线、OTA、蓝牙等标准能力。
questions:
  - initPanelEnvironment 支持哪些初始化配置选项？
  - 如何通过 useDefaultOffline 参数开启默认离线弹窗？
  - bleConnectType 的三种蓝牙连接方式（0/1/2）分别代表什么？
  - showFault 参数开启后如何自动展示设备故障列表？
  - initPanelEnvironment 需要引入哪个依赖包以及最低版本要求是多少？
  - bleCover 参数如何控制蓝牙状态悬浮窗的交互覆盖层？
  - customTop 参数接受什么格式的值来调整蓝牙悬浮窗顶部距离？
  - shouldConnectBleAuto 和 disableOtaDialog 参数分别控制什么行为？
  - initPanelEnvironment 基于哪些底层原子 API 封装实现？
  - 连云激活功能在设备进入面板后是如何自动触发的？
---

# 面板环境初始化

`initPanelEnvironment` 是涂鸦面板小程序的**标准环境初始化工具**。它不仅是一个 API，更是涂鸦面板标准交互规范的集成实现。通过一键调用，开发者可以快速为面板接入离线、蓝牙、OTA、故障提醒等一系列标准化能力。

<Callout type="info">
  需引入 `DeviceKit`，且 `@ray-js/ray` 版本需高于 `0.10.3`。
</Callout>

## 快速上手

在应用入口或面板主页面尽早调用即可开启标准环境（当前面板小程序模板均已内置调用此 API）：

```typescript
import { initPanelEnvironment } from '@ray-js/ray';

// 开启标准环境初始化
initPanelEnvironment({ 
  useDefaultOffline: true, // 开启默认离线提醒
});
```

---

## 核心能力

初始化面板环境 API 深度集成了以下标准交互能力：

### 1. 连接与离线保障
实时监测设备在线状态。针对 Wi-Fi 设备提供离线遮罩引导；针对蓝牙设备提供自动重连、权限检测及状态悬浮窗展示。

> **详情查阅**：[连接与离线逻辑说明](./connectivity)

### 2. OTA 升级检查
实时检测设备固件更新情况，并根据优先级（强制/提醒）引导用户进行升级。

> **详情查阅**：[OTA 升级机制说明](./ota)

### 3. 连云激活与设备监听
- **连云激活**：对于需要激活的设备，进入面板后自动弹出提示。
- **基础监听**：自动注册设备移除、状态变更等基础监听，简化业务复杂度。

<Image src="/images/panel/panel-plug-play.png" style={{ width: '375px' }} />

### 4. 故障列表组件
当设备支持并上报 `fault` 类型的功能点时，自动弹出标准故障列表说明。目前仅支持 `dpCode` 为 `fault` 的功能点。

<Image src="/images/panel/panel-fault-show.png" style={{ width: '375px' }} />

---

## 技术参考

### 类型定义

```typescript
/**
 * 面板环境初始化参数
 */
export interface InitPanelEnvironmentOptions {
  /**
   * @description 是否需要使用默认离线弹窗
   * @default true
   */
  useDefaultOffline?: boolean;
  /**
   * @description 蓝牙提示是否需要阻止交互
   * @default false
   */
  bleCover?: boolean;
  /**
   * @description 蓝牙及 toast 提示自定义顶部高度（自定义导航时使用）
   * @default 0
   */
  customTop?: string;
  /**
   * @description 蓝牙连接方式，默认0
   * 0： 网关和app都需要，本地和网关两个途径任何一个可用均可生效
   * 1： 仅 app， 只会判定本地是否在线， 以及本地连接是否成功
   * 2： 仅网关连接， 只会判定网关是否在线，以及网关连接是否成功
   * @default 0
   */
  bleConnectType?: number;
  /**
   * @description 是否显示蓝牙连接状态提示
   * @default true
   * @version 2.10.4
   */
  showBLEToast?: boolean;
  /**
   * @description 当前设备 id，默认为 undefined，表示自动从小程序的 query参数中获取
   * @default undefined
   */
  deviceId?: string;
  /**
   * @description 当前群组 id，默认为 undefined，表示自动从小程序的 query参数中获取
   * @default undefined
   */
  groupId?: string;
  /**
   * @description 微信详细页面路由
   * @default undefined
   */
  deviceDetailPage?: string;
  /**
   * @description 是否显示故障提示
   * @default false
   */
  showFault?: boolean;
  /**
   * @description 配置是否自动连接蓝牙，基础库 2.27.0 开始支持
   * @default true
   */
  shouldConnectBleAuto?: boolean;
  /**
   * @description 自动检查激活，基础库 2.27.0 开始支持
   * @default true
   */
  autoCheckActivation?: boolean;
  /**
   * @description 禁用自动检查固件升级，基础库 2.27.0 开始支持
   * @default false
   */
  disableOtaDialog?: boolean;
}

export declare function initPanelEnvironment(
  options?: InitPanelEnvironmentOptions,
): void;
```

---

### 参数详解

#### bleCover
当显示蓝牙状态悬浮窗时，是否要添加覆盖层以阻止界面交互。通常情况下，如果有些功能可以在设备离线时使用（如：数据图表查看），则不需要覆盖住界面。

```typescript | pure
initPanelEnvironment({ useDefaultOffline: true, bleCover: true });
```

<Image src="/images/panel/panel-ble-cover.jpeg" style={{ width: '375px' }} />

#### customTop
当使用自定义状态栏时，可通过该属性自定义蓝牙状态悬浮窗与顶部的距离。该参数接受 CSS 标准长度值（如: '100px', '10%'等）。

```typescript | pure
initPanelEnvironment({ useDefaultOffline: true, customTop: '120px' });
```

<Image src="/images/panel/panel-custom-top.jpeg" style={{ width: '375px' }} />

#### bleConnectType

在标准逻辑下，蓝牙设备的联网方式选择：
- **0**：同时尝试手机直连和连接网关（默认）。
- **1**：仅使用手机直连。
- **2**：仅使用网关连接。

#### showBLEToast
在蓝牙设备连接成功或失败时，是否显示 Toast 提示。

```typescript | pure
initPanelEnvironment({ useDefaultOffline: true, showBLEToast: true });
```

<Image src="/images/panel/panel-show-ble-toast.jpeg" style={{ width: '375px' }} />

#### showFault
若设置为 `true`，则使用内置能力展示设备故障。目前仅支持 `dpCode` 为 `fault` 的故障展示。

```typescript | pure
initPanelEnvironment({ useDefaultOffline: true, showFault: true });
```


### 底层原子实现
`initPanelEnvironment` 基于以下底层 API 深度封装后实现：

- [ty.panel.initPanelKit](/cn/miniapp/develop/ray/api/other/initPanelKit)
- [registerDeviceListListener](/cn/miniapp/develop/ray/api/device-info/info/registerDeviceListListener)
- [getDeviceInfo](/cn/miniapp/develop/ray/api/device-info/info/getDeviceInfo)
- [getSystemInfoSync](/cn/miniapp/develop/ray/api/base/system/getSystemInfoSync)
- [authorizeStatus](/cn/miniapp/develop/ray/api/authorize/authorizeStatus)
- [openMiniWidget](/cn/miniapp/develop/ray/api/base/container/MiniWidgetDialog#miniwidgetdialog-openminiwidget)
- [onWidgetDismiss](/cn/miniapp/develop/ray/api/base/container/MiniWidgetDialog#miniwidgetdialogonwidgetdismiss)
- [offWidgetDismiss](/cn/miniapp/develop/ray/api/base/container/MiniWidgetDialog#miniwidgetdialogoffwidgetdismiss)
- [dismissMiniWidget](/cn/miniapp/develop/ray/api/base/container/MiniWidgetDialog#miniwidgetdialogdismissminiwidget)
- [authorize](/cn/miniapp/develop/ray/api/authorize/authorizeStatus)
- [getDeviceOnlineType](/cn/miniapp/develop/ray/api/device-info/info/getDeviceOnlineType)
- [connectBluetoothDevice](/cn/miniapp/develop/ray/api/bluetooth/single/connectBluetoothDevice)
- [subscribeBLEConnectStatus](/cn/miniapp/develop/ray/api/bluetooth/single/subscribeBLEConnectStatus)
- [onBLEConnectStatusChange](/cn/miniapp/develop/ray/api/bluetooth/single/onBLEConnectStatusChange)
- [onBluetoothAdapterStateChange](/cn/miniapp/solution-panel/ability/common/sdm/api/onBluetoothAdapterStateChange)

---

## 注意事项

1. **标准化逻辑建议**：`initPanelEnvironment` 提供的逻辑均为涂鸦面板的标准规范，我们建议开发者优先使用本接口，仅在特殊场景下才参考原子接口进行自定义。
2. **OTA 逻辑封闭性**：OTA 升级机制（检测、弹窗及跳转）目前暂不支持开发者自定义实现，请务必通过内置能力完成。