UI 工程与工具链

本文介绍 AC792N SDK（V3）中 UI 工程从素材准备、UI 编辑、资源生成、资源下载到运行时控件显示的完整工具链，以及 UI 编辑工具、UI 配置（LED 数码管 / LCD）与 ui_* 运行时接口的使用方法。

Purpose and Scope

本页面覆盖 UI 工程与工具链的完整闭环：

• UI 工具开发流程（素材准备 → UI 布局 → 资源下载 → 控件显示）；
• UI 工具链产物（JL.sty、JL.str、JL.res、style_JL.h）；
• UI 编辑工具的组成（控件列表、属性列表、设计区、预览区）与控件属性；
• UI 资源生成与下载（copy_file.bat、ui_resource、JL/font 目录、download.bat 下载到 flash 的 res 区）；
• 可视化配置工具中的 UI 配置（LED7 数码管屏、LCD 点阵屏）；
• 运行时侧 ui_* API 与 LVGL 动态解析基础（gui_common.h、gui_parse_dyn.h）。

LED 数码管（LED UI）的专用接口、配置与状态说明属于兄弟主题，请参见 LED UI 相关文档；UI 运行接口的完整签名列表以「UI 接口说明」文档为准。

Overview

AC792N SDK 的 UI 能力建立在 LVGL v8 之上，并通过一套离线的 UI 编辑工具链将设计期产物转化为可在 flash res 区存放、可在运行时被动态解析的资源文件。整个体系的设计意图是：把界面设计与嵌入式开发解耦——UI 设计者使用 PC 端工具完成布局，生成二进制资源与控件 ID 头文件；固件开发者只关心 style_JL.h 中导出的 ID 和 ui_* 接口，无需手写 LVGL 控件创建代码。

关键概念：

• UI 工程（ui_project）：UI 编辑工具保存的工程目录，其中"模式界面"子工程用于触发资源生成。
• 资源四件套：JL.sty（控件样式）、JL.str（字符串/字库相关内容）、JL.res（图片等资源）、style_JL.h（控件/页面 ID 头文件，供 C 代码引用）。
• 下载目录约定：ui_resource 下的文件按用途拷贝到 JL（图片、控件属性）与 font（字库）两个文件夹，由 download.bat 一并下载进 flash 的 res 区。
• 运行时解析：上电后固件（LVGL v8 + jl_extra 扩展）解析资源文件，动态创建 obj/scr/label/btn/img/analog_clock/imglist/line 等控件，应用通过 ui_show_main(PAGE_x) 等接口切换页面。

Architecture

下图展示 UI 工程与工具链的完整架构：设计期（PC 工具）与运行期（固件）通过 flash res 区中的资源文件衔接。

flowchart TD
    subgraph sg_Design["设计期（PC 工具）"]
        A["素材准备<br/>（图片/字库/音频）"]
        B["UI 编辑工具<br/>（控件列表/属性列表/设计区/预览区）"]
        C["UI 工程<br/>ui_project/模式界面"]
        D["UI 资源生成工具"]
        E["copy_file.bat"]
        F["ui_resource 文件夹"]
    end

    subgraph sg_Flash["资源下载"]
        G["JL 文件夹<br/>（图片/控件属性）"]
        H["font 文件夹<br/>（字库）"]
        I["download.bat"]
        J["(flash) res 区"]
    end

    subgraph sg_Runtime["运行期（固件）"]
        K["可视化配置工具<br/>UI 配置使能"]
        L["LVGL v8 + jl_extra<br/>gui_parse_dyn 解析"]
        M["style_JL.h 控件 ID"]
        N["ui_* API<br/>lcd_ui_api.c / ui_text.c 等"]
        O["LCD / LED 屏幕显示"]
    end

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    F --> H
    G --> I
    H --> I
    I --> J
    J --> L
    K --> L
    M --> N
    L --> N
    N --> O

各部分职责：

