导出和发布流程 | HQ VISU Designer

当前官方规则是 1 PPT = 1 screen package。也就是说，一个 PPT 项目最终导出为一个画面包，这个包里包含页面文件、页级脚本、样式和图片资源。

导出后会看到 html、svg、js、json、img、manifest 等文件和目录。普通交付不要手工拆散这些文件，按一个画面包整体发布；排查页面缺文件时，再按目录名判断缺的是页面、图形、脚本、页级 JSON、图片还是清单。

<screen-package>/
  <page>.html
  <page>.svg
  css/
    app.css
  js/
    <page>.js
  json/
    global.json
    pages/
      <page>.json
  img/
    ...
  screen.manifest.json
  qtedit-export.manifest.json

当公共脚本、公共配置、共享样式、页面新增或删除、页面重命名、导航结构发生变化时，优先整包导出。只要变化影响多个页面或共享资源，就不要只替换单页。

整包导出适合首次发布、阶段性版本、正式交付、导航调整、页面增删、公共脚本调整、公共样式调整、共享图片更新和多页面联动更新。它的优势是边界完整，交付方和运行端都能按同一画面包处理。

完整画面包通常包含页面 HTML、页面 SVG、页面脚本、页级 JSON、公共样式、图片资源、资源清单、导出清单和运行所需配置。发布时应保持目录结构完整，不建议只挑选其中几个文件单独复制。

整包导出适合阶段性版本、正式交付、里程碑归档和宿主机整体替换。它相当于当前 PPT 项目的正式发布版本。

当前页图形调整、当前页脚本变化、当前页配置变化、当前页组件行为变化，这些都适合当前页导出。只要变化的边界没有越过当前页，就可以优先用它。

• 当前页图形变化
• 当前页脚本变化
• 当前页配置变化
• 当前页组件行为变化

当前页导出适合目标画面包已经存在，且本次只更新当前页自身资源的场景。例如修改单页布局、单页对象行为、单页脚本和单页图片。它不是独立发布包，而是对已有画面包的局部更新方式。

公共脚本、公共配置、共享样式、页面新增、页面删除、页面重命名、页面导航结构变化，这些都不属于单页边界。一旦碰到这些变化，就不要强行用当前页导出。

容易发生的误判是只看到页面内容变化，却忽略改动背后已经涉及全局配置。例如当前页调用了新的全局方法，或修改了公共翻译和公共样式，这种情况本质上已经不是纯单页变化。

应先确认本次变化是否只影响当前页自身的 html / svg / js 和图片资源。若无法明确确认，应优先整包导出。工业项目中，清晰的发布边界比减少一次导出操作更重要。

当前页导出后的文件应进入对应画面包的既有目录。交付前需要确认目标页面名称未变化、目标包版本一致、运行端引用的 screen code 未变化。若这些条件不能确认，应改用整包导出。

如果每次导出都重新选择目录，后续将难以区分预览包、正式包、上一版和回滚点。统一的导出路径和版本命名规则，可以显著提升交付可追溯性。

至少应区分预览导出和正式导出。预览导出适合内部确认和阶段性预览；正式导出适合交付和备份。建议进一步按日期、版本号或项目节点分目录，提升可追溯性。

目录名建议包含项目标识、画面包标识、日期时间和版本号，例如 ScreenCode_20260611_1530_v1.2.0。正式目录和预览目录保持分离，避免不同状态的文件混放。

当前页导出通常更适合在已经存在的目标画面包基础上做局部更新，不建议每次单独导出到全新目录后再人工合并文件。前提仍然是本次变化确实仅涉及单页。

Export History 只负责记录最近导出目录，便于快速回到常用位置。它不是版本管理器，也不会清理真实导出成果。清空历史记录不等于删除实际文件。

推荐方式是导出完整画面包，上传到宿主机，再由宿主机按包替换。该方式边界清晰，也更便于回滚和交付确认。

导出前应确认页面命名、页面层级、导航入口、模板变量、Tag 绑定、多语言文本、图片资源、报警范围、权限入口和输出目录。正式发布前还应确认本次变化是否触及公共资源或多页面资源。

画面包交给 HQControl 后，应在运行端确认画面包编码、菜单入口、页面访问路径、用户权限和关联设备范围。画面无法访问时，优先检查画面包编码、上传位置和菜单引用。

不建议在不清楚影响范围时手工复制少量导出文件。页面、脚本、样式和图片之间存在引用关系，缺失任一部分都可能影响运行端展示。需要局部替换时，应使用当前页导出或明确的包内资源替换规则。

不推荐长期将不同日期、不同状态的导出文件混放到同一目录；也不推荐依赖个人电脑本地路径或大量非统一路径支撑正式运行。此类做法会显著增加后续排查和回滚成本。

同一个画面包里的页面跳转优先使用 qtedit.openPage("PageName")；跨画面包跳转优先使用 qtedit.openScreen("SCREEN_CODE")；外部网站使用 qtedit.openWebsite(...)。跨包跳转不应写成相对磁盘路径。

检查页面范围是否正确、关键页面是否保存、模板和配置是否更新、当前导出方式是否符合这次发布目标。正式包应使用整包导出；仅针对单页确认的变更，可在边界明确时使用当前页导出。

优先判断本次变化是否已经越过当前页边界，例如公共脚本、公共配置、共享样式或导航结构发生变化。这些内容不应依赖当前页导出解决。

先确认 File / URL 指向的是当前画面包页面、相对文件还是外部网址，再看打开方式是框架内、全屏还是新标签。很多跳转问题都来自目标地址写错，或把外部网址当成本地文件处理。

通常不是导出工具的问题，而是导出目录和版本命名没有提前规划。没有清晰的导出版本，就算文件本身没问题，交付过程也容易乱。

如果无法明确确认本次变化只影响当前页，应改用整包导出。工业项目中，清晰的发布边界比减少一次导出操作更重要。