本页目录
快速上手核心能力1. 连接与离线保障2. OTA 升级检查3. 连云激活与设备监听4. 故障列表组件技术参考类型定义参数详解bleCovercustomTopbleConnectTypeshowBLEToastshowFault底层原子实现注意事项

面板环境初始化

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

Info

需引入 DeviceKit，且 @ray-js/ray 版本需高于 0.10.3。

快速上手

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

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

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

核心能力

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

1. 连接与离线保障

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

详情查阅：连接与离线逻辑说明

2. OTA 升级检查

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

详情查阅：OTA 升级机制说明

3. 连云激活与设备监听

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

4. 故障列表组件

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

技术参考

类型定义

/**
 * 面板环境初始化参数
 */
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

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

initPanelEnvironment({ useDefaultOffline: true, bleCover: true });

customTop

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

initPanelEnvironment({ useDefaultOffline: true, customTop: '120px' });

bleConnectType

在标准逻辑下，蓝牙设备的联网方式选择：

  • 0：同时尝试手机直连和连接网关（默认）。
  • 1：仅使用手机直连。
  • 2：仅使用网关连接。

showBLEToast

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

initPanelEnvironment({ useDefaultOffline: true, showBLEToast: true });

showFault

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

initPanelEnvironment({ useDefaultOffline: true, showFault: true });

底层原子实现

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

注意事项

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