导出和发布流程 | Mingcedar Studio

<section id="preface" class="docs-block docs-block-intro"> <span class="section-kicker">导出</span> <h2>使用前说明</h2> <p>导出是页面从设计态进入交付态的正式步骤。只要提前明确导出边界，页面替换、资源更新和发布影响范围都能更清楚。</p> <div class="docs-task-grid"> <article id="preface-item-1" class="docs-task-card"> <span>导出</span> <strong>最核心的一条规则</strong> <p>当前产品的正式交付单位是画面包，不是零散文件。也就是 1 个 PPT 对应 1 个 screen package。这个认识一旦建立，后面的整包导出和当前页导出就会更好理解。</p> </article><article id="preface-item-2" class="docs-task-card"> <span>导出</span> <strong>为什么还要支持当前页导出</strong> <p>实际项目中不应每次小范围修改都进行整包替换。当前页导出用于局部迭代和页级替换，但它有明确边界：只能处理属于当前页的变化。</p> </article><article id="preface-item-3" class="docs-task-card"> <span>导出</span> <strong>阅读重点</strong> <p>正式发布流程优先阅读整包导出和发布规则；单页替换优先阅读当前页导出边界；目录规划优先阅读导出位置和版本建议。</p> </article> </div> </section> <section id="package-structure" class="docs-block"> <span class="section-kicker">结构</span> <h2>整包导出：交付内容与目录结构</h2> <p>整包导出会把当前 PPT 对应的页面、脚本、样式和图片一起整理成正式画面包。</p> <div class="docs-detail-list"> <article id="package-structure-item-1" class="docs-detail-row"> <strong>整包导出的核心规则</strong> <p>一个 PPT 项目导出为一个画面包，包含页面文件、页级脚本、样式和图片资源。</p> </article><article id="package-structure-item-2" class="docs-detail-row"> <strong>典型目录结构说明</strong> <p>导出后会看到 html、svg、js、img 和导出清单等文件。普通交付不要手工拆散这些文件，按一个画面包整体发布；排查页面缺文件时，再判断缺的是页面、图形、脚本、图片还是清单。</p> <pre class="docs-code-block"><code>&lt;screen-package&gt;/

&lt;page&gt;.html

&lt;page&gt;.svg

js/

hq-pagemap.js

&lt;page&gt;.js

img/

...

