设置多个资源分区

启用 非紧凑模式(资源分区前缀可配置) 后，工具会生成资源分区前缀相关接口，通过设置多个资源前缀，可以实现"主资源目录获取不到资源时，自动从备份资源目录获取"的效果。

本章目录

1. 启用非紧凑模式(资源分区前缀可配置)
2. 接口
- 2.1. 资源查找逻辑
3. 使用示例
- 3.1. 场景：页面资源双备份

本章正文

启用 `非紧凑模式(资源分区前缀可配置)`

在 项目 - 属性 - 资源配置 下，将 资源模式 改为 非紧凑模式(资源分区前缀可配置)。

工具在生成代码时会额外生成一组资源分区前缀相关的接口，方便设置多个资源目录互相备份。

接口

工具会在生成目录下生成资源分区相关的文件：

.\generated\gui_common.h
.\generated\gui_common.c

接口	说明
`gui_set_res_prefix(type, prefix)`	设置指定类型的主资源前缀（索引 0）。
`gui_set_res_prefix_by_index(type, index, prefix)`	按索引设置指定类型的资源前缀，成功返回 `true`。
`gui_add_res_prefix(type, prefix)`	在末尾追加一个资源前缀，返回新前缀的索引；失败返回 `-1`。
`gui_get_res_prefix(type)`	获取指定类型的主资源前缀。
`gui_get_res_prefix_by_index(type, index)`	按索引获取指定类型的资源前缀。
`gui_get_res_prefix_count(type)`	获取指定类型当前已设置的前缀数量。
`gui_get_res_path_to_buf(id, out_buf, out_size)`	根据资源 ID 拼接资源路径并写入 `out_buf`，返回 `out_buf`。
`gui_res_file_exist(path)`	判断资源文件是否存在。

资源查找逻辑

资源路径的拼接规则为：前缀 + 资源ID(十六进制) + 扩展名，例如 A:/res/flash/4b000000.zip。
获取资源时，会遍历该分区的前缀列表，通过 gui_res_file_exist 判断文件是否存在，返回第一个存在的文件路径。
所有目录都找不到时，会回退返回主目录（索引 0）对应的路径，此时实际打开文件会失败。

查找的先后顺序由宏 GUI_RES_PREFIX_PRIORITY_DESC 控制：

`GUI_RES_PREFIX_PRIORITY_DESC`	查找顺序
`1`（默认）	下标大的前缀优先，即后添加 / 设置的备份目录优先
`0`	下标小的前缀优先，即索引 0 的主目录优先（先主目录、再备份目录）

提示

如果希望"先主目录，找不到再查备份目录"，需要将 GUI_RES_PREFIX_PRIORITY_DESC 定义为 0。

使用示例

场景：页面资源双备份

把某个页面用到的资源单独抽出来作为备份，主资源损坏时自动从备份目录读取，保证页面仍能正常显示。

1. 获取页面使用的资源 ID 列表

页面与资源的关系记录在工程的 jlui/design/default/ui.json 中：

screen：页面列表，页面下 widgets 中控件的 img_flash_path / img_sd_path 等字段引用资源文件（如 /4b000004.zip）
projectResource.image.data：图片资源列表，包含资源 ID、名称、文件类型等

将 ui.json 交给 AI，从目标页面的控件引用中解析出该页面用到的资源 ID 列表。例如页面 home 使用：

资源	资源 ID	文件名
GUI_RES_MENU_6MOTION_MODE_PNG	0x4B000004	4b000004.zip

提示

为保证备份目录与生成代码中的资源 ID 始终一致，请保持被提取页面的资源固定，并在工具上将相关页面 置顶，避免资源的增删导致每次生成的资源 ID 发生变化；若资源确有增减，请同步更新上文提取的页面资源列表。

2. 准备备份资源

把上述资源文件拷贝到独立的备份目录，例如：_listen_bg_alpha480x320.c

主目录：A:/res/flash/4b000004.zip
备份目录：D:/res_backup/flash/4b000004.zip

3. 设置备份前缀

在自定义代码中，为主资源追加备份前缀，主目录读取不到时，自动到备份目录读取：

#include "gui/_res/res_common.h"   // 资源前缀接口头文件，以工程实际生成路径为准

// Flash 分区：主目录 + 备份目录
gui_set_res_prefix(GUI_RES_PREFIX_FLASH, "A:/res/flash/");
gui_add_res_prefix(GUI_RES_PREFIX_FLASH, "D:/res_backup/flash/");

// SD 分区：主目录 + 备份目录
gui_set_res_prefix(GUI_RES_PREFIX_SD, "A:/res/sd/");
gui_add_res_prefix(GUI_RES_PREFIX_SD, "D:/res_backup/sd/");

提示

资源路径按 前缀 + 资源ID(十六进制) + 扩展名 拼接，备份目录下的文件名需与主目录一致（如 4b000004.zip）。如需"主目录优先、备份兜底"，将 GUI_RES_PREFIX_PRIORITY_DESC 定义为 0（见上文"资源查找逻辑"）。