• UI 编辑工具：拖拽式新建控件，维护每个控件唯一的 ID 号，实时更新位置坐标，可配置对齐方式、背景颜色与背景图片；保存工程后由"模式界面"中的 UI 资源生成工具产出资源。
• copy_file.bat：资源生成后把产物拷贝到与 UI 工程同级的 ui_resource 文件夹，脚本路径可自行修改以更改输出位置。
• download.bat：将 JL、font 两个文件夹一起下载进 flash 的 res 区，保证程序正常运行后可接入屏幕查看效果。
• 可视化配置工具：在 UI 配置页面对 UI 进行使能，选择 LED 数码管屏或 LCD 点阵屏（soundbar），配置 SPI、引脚与 OLED/SSD1306 驱动等参数。
• 运行时：gui_parse_dyn（LVGL v8 jl_extra 扩展）按 gui_common.h 中定义的控件类型与属性 ID 动态构建控件树，ui_* API 以 style_JL.h 中的页面/控件 ID 为句柄驱动显示。

UI 工具开发流程

UI 工具的开发流程分为四个阶段：素材准备、UI 布局、资源下载、控件显示，如下图所示（对应官方文档"图 1：UI 工具开发流程"）：

flowchart LR
    S1["素材准备"] --> S2["UI 布局"]
    S2 --> S3["资源下载"]
    S3 --> S4["控件显示"]

• 素材准备：准备界面所需的图片、字库等原始素材，供 UI 编辑器引用。
• UI 布局：在 UI 编辑工具中新建页面与图层，在图层上创建布局，在布局上摆放控件并设置属性。
• 资源下载：保存工程后点击 UI 资源生成工具，将产物经 copy_file.bat 放入 ui_resource，再经 download.bat 下载进 flash 的 res 区。
• 控件显示：固件解析资源并调用 ui_show_main(PAGE_x) 等接口显示页面与控件。

该流程的设计意图是让资源生成、下载与固件开发互相独立：任何一次 UI 布局修改都只需重新走"生成 → 下载"两步，不需要重新编译固件，从而大幅缩短音视频类产品（soundbar、点歌机等）界面迭代的验证周期。

UI 工具链产物

UI 工程编辑完成后，最终生成的文件为 JL.sty、JL.str、JL.res 三个资源文件，以及存放控件 ID 的 style_JL.h 头文件（官方文档"图 2：UI 工具链介绍"）：

style_JL.h 是设计期与运行期的契约层：它把工具链中分配的数值 ID 翻译成固件可读的符号常量，固件代码中所有 ui_show_main(PAGE_0)、ui_show(PIC_1) 形式的调用都以该头文件为唯一来源。

UI 编辑工具

UI 编辑工具由控件列表、属性列表、设计区、预览区四部分组成（官方文档"图 3：UI 编辑工具"）：

• 控件列表：列出可用控件类型，新建控件采用拖拽方式——单击选中控件后拖动到 UI 设计窗口。控件以灰色显示时表示当前不可用。
• 属性列表：展示选中控件的属性（ID 号、对齐方式、位置坐标、背景颜色、背景图片等），支持手动精确输入。
• 设计区：所见即所得的布局画布，拖动控件时坐标信息实时更新到属性栏。
• 预览区：模拟实际屏幕效果，用于检查布局与层级。

工具内部强制了一个页面 → 图层 → 布局 → 控件的层级模型：

• 新建页面后必须先创建一个图层；
• 图层上可以创建布局；
• 布局上可以创建各类控件；
• 当前芯片只支持单图层，因此每个页面只能建立一个图层（多图层会导致资源解析或显示异常）。

控件属性

控件 ID 的唯一性约束至关重要：style_JL.h 中导出的 ID 是运行时 ui_* API 定位控件的句柄，若两个控件 ID 重复，运行时动态解析阶段将无法区分目标控件，导致显示错误或隐藏/显示失效。

UI 资源配置

UI 的设置在可视化配置工具的 UI 配置页面完成：在 UI 配置页面对 UI 进行使能，用户可选择对应的 UI 类型（官方文档"图：UI 配置"）。支持两大类型：

LED7（数码管）配置

选择"LED 数码管屏"后，可配置：

• LED 屏驱动跑 RAM：占用 RAM 约 35K，led7_scan 调用到的全部代码存放在 RAM 中，且扫描中断设置为不可屏蔽中断（NMI）。设计意图：数码管扫描对时序敏感，不使用不可屏蔽中断可能出现闪屏风险。
• LED7 脚数码管屏：使能 7 脚数码管屏。
• LED 屏引脚配置：选择对应的 IO。

提示：关于不可屏蔽中断的使用方法与注意事项，请阅读"操作系统"章节的"临界区（不可屏蔽中断）"及"不可屏蔽中断"。

LCD 配置

选择"LCD 点阵屏（soundbar）"后，可配置：

