WebUI页面结构

1. WebUI 总体结构

一套典型的WebUI系统，其文件结构遵循清晰的模块化划分，各目录各司其职、相互配合，构成完整的前端运行体系。具体结构如下：

• html/：存放页面HTML模板，定义各页面的基础结构，是页面呈现的核心载体。

• js/panel/：对应各页面的前端控制器，负责处理页面的加载、数据交互、事件响应等核心逻辑。

• js/base/：包含通用工具函数，如AJAX请求封装、布局处理、XML解析、通用校验等，为各页面提供基础支撑。

• xml/：用于定义UI菜单配置，驱动菜单的展示、层级关系及页面关联。

• xmldata/：存储各业务模块的XML数据模板，约定前后端数据交互的结构规范。

• properties/：多语言资源文件，存放不同语言的文案，实现系统的多语言适配。

• css/：样式文件目录，包含全局样式、页面专用样式，统一页面视觉风格。

• 后端applet或CGI处理代码：负责模块注册、前端请求接收、数据获取与保存，是前后端交互的桥梁。

2. 新增一个页面需要改哪些地方

在现有WebUI系统中新增一个页面，需完成前端各模块的配置与开发，若涉及数据读写，还需联动后端进行模块注册。具体需接入的内容如下：

1. 页面HTML：定义页面结构、输入控件及交互区域，为JS控制器提供绑定基础。

1. 页面JS控制器：实现页面加载、数据读写、表单校验、提交反馈等核心逻辑。

1. 页面JS脚本引用：在入口页引入新增页面的JS控制器，确保菜单点击时能正常实例化页面对象。

1. 菜单配置：在XML菜单中注册新增页面，关联页面对象与业务模块。

1. 数据模板XML：若页面需读写数据，需定义对应的数据模板，约定前后端数据结构。

1. 多语言文案：在多语言资源文件中补充页面相关文案，如菜单名、标题、按钮文字等。

1. 后端模块处理函数：若页面需读写后端数据，需注册后端处理函数，负责数据的获取与保存。

1. 页面样式：优先复用全局样式，必要时新增页面专用样式，保证视觉一致性。

补充说明：若页面仅展示静态内容，可省略后端数据模块相关操作；若页面需要读写配置，则必须完成前后端的全流程对接。

3. 步骤一：新增页面 HTML

页面HTML的核心职责是定义页面的基础结构，为后续的JS交互和样式渲染提供载体，具体需包含以下内容：

• 定义页面整体结构，划分标题区、表单区、按钮区、错误提示区等核心区域。

• 定义必要的输入控件，如input（文本输入）、select（下拉选择）、textarea（多行输入）等。

• 预留标题、分组标题、错误提示和按钮区域，确保页面布局清晰、交互逻辑明确。

• 为各元素分配唯一id，用于与JS控制器绑定，实现事件响应和数据回填。

以下是一个通用的页面HTML结构示例：

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| html <label id="title" class="title"></label> <div class="formBox"> <label id="lGroupTitle" class="subttl1"></label> <div class="formRow"> <label id="lField1" for="field1"></label> <input id="field1" type="text" /> </div> <div class="formRow"> <label id="lField2" for="field2"></label> <select id="field2"></select> </div> </div> <div align="right"> <span class="btnWrp"> <input type="button" id="btUpdate" value="Save" onclick="setData()" /> </span> </div> <div align="center"> <label id="lError" class="error" style="display:none;"></label> </div> |

4. 步骤二：新增页面 JS 控制器

每个页面通常对应一个独立的JS控制器对象，该对象封装了页面的所有交互逻辑，是页面与后端、页面与用户交互的核心。通用页面对象通常包含以下核心方法，实现页面的全生命周期管理：

• loadHTML()：将页面HTML模板加载到系统的内容展示区域，完成页面的初始渲染。

• setXMLName(xmlName)：保存当前页面关联的业务模块名，用于后续数据读写时关联后端模块。

• onLoad()：页面初始化方法，负责加载HTML、初始化多语言文案、读取后端数据并完成表单回填。

• onPost()：数据提交方法，负责收集表单数据、进行数据校验、组装XML数据并提交到后端。

• onPostSuccess()：提交成功后的回调方法，通常用于页面刷新、提示用户操作成功等。

