BeShell 文档

简体中文

English

简体中文

English

外观

模块: LVGL (图形界面库)

约 2103 字大约 7 分钟

2026-09-06

构建固件和导入到JS

额外组件

该功能需要安装 beshell-lvgl 组件才能使用。

安装方法：

  1. 编辑项目根目录下的 idf_component.yml 文件，添加依赖：
dependencies:
  become-cool/beshell-lvgl: '>=1.0.2'
  1. 或在 ESP-IDF 环境的命令行中执行：
idf.py add-dependency "become-cool/beshell-lvgl>=1.0.2"

在 C++ 里加入以下代码, 然后重新编译构建固件：

// 为了控制固件的尺寸，BeShell 的 module 是按需引入的。
beshell.use<be::lv::LV>() ;

在JS中导入 lv module：

在.js文件中
import * as lv from 'lv'

简介

LVGL 图形界面库

基于 LVGL 9.0 的 GUI 模块，提供完整的控件体系和样式、事件、动画能力。

使用流程

  1. C++ 侧 beshell.use<be::lv::LV>() 引入模块并重新编译固件
  2. JS 侧创建屏幕驱动对象（如 ST7789 等），调用 lv.registerDisplay(driver) 注册为 LVGL 屏幕
  3. （可选）调用 lv.registerInputDevice(driver) 注册触摸等输入设备
  4. 创建控件构建界面

示例：

import * as lv from "lv"

// driver 由具体的屏幕驱动模块创建
lv.registerDisplay(driver)

// 在屏幕上创建控件
const btn = new lv.Btn(lv.screen())
btn.center()
const label = new lv.Label(btn)
label.text = "Hello LVGL"

导出成员

  • 控件类：Obj 是所有控件的基类，其余控件（Btn、Label、Slider 等）均继承自它
  • Style 样式类、Animation 动画类
  • 扩展控件：Row、Column、Rect、ColorPicker
  • 模块函数：屏幕/输入设备注册、字体加载、颜色转换等

模块函数

函数 screen

原型: screen ()

返回当前激活的 屏幕对象

屏幕对象 是指当前显示在屏幕上的对象，是所有可见组件的根节点，自身没有父节对象。

返回值:

类型Obj

说明当前激活的屏幕对象

函数 load

原型: load (obj:Obj)

将参数指定的对象作为 屏幕对象 加载到当前显示器上

加载成功后，传入对象的父对象会被设置为 null

参数:

  • obj

    类型Obj

    参数说明要加载的屏幕对象

返回值:

类型undefined

函数 pct

原型: pct (value:number)

将 0-100 范围的整数转换为能够表示百分比的 16位整数值

改数值是 lvgl 内部使用的格式

参数:

  • value

    类型number

    参数说明0-100范围的整数

返回值:

类型number

函数 unuseFont

原型: unuseFont ()

禁用字体功能

调用后 Label 的 font 属性设置将不再生效，用于精简固件或排查字体相关问题。

返回值:

类型undefined

函数 unuseImg

原型: unuseImg (name:string="*")

禁用内置图片或移除指定的内置图片

不传参数时禁用全部内置图片功能；传入名称时仅移除该名称对应的内置图片。

参数:

  • name

    类型string

    默认值"*"

    参数说明内置图片名称，默认为 "*" 表示全部

返回值:

类型undefined

函数 RGB

原型: RGB (r:number, g:number, b:number)

将 r/g/b 三个颜色分量合成为颜色值

合成格式与屏幕驱动的色深配置一致（通常为 RGB565）。

参数:

  • r

    类型number

    参数说明红色分量（0-255）

  • g

    类型number

    参数说明绿色分量（0-255）

  • b

    类型number

    参数说明蓝色分量（0-255）

返回值:

类型number

说明颜色值

函数 RGB565

原型: RGB565 (r:number, g:number, b:number)

将 r/g/b 三个颜色分量合成为 RGB565 格式的颜色值

参数:

  • r

    类型number

    参数说明红色分量（0-255）

  • g

    类型number

    参数说明绿色分量（0-255）

  • b

    类型number

    参数说明蓝色分量（0-255）

返回值:

类型number

说明RGB565 颜色值（16 位整数）

函数 registerDisplay

原型: registerDisplay (driver:Display, options:object)

将传入的屏幕驱动对象注册为 lv 的屏幕

参数:

  • driver

    类型Display

    参数说明屏幕驱动对象

  • options

    类型object (详见下方类型定义)

    参数说明可选配置

    options 类型定义：

    {
    renderMode?: number,    // LVGL 渲染模式：0=部分刷新(PARTIAL，默认)，1=全量刷新(FULL)，2=直接模式(DIRECT)
}

异常:

  • 屏幕已注册过
  • 渲染模式无效
  • 创建显存缓冲区失败

返回值:

类型undefined

函数 loadFont

原型: loadFont (name:string, path:string)

从文件系统加载字体文件并注册为指定名称的字体

字体文件需为 LVGL 二进制字体格式（binfont，可由 LVGL 在线字体转换工具生成）。 加载成功后，可通过 Label 的 font 属性使用该字体。

示例：

import * as lv from "lv"

lv.loadFont("myfont", "/fs/myfont.bin")

const label = new lv.Label(lv.screen())
label.font = "myfont"

参数:

  • name

    类型string

    参数说明字体名称，供 Label 的 font 属性引用

  • path

    类型string

    参数说明字体文件路径

返回值:

类型bool

说明是否加载成功

函数 registerInputDevice

原型: registerInputDevice (driver:object, options:object)

将一个输入设备的驱动对象注册为 lv 的输入设备

参数:

  • driver

    类型object

    参数说明输入设备驱动对象（指针类型，如触摸屏驱动）

  • options

    类型object (详见下方类型定义)

    参数说明可选配置

    options 类型定义：

    {
    gesture_limit?: number,           // 判定为手势的最小位移（像素），默认 20
    gesture_min_velocity?: number     // 判定为手势的最小速度，默认 3
}

异常:

  • 输入设备已注册过

返回值:

类型undefined

函数 disableAllInDev

原型: disableAllInDev ()

禁用所有的输入设备，可用于锁定系统

返回值:

类型undefined

函数 enableAllInDev

原型: enableAllInDev ()

恢复输入设备

恢复被 disableAllInDev() 禁用的全部输入设备。

返回值:

类型undefined