一、上一篇之后第一篇把环境搭好、程序编译跑通了。这一篇记录在 AWTK Designer 里新建项目的完整过程向导里每个字段的含义、创建完成后磁盘上生成了什么、项目设置里两个关键选项怎么选以及一个官方文档没有写、实测才发现的细节——向导里的启动页面名称并不会决定自动生成的 C 文件名。本文基于如下环境Windows 11 25H2AWTK Designer CommunitySDK 为 AWTK 1.7.1RELEASE_ID 2210项目是一个仪表 HMI 学习工程目标屏为 1216×568 的横条形 TFT。文中所有配置均以实际落盘的 project.json 为准。二、新建项目向导逐项解读新建项目对话框里需要填写的字段如下逐项说明含义与实测结果字段本文填写说明项目名称cluster_hmi_demo同时是工程文件夹名和 project.json 里的 name 字段项目路径D:\Codes\awtk_demo官方要求路径不要包含中文建议整条路径都用英文启动页面名称work_page运行时第一个打开的窗口名。注意它不决定 C 文件名详见第四节默认语言 / 国家Chinese / China对应 zh_CN写入多语言配置AWTK 路径${AWTK_SDK_PATH}/awtk${AWTK_SDK_PATH} 是 AWTK Designer 的 SDK 目录变量指向安装目录下的 SDK 文件夹宽度 / 高度1216 / 568目标屏的物理分辨率画布按此尺寸设计颜色深度 / 颜色格式32bit / BGR(A)决定主题资源的像素格式。BGR(A) 对应 AWTK 的 BITMAP_FMT_BGRA8888资源打包方式仅文件资源以文件形式放在 res 目录程序运行时从文件系统加载主题light新建时的主题风格基调创建后主题名仍为 default默认的保留字符常用中文字库裁剪规则详见下文这些字段与 project.json 的对应关系实测如下向导里改什么、落盘到哪一目了然向导字段project.json 落点备注项目名称name同时是文件夹名启动页面名称entry同时生成 application.c 里的 APP_START_PAGE 宏宽度/高度/颜色深度/颜色格式assets.themes.default.lcd与 Designer 主题页的 LCD 设置是同一份数据资源打包方式 / 常量格式assets.loadFrom / assets.const仅文件对应 loadFrom: fs默认的保留字符assets.themes.default.fonts按字号分组的保留字符表两个字段值得展开。一是颜色深度与颜色格式BGR(A) 对应 4 字节像素、内存字节序为 B、G、R、A也就是 AWTK 源码 types_def.h 里 bitmap_format_t 枚举的 BITMAP_FMT_BGRA8888。1216×568 分辨率下 32bit 帧缓冲约 2.7MB如果目标板内存吃紧可以在资源打包阶段降为 16bit 的 BGR565体积直接减半。二是默认的保留字符TTF 字体不会整包进资源Designer 按保留字符表裁剪字形实测生成的 project.json 里 fonts 节点按字号记录了三千多个常用汉字与符号。仪表类应用如果只显示数字加少量汉字在这里自定义保留字符能把字库从 MB 级压到几十 KB。三、创建完成后磁盘上生成了什么不点编译、直接查看新建完成的工程目录结构如下cluster_hmi_demo/ ├── project.json 工程核心配置名称、启动页、LCD、主题、打包方式 ├── manifest.json 工程清单 ├── SConstruct SCons 构建入口引用 SDK 完成编译链接 ├── design/default/ 设计期源文件 │ ├── ui/ 窗体 XMLwork_page.xml │ ├── styles/ 样式 │ ├── images/ 图片源文件按 x1/x2/x3/xx 分辨率分目录 │ ├── fonts/ 字体 │ └── strings/ 多语言 ├── res/ 资源输出目录Designer 打包生成程序运行时实际加载 ├── src/ │ ├── awtk_main.c 入口文件名字跟随主文件名称设置 │ ├── application.c 应用生命周期与启动页逻辑 │ ├── common/ navigator 窗口导航器 │ └── pages/ 各窗体的初始化代码 ├── scripts/ 构建辅助脚本app_helper 等 ├── tests/ 单元测试 └── bin/ 编译产物输出未编译前为空两组对应关系值得记住design 是源res 是产物改了 design 里的 UI、图片、字库之后要重新打包资源res 才会更新src 里的 pages 与 design 里的 ui 一一对应设计上每个窗体一份初始化代码——这一点正是下一节问题的由来。四、实测细节启动页面名称不会决定 C 文件的名字新建向导里我把启动页面名称填成了 work_page按直觉创建完成后 src/pages 里应该生成 work_page.c。实际生成的文件叫 home_page.c。为了排除偶然我把整个工程删掉重建了一次向导里同样填 work_page结果仍然是 home_page.c。结论稳定新建工程自动生成的 C 骨架文件固定叫 home_page.c向导里的启动页面名称不是它的命名参数。查官方 Designer 用户手册界面操作与说明一章关于代码生成的规则只有一句“对于常规项目新建窗体成功后会自动在src/pages目录创建窗体对应的C代码文件”。也就是说C 文件的自动生成只发生在新建窗体动作上向导的启动页面名称只落两处ui 目录下的窗体 XML 文件名和 application.c 里的 APP_START_PAGE 宏#defineAPP_START_PAGEwork_page要理解为什么名字错位了也不影响运行得看窗口的打开机制。AWTK 里窗口的打开与窗口的 C 代码是两条独立的线navigator_to(“work_page”) 打开窗口时UI 加载器按名字找到 work_page.xml 实例化控件树这一步不需要任何 C 文件pages 目录里的初始化函数是窗口打开之后的钩子由 src/common/navigator.c 的分发函数按窗口名做字符串匹配后调用externret_thome_page_init(widget_t*win,void*ctx);staticret_tnavigator_window_init(constchar*name,widget_t*win,void*ctx){if(tk_str_eq(name,home_page)){returnhome_page_init(win,ctx);}returnRET_OK;}窗口名是 work_page分发函数里只有 home_page 的分支匹配不上就静默跳过——所以程序编译、运行都正常只是这段钩子永远不会执行。这类问题编译器和运行时都不会报错症状是控件事件没反应属于典型的静默失效只能靠约定避免窗口名、XML 文件名、init 函数注册名三者保持一致。处理方式需要给 work_page 写控件逻辑时把 home_page.c 复制为 work_page.c函数改为 work_page_init并在 navigator.c 的分发函数里注册。改完之后 navigator_to(“work_page”) 打开窗口就会自动调用 work_page_init控件初始化和事件注册都写在这里。五、程序的类型怎么选项目设置常规页里的程序的类型有两个选项模拟器与嵌入式或移动APP对应 project.json 的 appType 字段APP_SIMULATOR 与 APP_MOBILE。这一项是程序形态的意图声明。模拟器类型面向 PC 窗口形态嵌入式或移动APP面向全屏、无窗口装饰、资源从文件系统或 ROM 加载的形态。实测两种类型都能在 PC 上正常编译并模拟运行产物为 bin 目录下的可执行文件加 awtk.dllUI 设计、控件、主题资源不受影响。本项目的终点是跑在仪表环境里所以选择了嵌入式或移动APP。需要说明的是真正移植到板子上时运行形态由移植层的 main_loop 和 LCD 驱动决定与这个选项没有强耦合——它影响的更多是生成骨架的默认假设随时可以改。同一页里还有一处改动把主文件名称从 main 改成 awtk_main 后src 下的入口文件随之命名为 awtk_main.c内容里引用 res/assets.inc 资源并包含 awtk_main.inc 主流程纯改名无副作用。六、编译与运行编译可以点 Designer 工具栏的编译按钮命令行等价于在工程根目录执行 scons。产物清单实测如下产物说明bin/cluster_hmi.exe应用本体文件名来自程序的名称bin/awtk.dllAWTK 本体动态库bin/*.pdb / *.ilk调试符号与增量链接文件运行后程序打开 work_page 窗口。新建工程自带的 work_page.xml 只有一行window/是个空窗体界面上没有内容是正常现象把控件画进去保存即可。重新编译前如果删除或重命名过源文件建议先执行 scons -c 清理再编译避免残留目标文件混进产物。七、下一步Designer 界面操作实践清单对照官方 Designer 用户手册界面操作与说明一章接下来准备逐项实践的界面功能整理如下作为第三篇的素材清单功能区域手册描述的要点计划验证的内容新建窗体新建窗体成功后会自动在 src/pages 创建对应 C 代码文件验证自动生成的文件名与窗体名的对应关系控件列表基础、容器、视图、图文、选择器、颜色、画布、多媒体等分类在 work_page 里拖放仪表常用控件属性与事件面板控件属性设置与事件绑定给控件命名并在 pages 代码里引用资源浏览器图片、字体、其他数据管理支持多分辨率目录导入仪表背景图与指针图观察 x1/x2/x3 目录机制编译 / 打包 / 模拟运行工具栏一键操作验证 design 修改后 res 的打包更新流程八、参考资料AWTK Designer 用户手册《界面操作与说明》https://awtk.zlg.cn/docs/awstudio_docs/AWTK_Designer_User_Manual/2.SoftFunction.htmlAWTK Designer 用户手册目录https://awtk.zlg.cn/docs/awstudio_docs/AWTK_Designer_User_Manual/AWTK 官方入门文档《初识 AWTK》https://awtk.zlg.cn/docs/awtk_docs/AWTK_Guide/1.GettingStarted.htmlAWTK 官网https://awtk.zlg.cn
AWTK 开发实践（二）：新建项目向导逐项解读与工程结构
一、上一篇之后第一篇把环境搭好、程序编译跑通了。这一篇记录在 AWTK Designer 里新建项目的完整过程向导里每个字段的含义、创建完成后磁盘上生成了什么、项目设置里两个关键选项怎么选以及一个官方文档没有写、实测才发现的细节——向导里的启动页面名称并不会决定自动生成的 C 文件名。本文基于如下环境Windows 11 25H2AWTK Designer CommunitySDK 为 AWTK 1.7.1RELEASE_ID 2210项目是一个仪表 HMI 学习工程目标屏为 1216×568 的横条形 TFT。文中所有配置均以实际落盘的 project.json 为准。二、新建项目向导逐项解读新建项目对话框里需要填写的字段如下逐项说明含义与实测结果字段本文填写说明项目名称cluster_hmi_demo同时是工程文件夹名和 project.json 里的 name 字段项目路径D:\Codes\awtk_demo官方要求路径不要包含中文建议整条路径都用英文启动页面名称work_page运行时第一个打开的窗口名。注意它不决定 C 文件名详见第四节默认语言 / 国家Chinese / China对应 zh_CN写入多语言配置AWTK 路径${AWTK_SDK_PATH}/awtk${AWTK_SDK_PATH} 是 AWTK Designer 的 SDK 目录变量指向安装目录下的 SDK 文件夹宽度 / 高度1216 / 568目标屏的物理分辨率画布按此尺寸设计颜色深度 / 颜色格式32bit / BGR(A)决定主题资源的像素格式。BGR(A) 对应 AWTK 的 BITMAP_FMT_BGRA8888资源打包方式仅文件资源以文件形式放在 res 目录程序运行时从文件系统加载主题light新建时的主题风格基调创建后主题名仍为 default默认的保留字符常用中文字库裁剪规则详见下文这些字段与 project.json 的对应关系实测如下向导里改什么、落盘到哪一目了然向导字段project.json 落点备注项目名称name同时是文件夹名启动页面名称entry同时生成 application.c 里的 APP_START_PAGE 宏宽度/高度/颜色深度/颜色格式assets.themes.default.lcd与 Designer 主题页的 LCD 设置是同一份数据资源打包方式 / 常量格式assets.loadFrom / assets.const仅文件对应 loadFrom: fs默认的保留字符assets.themes.default.fonts按字号分组的保留字符表两个字段值得展开。一是颜色深度与颜色格式BGR(A) 对应 4 字节像素、内存字节序为 B、G、R、A也就是 AWTK 源码 types_def.h 里 bitmap_format_t 枚举的 BITMAP_FMT_BGRA8888。1216×568 分辨率下 32bit 帧缓冲约 2.7MB如果目标板内存吃紧可以在资源打包阶段降为 16bit 的 BGR565体积直接减半。二是默认的保留字符TTF 字体不会整包进资源Designer 按保留字符表裁剪字形实测生成的 project.json 里 fonts 节点按字号记录了三千多个常用汉字与符号。仪表类应用如果只显示数字加少量汉字在这里自定义保留字符能把字库从 MB 级压到几十 KB。三、创建完成后磁盘上生成了什么不点编译、直接查看新建完成的工程目录结构如下cluster_hmi_demo/ ├── project.json 工程核心配置名称、启动页、LCD、主题、打包方式 ├── manifest.json 工程清单 ├── SConstruct SCons 构建入口引用 SDK 完成编译链接 ├── design/default/ 设计期源文件 │ ├── ui/ 窗体 XMLwork_page.xml │ ├── styles/ 样式 │ ├── images/ 图片源文件按 x1/x2/x3/xx 分辨率分目录 │ ├── fonts/ 字体 │ └── strings/ 多语言 ├── res/ 资源输出目录Designer 打包生成程序运行时实际加载 ├── src/ │ ├── awtk_main.c 入口文件名字跟随主文件名称设置 │ ├── application.c 应用生命周期与启动页逻辑 │ ├── common/ navigator 窗口导航器 │ └── pages/ 各窗体的初始化代码 ├── scripts/ 构建辅助脚本app_helper 等 ├── tests/ 单元测试 └── bin/ 编译产物输出未编译前为空两组对应关系值得记住design 是源res 是产物改了 design 里的 UI、图片、字库之后要重新打包资源res 才会更新src 里的 pages 与 design 里的 ui 一一对应设计上每个窗体一份初始化代码——这一点正是下一节问题的由来。四、实测细节启动页面名称不会决定 C 文件的名字新建向导里我把启动页面名称填成了 work_page按直觉创建完成后 src/pages 里应该生成 work_page.c。实际生成的文件叫 home_page.c。为了排除偶然我把整个工程删掉重建了一次向导里同样填 work_page结果仍然是 home_page.c。结论稳定新建工程自动生成的 C 骨架文件固定叫 home_page.c向导里的启动页面名称不是它的命名参数。查官方 Designer 用户手册界面操作与说明一章关于代码生成的规则只有一句“对于常规项目新建窗体成功后会自动在src/pages目录创建窗体对应的C代码文件”。也就是说C 文件的自动生成只发生在新建窗体动作上向导的启动页面名称只落两处ui 目录下的窗体 XML 文件名和 application.c 里的 APP_START_PAGE 宏#defineAPP_START_PAGEwork_page要理解为什么名字错位了也不影响运行得看窗口的打开机制。AWTK 里窗口的打开与窗口的 C 代码是两条独立的线navigator_to(“work_page”) 打开窗口时UI 加载器按名字找到 work_page.xml 实例化控件树这一步不需要任何 C 文件pages 目录里的初始化函数是窗口打开之后的钩子由 src/common/navigator.c 的分发函数按窗口名做字符串匹配后调用externret_thome_page_init(widget_t*win,void*ctx);staticret_tnavigator_window_init(constchar*name,widget_t*win,void*ctx){if(tk_str_eq(name,home_page)){returnhome_page_init(win,ctx);}returnRET_OK;}窗口名是 work_page分发函数里只有 home_page 的分支匹配不上就静默跳过——所以程序编译、运行都正常只是这段钩子永远不会执行。这类问题编译器和运行时都不会报错症状是控件事件没反应属于典型的静默失效只能靠约定避免窗口名、XML 文件名、init 函数注册名三者保持一致。处理方式需要给 work_page 写控件逻辑时把 home_page.c 复制为 work_page.c函数改为 work_page_init并在 navigator.c 的分发函数里注册。改完之后 navigator_to(“work_page”) 打开窗口就会自动调用 work_page_init控件初始化和事件注册都写在这里。五、程序的类型怎么选项目设置常规页里的程序的类型有两个选项模拟器与嵌入式或移动APP对应 project.json 的 appType 字段APP_SIMULATOR 与 APP_MOBILE。这一项是程序形态的意图声明。模拟器类型面向 PC 窗口形态嵌入式或移动APP面向全屏、无窗口装饰、资源从文件系统或 ROM 加载的形态。实测两种类型都能在 PC 上正常编译并模拟运行产物为 bin 目录下的可执行文件加 awtk.dllUI 设计、控件、主题资源不受影响。本项目的终点是跑在仪表环境里所以选择了嵌入式或移动APP。需要说明的是真正移植到板子上时运行形态由移植层的 main_loop 和 LCD 驱动决定与这个选项没有强耦合——它影响的更多是生成骨架的默认假设随时可以改。同一页里还有一处改动把主文件名称从 main 改成 awtk_main 后src 下的入口文件随之命名为 awtk_main.c内容里引用 res/assets.inc 资源并包含 awtk_main.inc 主流程纯改名无副作用。六、编译与运行编译可以点 Designer 工具栏的编译按钮命令行等价于在工程根目录执行 scons。产物清单实测如下产物说明bin/cluster_hmi.exe应用本体文件名来自程序的名称bin/awtk.dllAWTK 本体动态库bin/*.pdb / *.ilk调试符号与增量链接文件运行后程序打开 work_page 窗口。新建工程自带的 work_page.xml 只有一行window/是个空窗体界面上没有内容是正常现象把控件画进去保存即可。重新编译前如果删除或重命名过源文件建议先执行 scons -c 清理再编译避免残留目标文件混进产物。七、下一步Designer 界面操作实践清单对照官方 Designer 用户手册界面操作与说明一章接下来准备逐项实践的界面功能整理如下作为第三篇的素材清单功能区域手册描述的要点计划验证的内容新建窗体新建窗体成功后会自动在 src/pages 创建对应 C 代码文件验证自动生成的文件名与窗体名的对应关系控件列表基础、容器、视图、图文、选择器、颜色、画布、多媒体等分类在 work_page 里拖放仪表常用控件属性与事件面板控件属性设置与事件绑定给控件命名并在 pages 代码里引用资源浏览器图片、字体、其他数据管理支持多分辨率目录导入仪表背景图与指针图观察 x1/x2/x3 目录机制编译 / 打包 / 模拟运行工具栏一键操作验证 design 修改后 res 的打包更新流程八、参考资料AWTK Designer 用户手册《界面操作与说明》https://awtk.zlg.cn/docs/awstudio_docs/AWTK_Designer_User_Manual/2.SoftFunction.htmlAWTK Designer 用户手册目录https://awtk.zlg.cn/docs/awstudio_docs/AWTK_Designer_User_Manual/AWTK 官方入门文档《初识 AWTK》https://awtk.zlg.cn/docs/awtk_docs/AWTK_Guide/1.GettingStarted.htmlAWTK 官网https://awtk.zlg.cn