hqVisuDesigner-export-report.json</code></pre> </article><article id="package-structure-item-3" class="docs-detail-row"> <strong>整包导出的优先场景</strong> <p>当共享样式、页面新增或删除、页面重命名、导航结构发生变化时，优先整包导出。只要变化影响多个页面或共享资源，就不要只替换单页。</p> </article><article id="package-structure-item-4" class="docs-detail-row"> <strong>整包导出适用范围</strong> <p>整包导出适合首次发布、阶段性版本、正式交付、导航调整、页面增删、公共样式调整、共享图片更新和多页面联动更新。它的优势是边界完整，交付方和运行端都能按同一画面包处理。</p> </article><article id="package-structure-item-5" class="docs-detail-row"> <strong>整包里通常包含什么</strong> <p>完整画面包通常包含页面 HTML、页面 SVG、页面脚本、页级 JSON、公共样式、图片资源、资源清单、导出清单和运行所需配置。发布时应保持目录结构完整，不建议只挑选其中几个文件单独复制。</p> </article><article id="package-structure-item-6" class="docs-detail-row"> <strong>整包导出的项目价值</strong> <p>整包导出适合阶段性版本、正式交付、里程碑归档和宿主机整体替换。它相当于当前 PPT 项目的正式发布版本。</p> </article> </div> <div class="docs-note-grid"> <figure id="package-structure-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ExportFolderDialog.png" alt="整包导出" loading="lazy" decoding="async"> <figcaption> <strong>整包导出</strong> <p>正式发布、版本归档和完整交付时，应优先使用整包导出。</p> </figcaption> </figure> </div> </section><section id="current-page" class="docs-block"> <span class="section-kicker">单页</span> <h2>当前页导出：只在“这次变化只属于这一页”时使用</h2> <p>当前页导出不是缩水版整包导出，而是面向页级更新的明确工具。用对了会很高效，用错了就会觉得“为什么有些变化没带上”。</p> <div class="docs-detail-list"> <article id="current-page-item-1" class="docs-detail-row"> <strong>当前页导出适合哪些变化</strong> <p>当前页图形调整、当前页脚本变化、当前页配置变化、当前页组件行为变化，这些都适合当前页导出。只要变化的边界没有越过当前页，就可以优先用它。</p> <ul> <li>当前页图形变化</li><li>当前页脚本变化</li><li>当前页配置变化</li><li>当前页组件行为变化</li> </ul> </article><article id="current-page-item-2" class="docs-detail-row"> <strong>当前页导出适用范围</strong> <p>当前页导出适合目标画面包已经存在，且本次只更新当前页自身资源的场景。例如修改单页布局、单页对象行为、单页脚本和单页图片。它不是独立发布包，而是对已有画面包的局部更新方式。</p> </article><article id="current-page-item-3" class="docs-detail-row"> <strong>哪些变化不适合当前页导出</strong> <p>公共脚本、公共配置、共享样式、页面新增、页面删除、页面重命名、页面导航结构变化，这些都不属于单页边界。一旦碰到这些变化，就不要强行用当前页导出。</p> </article><article id="current-page-item-4" class="docs-detail-row"> <strong>单页替换的常见误判</strong> <p>容易发生的误判是只看到页面内容变化，却忽略改动背后已经涉及全局配置。例如当前页调用了新的全局方法，或修改了公共翻译和公共样式，这种情况本质上已经不是纯单页变化。</p> </article><article id="current-page-item-5" class="docs-detail-row"> <strong>单页替换的正确思路</strong> <p>应先确认本次变化是否只影响当前页自身的 html / svg / js 和图片资源。若无法明确确认，应优先整包导出。工业项目中，清晰的发布边界比减少一次导出操作更重要。</p> </article><article id="current-page-item-6" class="docs-detail-row"> <strong>当前页导出后的交付边界</strong> <p>当前页导出后的文件应进入对应画面包的既有目录。交付前需要确认目标页面名称未变化、目标包版本一致、运行端引用的 screen code 未变化。若这些条件不能确认，应改用整包导出。</p> </article> </div> <div class="docs-note-grid"> <figure id="current-page-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ExportFolderDialog.png" alt="当前页导出" loading="lazy" decoding="async"> <figcaption> <strong>当前页导出</strong> <p>单页导出适合局部迭代，前提是变化边界确实只在当前页。</p> </figcaption> </figure> </div> </section><section id="export-location" class="docs-block"> <span class="section-kicker">目录</span> <h2>导出位置与版本管理：区分预览导出和正式导出</h2> <p>导出目录规划会直接影响后续替换、回滚和版本交付。</p> <div class="docs-detail-list"> <article id="export-location-item-1" class="docs-detail-row"> <strong>为什么导出目录要提前定规则</strong> <p>如果每次导出都重新选择目录，后续将难以区分预览包、正式包、上一版和回滚点。统一的导出路径和版本命名规则，可以显著提升交付可追溯性。</p> </article><article id="export-location-item-2" class="docs-detail-row"> <strong>目录划分建议</strong> <p>至少应区分预览导出和正式导出。预览导出适合内部确认和阶段性预览；正式导出适合交付和备份。建议进一步按日期、版本号或项目节点分目录，提升可追溯性。</p> </article><article id="export-location-item-3" class="docs-detail-row"> <strong>导出目录命名</strong> <p>目录名建议包含项目标识、画面包标识、日期时间和版本号，例如 ScreenCode_20260611_1530_v1.2.0。正式目录和预览目录保持分离，避免不同状态的文件混放。</p> </article><article id="export-location-item-4" class="docs-detail-row"> <strong>当前页导出目录选择</strong> <p>当前页导出通常更适合在已经存在的目标画面包基础上做局部更新，不建议每次单独导出到全新目录后再人工合并文件。前提仍然是本次变化确实仅涉及单页。</p> </article><article id="export-location-item-5" class="docs-detail-row"> <strong>Export History 的作用</strong> <p>Export History 只负责记录最近导出目录，便于快速回到常用位置。它不是版本管理器，也不会清理真实导出成果。清空历史记录不等于删除实际文件。</p> </article> </div> <div class="docs-note-grid"> <figure id="export-location-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ExportHistoryForm.png" alt="导出位置设置" loading="lazy" decoding="async"> <figcaption> <strong>导出位置设置</strong> <p>统一导出目录规则比记忆单次路径更重要，尤其适用于多人协作和长期迭代项目。</p> </figcaption> </figure> </div> </section><section id="release-rules" class="docs-block"> <span class="section-kicker">发布</span> <h2>发布规则：正式交付优先整包，局部调整才考虑页级替换</h2> <p>本节说明如何将导出内容交给宿主机，以及哪些发布方式不建议使用。</p> <div class="docs-detail-list"> <article id="release-rules-item-1" class="docs-detail-row"> <strong>推荐发布方式</strong> <p>推荐方式是导出完整画面包，上传到宿主机，再由宿主机按包替换。该方式边界清晰，也更便于回滚和交付确认。</p> </article><article id="release-rules-item-2" class="docs-detail-row"> <strong>导出前检查清单</strong> <p>导出前应确认页面命名、页面层级、导航入口、模板变量、Tag 绑定、多语言文本、图片资源、报警范围、权限入口和输出目录。正式发布前还应确认本次变化是否触及公共资源或多页面资源。</p> </article><article id="release-rules-item-3" class="docs-detail-row"> <strong>导出后接入流程</strong> <p>画面包交给 Mingcedar 后，应在运行端确认画面包编码、菜单入口、页面访问路径、用户权限和关联设备范围。画面无法访问时，优先检查画面包编码、上传位置和菜单引用。</p> </article><article id="release-rules-item-4" class="docs-detail-row"> <strong>资源替换边界</strong> <p>不建议在不清楚影响范围时手工复制少量导出文件。页面、脚本、样式和图片之间存在引用关系，缺失任一部分都可能影响运行端展示。需要局部替换时，应使用当前页导出或明确的包内资源替换规则。</p> </article><article id="release-rules-item-5" class="docs-detail-row"> <strong>不推荐的方式</strong> <p>不推荐长期将不同日期、不同状态的导出文件混放到同一目录；也不推荐依赖个人电脑本地路径或大量非统一路径支撑正式运行。此类做法会显著增加后续排查和回滚成本。</p> </article><article id="release-rules-item-6" class="docs-detail-row"> <strong>同包跳转和跨包跳转写法</strong> <p>同包跳转用 hqVisuDesigner.openPage(&quot;PageName&quot;)，跨包用 hqVisuDesigner.openScreen(&quot;SCREEN_CODE&quot;)，外部站点用 hqVisuDesigner.openWebsite(...)。跨包目标不能使用相对磁盘路径。</p> </article><article id="release-rules-item-7" class="docs-detail-row"> <strong>正式交付前最后一遍自查</strong> <p>检查页面范围是否正确、关键页面是否保存、模板和配置是否更新、当前导出方式是否符合这次发布目标。正式包应使用整包导出；仅针对单页确认的变更，可在边界明确时使用当前页导出。</p> </article> </div> </section><section id="common-questions" class="docs-block"> <span class="section-kicker">排查</span> <h2>导出相关的常见误区和排查思路</h2> <p>很多导出问题并非导出器异常，而是导出边界理解错了。</p> <div class="docs-detail-list"> <article id="common-questions-item-1" class="docs-detail-row"> <strong>为什么当前页导出后，某些变化没有带上</strong> <p>优先判断本次变化是否已经越过当前页边界，例如公共脚本、公共配置、共享样式或导航结构发生变化。这些内容不应依赖当前页导出解决。</p> </article><article id="common-questions-item-2" class="docs-detail-row"> <strong>为什么宿主机里页面跳转不对</strong> <p>先确认 File / URL 指向的是当前画面包页面、相对文件还是外部网址，再看打开方式是框架内、全屏还是新标签。很多跳转问题都来自目标地址写错，或把外部网址当成本地文件处理。</p> </article><article id="common-questions-item-3" class="docs-detail-row"> <strong>为什么交付后很难回滚</strong> <p>通常不是导出工具的问题，而是导出目录和版本命名没有提前规划。没有清晰的导出版本，就算文件本身没问题，交付过程也容易乱。</p> </article><article id="common-questions-item-4" class="docs-detail-row"> <strong>边界判断原则</strong> <p>如果无法明确确认本次变化只影响当前页，应改用整包导出。工业项目中，清晰的发布边界比减少一次导出操作更重要。</p> </article> </div> <div class="docs-note-grid"> <figure id="common-questions-image-1" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/current-20261021/batch-replace.png" alt="批量替换" loading="lazy" decoding="async"> <figcaption> <strong>导出前整理</strong> <p>先核对 Scope、Categories 和 Replacement preview；当前界面图列出可搜索项，点击 Replace 后才会修改 PPT。</p> </figcaption> </figure><figure id="common-questions-image-2" class="docs-note-card manual-doc-image-card"> <img src="/WEB_img/HQPPT/ExportProgressForm.png" alt="导出进度" loading="lazy" decoding="async"> <figcaption> <strong>导出进度</strong> <p>导出中关注当前步骤和结果提示；失败时保留 PPT 和输出目录，便于复现与排查。</p> </figcaption> </figure> </div> </section>