CrabUI入门教程

文章中的新版指2025.10.6之后的框架，旧版指2025.10.6之前的框架

硬件配置

我的硬件配置:

  • Esp32NodeMCU
  • 内存: 166kb
  • 储存: 2mb
  • 主频: 最高240MHz
  • SSD1306
  • 尺寸: 128x64 / 128x32
  • iic: 约60fps
  • spi: 约90fps

安装模块

下载项目中的CrabUI文件夹，并将文件放入Micropython设备中

Micropython设备/
|- CrabUI/
`--`- ...

上传依赖

如果你仔细观察，会发现在配置文件(config.py)中指定了字体文件(files/output.bmf)，这里的字体文件是由大佬@AntonVanke制作的ufont项目中使用的（其实CrabUI的字体渲染就是在ufont的基础上重构优化而来的）

为了使ui框架能够正常运行，需要上传字体、图片等素材

若使用默认的配置文件，字体文件需要放在micropython设备的/files目录下

将项目examples文件夹中的files文件夹上传至micropython设备:

Micropython设备/
|- CrabUI/
|- files/
|  |- a.pbm
|  |- b.pbm
`--`- output.bmf

如果你想要自定义字体文件，可以看看 MicroPython-uFont-Tools

配置文件

配置文件(config.py)中定义了CrabUI的行为

在使用前请修改配置文件：
1. 将屏幕的宽高改为你屏幕的宽高（单位：像素）
2. 将selector_fill（填充选择器）设为False
3. 如果使用的是较旧版本(2025.10.6之前的版本)，请在配置文件中按照自己的实际情况修改引脚配置

新版使用说明

如果使用较新的版本(2025.10.6之后的版本)，请在您的项目中手动指定显示器并手动绑定按钮事件，详见如下：

1. 在您的项目中导入并初始化屏幕的驱动程序，如（此处仅为示例）:

import ssh1106
from machine import SPI, Pin

# 根据实际情况修改引脚内容
spi = SPI(1, mosi=Pin(13), miso=Pin(12), sck=Pin(14), baudrate=30_000_000)
display = ssh1106.SSH1106_SPI(128, 64, spi, Pin(16), Pin(17), Pin(18), 180)
  1. 在初始化ui.Manager后，手动绑定按钮事件
...
manager = ui.Manager()
btn_evnet = manager.btn_event
# 这里的数字是按钮的引脚号
btn_evnet.add(35, manager.up)    # 向上的按钮
btn_evnet.add(34, manager.down)  # 向下的按钮
btn_evnet.add(39, manager.yes)   # 确认的按钮
btn_evnet.add(36, manager.back)  # 返回的按钮

最简示例

如果你想运行直接可用的示例代码文件，见examples中的new_demo.py（新版）或old_demo.py(旧版)

如果你想要自己编写代码，参阅如下：

在Micropython设备中新建demo0.py

Micropython设备/
|- CrabUI/
|- files/
`- demo0.py

在文件中导入CrabUI:

import CrabUI as ui
import oled  # 你的oled屏幕驱动模块

初始化Manager:

方式1(自动初始化屏幕，仅旧版):

manager = ui.Manager(oled)  # oled就是上面导入的驱动

方式2(手动初始化屏幕):

# 初始化你的屏幕驱动程序
display = oled.DisplaySPI(...)  # 此处仅为示例，省略参数

# manager = ui.Manager(dis=display)  # 旧版
manager = ui.Manager(display)      # 新版

新建菜单:

root = ui.ListMenu()  # 列表菜单
# root = ui.IconMenu()   # 图标菜单

新建菜单项:

# root是父节点（菜单），HelloWorld时标签的内容
# 由于root是列表菜单，所以item是一个标签列表项
ui.item(root, 'HelloWorld')

设定默认菜单:

manager.page(root)

循环更新画面:

while True:
    manager.update()

至此，你已经创建了一个最简单的列表菜单