• LCD SPI 口选择：选择对应的 SPI（SPI 需在板级配置页里的"硬件 SPI1"或"硬件 SPI2"进行配置）。
• 歌词显示：暂不支持。
• 保存歌词的时间标签到 flash：暂不支持。
• OLED 屏使能：使能 OLED 屏。
• SSD1306：选择 SSD1306 驱动。
• LCD 屏引脚配置：选择对应的 IO。

配置的设计意图：SPI 与引脚在配置工具中集中管理，生成对应的板级初始化代码；驱动层按配置选择 SPI 实例与显示驱动（如 SSD1306），固件侧无需为每种屏体单独写适配。

UI 资源下载

在"UI 工具说明"文档中，通过工具生成 UI 资源后，需要将其下载进 flash。具体步骤如下（对应官方文档"UI 资源下载说明"）：

1. 在 UI 工程中点击生成 UI 资源（"图：UI 资源生成"）。
2. 生成后的资源根据 copy_file.bat 被放到与 UI 工程文件夹同级目录的 ui_resource 文件夹下（"图：UI 资源存放位置"）。用户可自行更改 copy_file.bat 中的文件生成路径，文件位于 UI工程/ui_project/模式界面/project/copy_file.bat。
3. 在下载目录中新建两个文件夹，分别命名为 JL、font，将 ui_resource 下的文件拷贝到其中——JL 存放图片、控件属性，font 存放字库文件（"图：UI 文件命名"）。
4. 最后在 download.bat 中将 JL、font 两个文件夹一起下载进 flash 的 res 区（"图：UI 文件下载"）。
5. 程序正常下载后，接入 LCD 屏查看效果。

flowchart TD
    A["UI 工程点击<br/>UI 资源生成工具"] --> B["copy_file.bat<br/>（路径可改）"]
    B --> C["ui_resource 文件夹<br/>（与 UI 工程同级）"]
    C --> D["拷贝到下载目录"]
    D --> E["JL 文件夹<br/>图片/控件属性"]
    D --> F["font 文件夹<br/>字库"]
    E --> G["download.bat"]
    F --> G
    G --> H["flash res 区"]
    H --> I["接入屏幕查看效果"]

运行时侧：资源解析与控件类型

固件运行期通过 LVGL v8 的 jl_extra 扩展解析资源。gui_common.h 定义了动态解析所需的控件类型字符串/ID 与 属性操作 ID（style/position/控件专属操作），gui_parse_dyn.h 负责按资源文件动态构建控件树。资源文件中的每个控件记录均携带类型 ID 与属性 ID 列表，解析器据此调用对应的 LVGL 接口。

控件类型定义如下（摘自 gui_common.h）：

// 控件类型
#define TYPE_OBJ         "obj"
#define TYPE_SCR         "scr"
#define TYPE_LABEL       "label"
#define TYPE_BTN         "btn"
#define TYPE_IMG         "img"
#define TYPE_ANALOGCLOCK "analog_clock"
#define TYPE_IMGLIST     "imglist"
#define TYPE_LINE        "line"

#define TYPE_OBJ_ID         0x10
#define TYPE_LABEL_ID       0x11
#define TYPE_BTN_ID         0x12
#define TYPE_IMG_ID         0x13
#define TYPE_ANALOGCLOCK_ID 0x14
#define TYPE_IMGLIST_ID     0x15
#define TYPE_LINE_ID        0x16

Source: gui_common.h

属性操作 ID 采用分组编号设计：样式类从 0x00100000 起、基础控件属性从 0x00010000 起、label 从 0x00011000 起、img 从 0x00013000 起、模拟时钟从 0x00014000 起、imglist 从 0x00015000 起、line 从 0x00016000 起。这种编码让解析器可以按高字节快速路由到对应控件的属性设置函数，例如：

// 基础控件
#define LV_OBJ_SET_POS_ID       0x00010000
#define LV_OBJ_SET_SIZE_ID      0x00010001
#define LV_OBJ_SET_X_ID         0x00010002
#define LV_OBJ_SET_Y_ID         0x00010003
#define LV_OBJ_SET_WIDTH_ID     0x00010004
#define LV_OBJ_SET_HEIGHT_ID    0x00010005

// img
#define LV_IMG_SET_SRC_ID      0x00013000
#define LV_IMG_SET_PIVOT_ID    0x00013001
#define LV_IMG_SET_ANGLE_ID    0x00013002
#define LV_IMG_SET_ZOOM_ID     0x00013003

