文档手册

画面与模板：让用户从菜单进到正确页面

进入“Screen Files / 画面文件”，先确认页面目录和待发布文件。页面资产来自设计和导出流程，进入 HQControl 后要检查入口文件、目录结构、发布时间和发布状态。除了在页面上传发布，也可以直接进画面运行目录，在磁盘上删除或替换画面文件，两种方式都行。

画面

画面: 画面与模板：让用户从菜单进到正确页面

画面文件决定有什么页面，菜单决定用户从哪里进，弹窗模板决定点设备后看到什么内容。三者配齐，运行端才像一个完整系统。

画面文件发布方式

先上传或确认导出的页面文件已经在待发布列表里。
也可以直接进画面运行目录，在磁盘上删除或替换对应画面文件。
检查入口页面、资源目录和依赖文件是否齐全。
点击发布后，查看最近记录确认发布成功。
发布后到运行端打开页面，确认页面可访问。

画面文件的运行目录在哪里

画面文件页会显示当前运行目录。上传按钮会把文件写入这个目录；菜单配置里的文件选择也从这个目录扫描。Linux 安装版默认是 /opt/hqcontrol/screens/assets，Windows 安装版默认是安装目录下的 screens\assets。不要把文件只放在解压出来的安装包目录里，服务已经安装后通常不会再读取安装包展开目录。

目录列表里的“根目录”就是画面运行目录本身，可以直接选择根目录上传。
上传文件夹时会保留文件夹内部结构，例如 5/css/app.css。
手动复制文件时，也要复制到页面显示的运行目录，而不是复制到安装包解压目录。
菜单配置找不到 HTML 时，先回画面文件页看运行目录和待发布文件是否一致。

# Linux 默认画面目录
/opt/hqcontrol/screens/assets

# Windows 默认画面目录
C:\HQCONTROL\screens\assets

菜单配置方法

进入“Menus / 菜单配置”，新增一级菜单或子菜单，把画面、报警、趋势或其他运行入口挂到运行端导航。一级菜单决定主要入口，子菜单决定更细的页面结构。

填写 code、name、多语言键、菜单类型、目标类型和目标引用。
目标类型选择画面文件时，列表来自画面运行目录下扫描到的 .html 文件。
选择图标，设置排序、是否可见、是否首页。
需要权限控制时填写权限编码，并确认角色里有对应权限。
保存后刷新运行端，用管理员和普通用户各打开一次。

弹窗模板配置范围

进入“Popup Templates / 弹窗模板”，选择已有模板或新增模板。弹窗模板用于定义设备或对象详情弹窗的内容结构，可组织设备信息、状态块、报警块、趋势块、控制块和实时预览。后台页面保存的是模板配置内容，不属于端口、数据库、Redis 或授权服务等运行配置项。

先确定模板服务哪一类对象，例如泵、阀、产线、设备单元。
把状态、报警、趋势和控制区域按现场使用顺序摆好。
绑定 Tag 时用完整点名或稳定对象标识，避免后期菜单和画面找不到。
保存后使用预览功能，并在运行端通过设备入口确认弹窗内容。

弹窗模板文件结构

每个弹窗模板是 configs/popup-templates/ 目录下的一个独立 JSON 文件，文件名用模板 ID（例如 1.json），文件内容就是这一个模板对象。常用字段包括 id、code、name、description、popupType、component、defaultTab、width、height、signalCategories、signalSuffixes、focusTagNames、sections、enabled。旧版本的单文件 popup-templates.json 升级后会自动拆成每个模板一个文件，原文件改名备份。

一个模板一个文件，文件名是模板 ID（如 1.json）；增删改某个模板时仅修改对应文件。
code 应保持唯一，作为模板识别编码。
width、height 控制弹窗默认尺寸。
signalCategories、signalSuffixes、focusTagNames 用于把模板与当前项目 Tag 命名规则关联起来。
sections 组织弹窗里的状态、报警、趋势、控制或自定义区域。
enabled 控制模板是否启用。

{
  "id": 1,
  "code": "...",
  "name": "...",
  "description": "...",
  "popupType": "...",
  "component": "...",
  "defaultTab": "...",
  "width": 960,
  "height": 640,
  "signalCategories": [],
  "signalSuffixes": [],
  "focusTagNames": [],
  "sections": [],
  "enabled": true
}

跨项目迁移快捷弹窗

从其他项目迁移弹窗模板时，直接把对应模板的那个 JSON 文件复制到当前项目 configs/popup-templates/ 目录即可。复制后重启 HQControl 服务，或进入后台弹窗模板页面保存一次，让后台接管维护。

迁移前先确认模板的 code 在当前项目里唯一，文件名（模板 ID）不要和已有文件冲突。
signalSuffixes 和 focusTagNames 要与当前项目 Tag 命名匹配。
复制整个模板文件，不要只复制 sections 或局部字段。
只复制需要的模板文件，不要把其他项目的无关模板一起带过来。
模板文件是配置文件，不是数据库表，也不是运行配置项文件。

PPT 画面弹窗与报警范围对应关系

PPT 导出的页面会把页级报警和弹窗范围写成 JSON。HQControl 按字段语义读取这些范围，不会把整页所有 Tag 都塞进弹窗。被点击组件关联的 Tag、页面报警设置和弹窗配置关联的 Tag 会共同决定当前弹窗诊断范围。范围和菜单、弹窗、声音报警统一用“设备.组”写法：除 plcCodes 只填设备外，tags 和各分组都要绑定到具体设备。

showWindow：当前页是否允许显示报警窗口。
tags：具体完整点名，写成“设备编码.Tag编码”，适合只看几个确定点位。
plcCodes：设备 / PLC 编码，例如 DK、PLC01（只填设备，不加点）。
functionGroupCodes：功能组，写成“设备编码.功能组”，例如 DK.产线A。
deviceGroupCodes：设备组 / 对象，写成“设备编码.设备组”，例如 DK.Pump01。
signalGroupCodes：信号组，写成“设备编码.信号组”，例如 DK.status。
数组为空表示该维度不附加范围条件，不表示自动选择全部点位。

{
  "showWindow": true,
  "tags": [],
  "plcCodes": [],
  "functionGroupCodes": [],
  "deviceGroupCodes": [],
  "signalGroupCodes": []
}

画面交付要检查什么

确认页面文件已发布，菜单目标能打开，弹窗模板能预览，模板里的 Tag 引用能找到主数据，权限编码没有把普通用户挡在入口外。正式交付前最好用非管理员账号走一遍运行端入口。

运行端首页是否进入正确页面。
每个菜单是否能打开对应画面。
每个设备弹窗是否能正常打开并显示实时值。
普通用户是否只能看到自己有权限的入口。

HQControl 画面文件页面 — **图示 1: 画面文件**
画面文件页用于确认页面目录、待发布文件和最近发布记录。

HQControl 菜单配置页面 — **图示 2: 菜单配置**
菜单配置决定运行端导航入口、页面目标、排序、可见性、首页和权限控制。

HQControl 弹窗模板页面 — **图示 3: 弹窗模板**
弹窗模板用于统一设备详情、报警、趋势和控制面板结构，并支持实时预览。

HQControl 运行端弹窗示例 — **图示 4: 运行端弹窗**
弹窗模板发布后，应在运行端从菜单或对象入口打开，确认实时值、权限和关闭行为。

HQControl 弹窗模板运行示例 — **图示 5: 弹窗实例**
弹窗实例用于验证模板参数、设备上下文和状态字段是否按当前对象传入。