M5UI

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

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

M5 系列显示库说明

1. Display (M5.Lcd)

  • 底层图形库，提供屏幕绘制、文字、线条、颜色管理等基础功能。

  • 可独立使用，适合只需要绘制图形或文字的场景。

  • Access via: M5.Lcd.fillRect(), M5.Lcd.drawRect(), M5.Lcd.drawString(), etc.

2. Widgets (M5.Widgets)

  • 基础控件库，提供标签、图片显示等 UI 控件。

  • 底层依赖 M5GFX。

  • 适合需要简单交互控件的界面。

  • Access via: M5.Widgets.Label(), M5.Widgets.Image(), M5.Widgets.Rectangle(), etc.

  • Important: M5.Widgets provides UI component classes, not drawing methods.

3. M5UI

  • 高层 UI 框架，基于 LVGL 封装。

  • 提供页面管理、多控件布局和统一事件处理。

  • Access via: m5ui.M5Label(), m5ui.M5Button(), m5ui.M5Page(), etc.

使用提示

  • ⚠️ 不建议同时混用 M5GFX、M5Widgets、M5UI，可能导致渲染异常或事件冲突。

  • For graphics-only drawing → use M5GFX (M5.Lcd).

  • 简单控件交互 → 使用 M5Widgets。

  • 多页面 UI → 使用 M5UI。

Common Mistakes to Avoid

  • ❌ WRONG: Widgets.fillRect() or Widgets.drawRect() - These methods do not exist in Widgets module

  • ✅ CORRECT: M5.Lcd.fillRect() or M5.Lcd.drawRect() - Use M5.Lcd for drawing methods

  • ❌ WRONG: Mixing M5.Widgets.Rectangle() with m5ui.M5Page() - Different UI systems, don’t mix

  • ✅ CORRECT: Use either M5.Widgets OR m5ui consistently, not both together

Key Distinction: - M5.Lcd = Drawing methods (fillRect, drawRect, drawCircle, drawString, etc.) - M5.Widgets = Simple UI component classes (Label, Image, Rectangle, Circle, etc.) - m5ui = LVGL-based UI framework (M5Label, M5Button, M5Page, M5Chart, etc.)

Available Fonts

Font availability depends on the board firmware build and the UI API you use.

LVGL / m5ui widget fonts

For m5ui widgets, use LVGL font objects such as lv.font_montserrat_*. Most M5Stack firmware builds include these Montserrat fonts:

  • lv.font_montserrat_12 - Extra small text

  • lv.font_montserrat_14 - Default font

  • lv.font_montserrat_16 - Medium text

  • lv.font_montserrat_18 - Medium-large text

  • lv.font_montserrat_24 - Large text

  • lv.font_montserrat_40 - Extra-large text

  • lv.font_montserrat_44 - Extra-large text

  • lv.font_montserrat_48 - Extra-large text

Some builds, such as Tab5, also include lv.font_montserrat_20, lv.font_montserrat_22, lv.font_montserrat_30, and lv.font_montserrat_36.

M5.Lcd / Widgets CJK fonts

For drawing text with M5.Lcd or widgets based on M5.Widgets, use M5.Lcd.FONTS. Most firmware builds also include these 24 px CJK fonts:

  • M5.Lcd.FONTS.AlibabaPuHuiTiCN24 - Simplified Chinese

  • M5.Lcd.FONTS.AlibabaSansJA24 - Japanese

  • M5.Lcd.FONTS.AlibabaSansKR24 - Korean

The older EFontCN24, EFontJA24, and EFontKR24 names are deprecated aliases; prefer the Alibaba* names above. These CJK fonts may be disabled on small-flash or resource-constrained firmware builds.

重要

Do not assume every font is available on every device. If your code may run on multiple boards, use common fonts or check availability before using an optional size/font, for example hasattr(lv, "font_montserrat_20") for LVGL fonts.

Font Selection Guide:

  • m5ui labels/buttons/dropdowns -> lv.font_montserrat_*

  • M5.Lcd.drawString() / M5.Widgets English text -> M5.Lcd.FONTS.Montserrat*

  • M5.Lcd.drawString() / M5.Widgets Chinese/Japanese/Korean text -> M5.Lcd.FONTS.Alibaba*24

Example:

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)

Functions

m5ui.init()

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

返回:

None

m5ui.deinit()

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

返回:

None

Classes