Source: gui_common.h

设计意图：把 LVGL 的 setter API 抽象为可序列化的属性 ID，使资源文件可以用纯数据描述界面，工具链与运行期共用同一套 ID 语义，新增控件属性时只需在 gui_common.h 增加宏并在解析器中注册处理函数。

Core Flow

一次完整的 UI 显示流程从资源下载到控件上屏的时序如下：

sequenceDiagram
    participant Dev as 开发者
    participant Editor as UI 编辑工具
    participant Gen as UI 资源生成工具
    participant Bat as copy_file.bat
    participant Flash as flash res 区
    participant Parser as gui_parse_dyn
    participant Api as ui_* API
    participant Screen as LCD/LED 屏

    Dev->>Editor: 拖拽控件、设置属性
    Editor->>Editor: 保存 UI 工程（ui_project/模式界面）
    Dev->>Gen: 点击 UI 资源生成
    Gen->>Bat: 生成 JL.sty/JL.str/JL.res/style_JL.h
    Bat->>Flash: 经 JL/font 目录与 download.bat 下载到 res 区
    Flash->>Parser: 上电后解析资源，创建 LVGL 控件树
    Parser->>Api: 注册页面/控件 ID（style_JL.h）
    Dev->>Api: ui_show_main(PAGE_x) / ui_show(PIC_x)
    Api->>Screen: 刷新显示
    Screen-->>Dev: 界面可见

关键点：style_JL.h 在生成与解析两侧同时生效——工具链生成它，固件包含它，从而保证 ID 语义一致；应用代码只依赖符号常量，不关心资源文件内部布局格式。

Usage Examples

以下示例均取自官方文档"UI 接口说明"与 SDK 头文件。

显示/隐藏页面与控件

页面 ID（PAGE_0）与控件 ID（PIC_1）由工具链生成的 style_JL.h 提供：

int ui_show_main(int id);       // 显示指定页面，id 为页面 ID 号
int ui_hide_main(int id);       // 隐藏指定页面
int ui_hide_curr_main(void);    // 隐藏当前页面
int ui_get_current_window_id(void); // 获取当前页面 ID

ui_show_main(PAGE_0);           // PAGE_0 为页面的 ID 号，参考 style.h 文件
ui_hide_main(PAGE_0);
ui_show(PIC_1);                 // 显示图片控件 PIC_1，参考 style.h
ui_hide(PIC_1);                 // 隐藏图片控件 PIC_1

Source: ui_api.rst.txt

数字控件更新

数字控件通过 struct unumber 描述要显示的数字内容，支持数字与数字字符串两种类型：

enum {
    TYPE_NUM,     // 数字
    TYPE_STRING,  // 数字字符串
};

struct unumber {
    u8 numbs;        // 数字个数
    u8 type;         // 类型：TYPE_NUM / TYPE_STRING
    u32 number[2];   // 数值，当 TYPE_NUM 时有效
    u8 *num_str;     // 字符串，当 TYPE_STRING 时有效
};

struct unumber n;
n.type = TYPE_NUM;
n.numbs = 1;
n.number[0] = 10;
ui_number_update_by_id(NUMBER, &n);

Source: ui_api.rst.txt

文本显示（strpic / UNICODE / UTF8）

文本控件支持 strpic 编码（索引方式）与 text 编码（UNICODE / UTF8 字符串方式）：

int ui_text_set_index(struct ui_text *text, int index);            // 按文本控件句柄切换
int ui_text_show_index_by_id(int id, int index);                   // 按文本控件 ID 切换
int ui_text_set_textw_by_id(int id, const char *str, int strlen, int endian, u32 flags); // UNICODE 编码
int ui_text_set_textu_by_id(int id, const char *str, int strlen, u32 flags);             // UTF8 编码

Source: ui_api.rst.txt

Configuration Options

UI 配置在可视化配置工具的 UI 配置页面完成，先使能 UI，再选择屏体类型：

Source: ui_config.rst.txt

API Reference

运行时 UI 接口由 lcd_ui_api.c、ui_pic.c、ui_text.c、ui_number.c 等模块实现，页面/控件 ID 引用 style_JL.h（文档中称 style.h）。

页面管理（lcd_ui_api.c）

控件管理（lcd_ui_api.c）

