M5UI

M5UI 是一个基于 LVGL v9.3 的 UI 库。它提供了一组用于创建 M5Stack 设备用户界面的小部件和函数。

它已适用于 M5Stack 设备，您只需调用 m5ui.init() 即可开始使用它。

备注

请在调用 m5ui.init() 前设置屏幕旋转方向。更新 M5GFX 后，Core2、CoreS3 和 StackChan 的正常 320 × 240 横屏布局使用 0。其他主机及旧工程的迁移方法见屏幕旋转方向。

支持的主机

当前 UiFlow2 固件在以下 9 款主机上同时启用了 LVGL 和 M5UI：

Core2 (M5STACK_Core2)
CoreS3 (M5STACK_CoreS3)
M5Dial (M5STACK_Dial)
StackChan (M5STACK_StackChan)
StopWatch (M5STACK_StopWatch)
Tab5 (M5STACK_Tab5)
Tab5X (M5STACK_Tab5X；继承 Tab5 的 LVGL 和 M5UI 配置)
Tough (M5STACK_Tough)
ToughC5 (M5STACK_ToughC5)

M5 系列显示库说明

1. Display 底层绘图库（M5.Lcd）

底层图形库，提供屏幕绘制、文字、线条、颜色管理等基础功能。
可独立使用，适合只需要绘制图形或文字的场景。
调用方式：M5.Lcd.fillRect()、M5.Lcd.drawRect()、M5.Lcd.drawString() 等。

2. Widgets 组件库（M5.Widgets）

基础控件库，提供标签、图片显示等 UI 控件。
底层依赖 M5GFX。
适合需要简单交互控件的界面。
调用方式：M5.Widgets.Label()、M5.Widgets.Image()、M5.Widgets.Rectangle() 等。
注意：M5.Widgets 提供 UI 组件类，不提供绘图方法。
建议：新建交互式 UI 项目时优先使用 M5UI/LVGL。M5.Widgets 适用于简单或旧版 UI 组件。

3. M5UI

高层 UI 框架，基于 LVGL 封装。
提供页面管理、多控件布局和统一事件处理。
建议：新建交互式 UI 项目优先使用 M5UI/LVGL。
调用方式：m5ui.M5Label()、m5ui.M5Button()、m5ui.M5Page() 等。

使用提示

⚠️ 不建议同时混用 M5GFX、M5Widgets、M5UI，可能导致渲染异常或事件冲突。
仅需图形绘制 → 使用 M5GFX（M5.Lcd）。
简单控件交互 → 使用 M5Widgets。
多页面 UI → 使用 M5UI/LVGL（新项目推荐）。

常见错误及正确用法

❌ 错误：Widgets.fillRect() 或 Widgets.drawRect()——Widgets 模块中没有这些方法。
✅ 正确：M5.Lcd.fillRect() 或 M5.Lcd.drawRect()——通过 M5.Lcd 调用绘图方法。
❌ 错误：将 M5.Widgets.Rectangle() 与 m5ui.M5Page() 混用——它们属于不同的 UI 系统。
✅ 正确：在同一界面中统一使用 M5.Widgets 或 m5ui，避免混用。

主要区别：- M5.Lcd 提供绘图方法（fillRect、drawRect、drawCircle、drawString 等）；- M5.Widgets 提供简单 UI 组件类（Label、Image、Rectangle、Circle 等）；- m5ui 是基于 LVGL 的 UI 框架（M5Label、M5Button、M5Page、M5Chart 等）。

可用字体

字体是否可用取决于开发板固件构建以及所使用的 UI API。

LVGL / m5ui 控件字体

对于 m5ui 控件，请使用 lv.font_montserrat_* 等 LVGL 字体对象。大多数 M5Stack 固件构建都包含以下 Montserrat 字体：

lv.font_montserrat_12 - 超小文本
lv.font_montserrat_14 - 默认字体
lv.font_montserrat_16 - 中等文本
lv.font_montserrat_18 - 中大文本
lv.font_montserrat_24 - 大文本
lv.font_montserrat_40 - 超大文本
lv.font_montserrat_44 - 超大文本
lv.font_montserrat_48 - 超大文本

部分固件构建（例如 Tab5）还包含 lv.font_montserrat_20、lv.font_montserrat_22、lv.font_montserrat_30 和 lv.font_montserrat_36。

大多数启用 CJK 字体支持的固件构建还会为 m5ui 控件提供以下 24 px LVGL 字体对象：

lv.AlibabaPuHuiTi_CN24 - 简体中文
lv.AlibabaSans_JP24 - 日文
lv.AlibabaSans_KR24 - 韩文

LVGL 与 M5.Lcd.FONTS 使用不同的对象名称。请根据所使用的 UI API 采用上面对应的拼写。

M5.Lcd / Widgets CJK 字体

使用 M5.Lcd 绘制文本或使用基于 M5.Widgets 的控件时，请使用 M5.Lcd.FONTS。大多数固件构建还包含以下 24 px CJK 字体：

M5.Lcd.FONTS.AlibabaPuHuiTiCN24 - 简体中文
M5.Lcd.FONTS.AlibabaSansJA24 - 日文
M5.Lcd.FONTS.AlibabaSansKR24 - 韩文

重要

选择字体前，请先查阅目标主机文档中的支持字体列表。如果文档未提供相关信息，可在运行时检查字体是否可用，例如使用 hasattr(lv, "font_montserrat_20")。

字体选择指南：

m5ui 标签/按钮/下拉列表 -> lv.font_montserrat_*
m5ui 中显示 CJK 文本的控件 -> lv.Alibaba*24
M5.Lcd.drawString() / M5.Widgets 英文文本 -> M5.Lcd.FONTS.Montserrat*
M5.Lcd.drawString() / M5.Widgets 中文/日文/韩文文本 -> M5.Lcd.FONTS.Alibaba*24

示例：

import m5ui
import lvgl as lv

m5ui.init()
page0 = m5ui.M5Page(bg_c=0xFFFFFF)

title = m5ui.M5Label("Title", x=10, y=10, font=lv.font_montserrat_24, parent=page0)
label = m5ui.M5Label("Text", x=10, y=50, font=lv.font_montserrat_14, parent=page0)

optional_font = lv.font_montserrat_20 if hasattr(lv, "font_montserrat_20") else lv.font_montserrat_18
value = m5ui.M5Label("123", x=10, y=80, font=optional_font, parent=page0)

函数

m5ui.init()

初始化 M5UI 库。使用任何其他 M5UI 函数之前必须调用此函数

返回:: None

m5ui.deinit()

取消初始化 M5UI 库。当您不再需要使用 M5UI 时，应调用此函数。

返回:: None