以下是通用页面对象的结构示例：

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| javascript (function () { .fn.objPageName = function (initKey) { var xmlName = ""; function localize() { // 标题、标签、选项、按钮本地化，从多语言文件中读取文案并赋值 } function isValid() { // 表单校验逻辑，判断输入内容是否合法，返回布尔值 return true; } this.loadHTML = function () { document.getElementById("Content").innerHTML = ""; document.getElementById("Content").innerHTML = callProductHTML("html/module/page.html"); }; this.onLoad = function () { var xml; this.loadHTML(); localize(); xml = getData(xmlName); // 从xml中解析字段并回填到表单 ("#field1").val((xml).find("field1").text()); ("#field2").val((xml).find("field2").text()); }; this.onPost = function () { var mapData = new Array(0); var index = 0; if (!isValid()) { return; } // 把表单字段组装成XML映射 mapData = g_objXML.putMapElement(mapData, index++, "RGW/module/field1", ("#field1").val()); mapData = g_objXML.putMapElement(mapData, index++, "RGW/module/field2", ("#field2").val()); // 提交XML数据到后端 postXML(xmlName, g_objXML.getXMLDocToString(g_objXML.createXML(mapData))); }; this.onPostSuccess = function () { // 提交成功后刷新页面，重新加载数据 this.onLoad(); }; this.setXMLName = function (_xmlName) { xmlName = _xmlName; }; return this.each(function () { }); }; })(jQuery); |

5. 步骤三：在入口页中引入页面 JS

新增页面控制器后，需在系统主入口页（通常为index.html）中引入该JS脚本，否则菜单点击时无法找到对应的页面对象，导致页面无法正常加载。引入方式如下，需确保脚本路径与实际文件路径一致：

|---------------------------------------------------------------------------------|
| html <script type="text/javascript" src="js/panel/module/page.js"></script> |

6. 步骤四：在菜单配置中注册页面

WebUI菜单通常由XML或JSON文件驱动，其中XML配置是最常用的形式。新增页面需在菜单XML中注册，关联菜单项、页面对象与业务模块，确保菜单点击时能正确实例化页面对象并加载页面。

菜单XML的通用配置示例如下：

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| xml <Tab Name="tModule" type="submenupresent"> <Menues> <Menu id="mPageConfig" implFunction="objPageName" xmlName="module_config" /> </Menues> </Tab> |

各配置字段的含义如下：

• id：菜单项唯一标识，同时通常作为多语言文案的key，用于匹配多语言文件中的菜单名称。

• implFunction：前端页面对象名，必须与JS控制器中定义的对象名（如上述示例中的objPageName）完全一致，否则无法实例化页面。

• xmlName：当前页面关联的业务模块名，必须与后端注册的模块名、数据模板XML的模块名一致，用于前后端数据交互时的模块匹配。

注意事项：implFunction、xmlName与对应模块的命名必须严格一致，否则会导致页面无法加载或数据交互失败；id需在多语言文件中配置对应的显示文案，确保菜单正常显示。

7. 步骤五：增加数据模板 XML

若新增页面需要读取或提交后端配置数据，必须定义对应的XML数据模板，该模板用于约定前后端数据交互的结构，明确数据的层级关系和字段名称，确保前后端数据解析一致。

数据模板XML的通用示例如下：

|----------------------------------------------------------------------------------------------------------------------------------------------|
| xml <?xml version="1.0" encoding="US-ASCII"?> <RGW> <module_config> <field1 /> <field2 /> <field3 /> </module_config> </RGW> |

数据模板的核心作用：

• 定义业务模块的数据结构，明确字段名称和层级关系。

• 约定前后端数据交互的格式，避免因数据结构不统一导致解析失败。

• 为页面表单字段提供统一的组织形式，方便数据的读取、回填和提交。

8. 步骤六：补充多语言文案

为实现系统的多语言适配，新增页面的所有文案（包括菜单名、页面标题、字段标签等）都需补充到多语言资源文件（properties格式）中，确保不同语言环境下页面文案正常显示。需补充的文案类型如下：

1. 菜单名称：对应菜单XML中id字段的值。

1. 页面标题：对应HTML中标题元素的文案。

1. 分组标题：页面中表单分组的标题文案。

1. 字段标签：输入控件对应的提示文案。

1. 下拉选项文案：select控件的选项内容。

1. 错误提示：表单校验失败时的提示文案。

1. 按钮文字：提交、取消等按钮的显示文案。

多语言文案的通用示例如下：

|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| properties tModule = Module mPageConfig = Configuration titlePageConfig = Configuration Page lGroupTitle = Basic Settings lField1 = Field 1 lField2 = Field 2 lErrorInvalid = Invalid value btUpdate = Save |

9. 步骤七：补充页面样式

新增页面时，应优先复用系统已有的全局样式（如表单样式、标题样式、按钮样式等），避免样式冗余和视觉不一致。仅在页面布局与全局样式存在差异时，补充少量页面专用样式，遵循以下建议：

• 优先复用全局样式，减少重复代码，降低维护成本。

• 页面专用样式仅用于解决布局差异，避免引入复杂、难维护的CSS代码。

• 样式命名遵循系统统一规范，确保代码可读性和可扩展性。

页面专用样式示例如下：

|------------------------------------------------------------------------------------------------|
| css .page-row { display: flex; flex-wrap: wrap; gap: 16px 24px; } .page-item { width: 180px; } |

10. 步骤八：后端注册模块处理函数

若新增页面需要读写后端数据，必须在后端注册对应的模块处理函数，用于接收前端的GET（读取数据）和SET（保存数据）请求，完成数据的读取与保存。后端模块注册通常采用数组形式，通用结构如下（以C语言为例）：

|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| c const struct applet_info g_webui_applets[] = { { .di_modname = "module_config", .di_version = 1, .di_handler_post_get_func = module_config_get, .di_handler_post_set_func = module_config_set, }, }; |

各字段含义如下：

• di_modname：业务模块名，必须与前端菜单配置中的xmlName、数据模板XML中的模块名完全一致，用于前后端模块匹配。

• di_version：模块版本号，用于版本管理和兼容性控制。

• di_handler_post_get_func：处理前端GET请求的函数，负责从后端配置源读取数据并组装XML返回给前端。

• di_handler_post_set_func：处理前端SET请求的函数，负责接收前端提交的XML数据、校验数据合法性并保存到配置源。

注意：若未注册后端模块处理函数，前端虽然能发送请求，但后端无法识别模块，导致数据读取或保存失败。