图片控件（ui_pic.c）

文本控件（ui_text.c）

数字控件（ui_number.c）

Source: ui_api.rst.txt

Failure Modes, Edge Cases & Concurrency

• 闪屏风险（数码管扫描时序）：LED 屏驱动不跑 RAM 或扫描中断未设置为不可屏蔽中断（NMI）时，可能出现闪屏。原因是 led7_scan 的扫描代码位于 flash，取指延迟导致中断响应抖动。配置"LED 屏驱动跑 RAM"（约 35K RAM）后，扫描代码与中断全部驻留 RAM 并使用 NMI 保证确定性。使用 NMI 时需注意临界区保护，详见"操作系统"章节的不可屏蔽中断说明。
• 单图层限制：当前芯片仅支持单图层，每个页面只能建立一个图层；若在工具中创建多个图层，资源解析行为不受支持，应视为无效布局。图层之上才可建布局，布局之上才可放控件，层级缺失会导致控件无法创建。
• 控件灰色不可用：控件列表中以灰色显示的控件类型表示当前不可用（可能受芯片资源或版本限制），强行拖入不会产生有效控件。
• 控件 ID 冲突：控件 ID 必须唯一，ID 冲突会导致 ui_* API 定位到错误控件，表现为显示/隐藏错乱；工具默认分配 ID，手动修改时需自行保证唯一性。
• 资源路径不一致：copy_file.bat 的生成路径可被用户修改，若 ui_resource 输出位置与下载目录预期不符，后续拷贝到 JL/font 会失败，需确保脚本路径与实际目录一致。
• 未下载资源即上电：JL.sty/JL.res 等未下载进 flash res 区时，运行时解析将找不到控件数据，界面不显示；LCD 需按"生成 → 拷贝 → download.bat → res 区"完整链路执行后再接入屏幕验证。
• 并发/多任务注意：页面切换（ui_show_main/ui_hide_main）与文本/数字更新接口应在 UI 线程上下文中调用；使用 NMI 中断的数码管扫描路径与业务代码之间通过临界区互斥，避免在不可屏蔽中断内调用可能阻塞的 LVGL 接口。
• 暂不支持能力：LCD 的歌词显示、保存歌词时间标签到 flash 两个配置项当前版本暂不支持，配置后不会产生预期效果。

Performance & Operational Considerations

• RAM 开销："LED 屏驱动跑 RAM"模式约占用 35K RAM，资源紧张的产品需在配置前评估剩余内存。
• SPI 依赖：LCD 的 SPI 必须先在板级配置页的"硬件 SPI1/SPI2"中启用并配置，UI 配置页只做选择，未配置 SPI 将导致 LCD 无显示。
• 字库管理：字库文件统一放 font 目录，图片/控件属性放 JL 目录；两者经 download.bat 一并下载到 res 区，字库更新需重新执行下载流程。
• 迭代效率：UI 布局修改只需重跑"资源生成 → 下载"，无需重编固件，是工具链带来的核心运维收益。

Extension Points

• copy_file.bat：位于 UI工程/ui_project/模式界面/project/copy_file.bat，可修改资源输出路径，实现自定义的产物收集/后处理流程。
• gui_common.h 控件类型与属性 ID：新增自定义控件类型或 LVGL 属性时，在此头文件登记类型字符串/ID 与属性操作 ID（按分组编号规则递增），并在解析器（gui_parse_dyn）中注册对应的属性设置处理函数。
• ui_* 接口族：页面/控件/图片/文本/数字接口已覆盖常见显示需求；自定义控件可仿照 ui_pic.c、ui_text.c、ui_number.c 的组织方式，提供 xxx_xxx_by_id 形式的 API 供应用层调用。

Tests

官方文档未提供针对 UI 工具链的自动化测试用例描述；工具链的验证方式为端到端人工验证：资源生成后下载进 res 区，接入 LCD/LED 屏观察页面切换与控件显示是否符合预期。固件侧可结合 ui_get_current_window_id() 断言当前页面 ID，辅助调试页面切换逻辑。

Related Links

• UI 接口说明（ui_api）
• UI 配置说明（ui_config）
• UI 工具说明（ui_tool）
• 运行时 GUI 公共定义（gui_common.h）
• 动态解析声明（gui_parse_dyn.h）
• 兄弟主题：LED UI（led_ui）接口/配置/状态说明、通用组件/ui 文档