matlab-generate-report

MATLAB 报告生成

根据 MATLAB 数据和 Simulink 模型生成结构清晰、专业的报告（PDF、Word、HTML）。

适用场景

• 根据 MATLAB 数据创建 PDF、Word 或 HTML 报告
• 创建包含章节、标题页和目录的报告
• 为文档中的图和表添加自动编号
• 创建多页 HTML 报告（多个带导航的独立 HTML 文件）
• 使用框图、I/O 表和执行顺序记录 Simulink 模型
• 自定义报告模板（样式、颜色、字体、页眉、页脚）
• 使用模板占位符和动态内容创建自定义报告器类
• 创建共享公司样式的多报告器包
• 创建具有不同表头颜色的表格变体报告器
• 在报告中包含 HTML 内容

不适用场景

• 简单的文件导出（CSV、Excel）——使用 writetable、writematrix
• 将 Live Scripts 用作报告——使用 MATLAB Live Editor 导出
• 交互式报告创建——使用 Report Explorer GUI
• Simulink 模型的 Web 视图——直接使用 slreportgen.webview.*

API 选择

始终使用 Report API（mlreportgen.report.*）作为基础。它提供 Report 容器和报告器（Figure、BaseTable、FormalImage、Chapter、TitlePage 等），用于处理自动编号、标题和文档结构。

结合使用两个 API。 使用 Report API 创建报告，并添加已有报告器支持的内容。使用 DOM API（mlreportgen.dom.*）添加带样式的段落、自定义表格、内联格式、HTML 内容以及不带标题的图像。DOM 对象可以与报告器一起直接追加到 Report、Chapter 或 Section 中。

重要规则： Report API 报告器（Figure、BaseTable、FormalImage）只能追加到 Report、Chapter 或 Section 对象中，不能追加到 TableEntry 等 DOM 对象中。在 TableEntry 中使用 DOM 对象。

Simulink 报告： 使用 slreportgen.report.Report（而非 mlreportgen.report.Report）——它扩展了基础类，并提供 SystemIO、ExecutionOrder 及其他 Simulink 报告器所需的模型编译支持。

多页 HTML： 使用 "html-multipage" 类型的 mlreportgen.dom.Document，并搭配 HTMLPage 对象。这是唯一需要使用 DOM Document 而非 Report API Report 的场景。

核心工作流：标准报告

TitlePage、TableOfContents、ListOfFigures 和 ListOfTables 均为可选项——仅在任务需要时添加。最精简的报告只需 Report、内容和 close。

import mlreportgen.report.*
import mlreportgen.dom.*

rpt = Report("MyReport","pdf");
append(rpt,TitlePage(Title="Report Title",Author="Team"));  % optional
append(rpt,TableOfContents());   % optional
append(rpt,ListOfFigures());     % optional
append(rpt,ListOfTables());      % optional

ch = Chapter("Results");
append(ch,Paragraph("Analysis complete."));

% Auto-numbered table
data = FormalTable(["ID","Value"],[1 10; 2 20]);
bt = BaseTable(data);
bt.Title = "Measured values";
append(ch,bt);

% Auto-numbered figure
fig = figure("Visible","off");
plot([1 2],[10 20]);
rptFig = Figure(fig);
rptFig.Snapshot.Caption = "Value trend";
append(ch,rptFig);
close(fig);

append(rpt,ch);
close(rpt);
rptview(rpt);

核心工作流：Simulink 报告

load_system(modelName);

% MUST use slreportgen.report.Report for Simulink content
rpt = slreportgen.report.Report(outputPath,"pdf");
append(rpt,mlreportgen.report.TitlePage("Title","Model Report"));
append(rpt,mlreportgen.report.TableOfContents());

ch = mlreportgen.report.Chapter("Diagrams");

% Root diagram — direct reporter
rootDiag = slreportgen.report.Diagram(modelName);
rootDiag.Snapshot.ScaleToFit = true;
append(ch,rootDiag);

% Subsystems — finder pattern (iterator for memory efficiency)
finder = slreportgen.finder.SystemDiagramFinder(modelName);
finder.IncludeRoot = false;
finder.SortType = "alphabetical";

while finder.hasNext()
    result = finder.next();
    sec = mlreportgen.report.Section("Title",result.Name);
    append(sec,result);
    append(ch,sec);
end

append(rpt,ch);
close(rpt);
rptview(rpt);

选择内置还是自定义报告器

编写代码前，请根据内置报告器的功能分析需求：

1. 列出所有内容和格式要求——标题页字段、页面边框、页眉/页脚、品牌样式
2. 检查内置报告器。 内置的 TitlePage 包含：Title、Subtitle、Author、Publisher、PubDate、Image。内置的 Chapter/Section 提供标题、自动编号和 Content 插槽。
3. 如果内置报告器满足所有要求，请直接使用
4. 如果有任何要求未满足，请创建自定义报告器：
   • 单个自定义报告器——参阅 references/custom-reporters.md
   • 多个共享视觉标识的报告器——参阅 references/report-package.md

常见的自定义报告器使用场景：

• 标题页需要标准字段集之外的字段（项目名称、设施、合同编号）
• 页面边框、水印或自定义页面布局
• 包含动态内容的页眉/页脚（每章配图、滚动信息条）
• 采用不同标题颜色的品牌化表格变体
• 使用 MATLAB 生成徽标（通过 plot/patch 绘制几何图形，再用 exportgraphics 导出）

不要强行将需求塞入内置属性（例如，将多个字段拼接到 Subtitle 中）。请改为创建自定义报告器。

不要使用原始 DOM 元素（追加到 Chapter 的 Paragraph、Image）构建自定义标题页。请始终使用 customizeReporter 实现基于模板的布局和格式可移植性。

决策树：我需要哪份参考资料？

我需要……	参考资料
构建包含章节、图、表和验证内容的标准报告	references/report-api-patterns.md
使用 DOM 表格、HTML 包含、多页 HTML、Number/NumberFormat	references/dom-api-patterns.md
了解模板文件类型、查找/检查模板	references/template-system.md
查阅内置模板插槽、样式和页面布局（预先计算）	references/template-reference.md
创建自定义报告器类（customizeReporter、插槽、页眉）	references/custom-reporters.md
构建共享样式并使用 buildTemplates 的多报告器包	references/report-package.md
生成 Simulink 模型报告（查找器、方向、居中）	references/simulink-report.md
查阅所有 Simulink 查找器和报告器	references/finders-and-reporters.md
使用自定义报告器将结构体数组迭代为章节	references/data-driven-report-pattern.md
编辑模板样式（颜色、字体、页眉、页脚、目录）	references/template-system.md

主要功能

类	用途	包
Report	顶层报告容器	mlreportgen.report
TitlePage	包含标题、副标题和作者的标题页	mlreportgen.report
TableOfContents	自动生成的目录	mlreportgen.report
Chapter / Section	文档结构	mlreportgen.report
Figure	根据 MATLAB 图窗自动编号的图	mlreportgen.report
FormalImage	根据文件创建带标题的自动编号图像	mlreportgen.report
BaseTable	自动编号的表格封装器（传入 FormalTable）	mlreportgen.report
FormalTable	由单元格数组构成的含表头、表体和表尾的表格	mlreportgen.dom
Template（3 个参数）	编辑模板：Template(out,fmt,src)	mlreportgen.dom
HTMLFile / HTML	在任意输出格式中包含 HTML 内容	mlreportgen.dom
HTMLPage	多页 HTML 文档中的页面（R2024a+）	mlreportgen.dom
Number	数值 DOM 对象（与 NumberFormat 配合使用）	mlreportgen.dom
TemplateHole	在生成报告时填充的占位符	mlreportgen.dom
Page / NumPages	页码 / 总页数	mlreportgen.dom
*.customizeReporter	搭建自定义报告器及模板	mlreportgen.report
getStyle / replaceStyle	修改模板样式	mlreportgen.dom
slreportgen.report.Report	用于 Simulink 内容的报告容器	slreportgen.report
slreportgen.report.Diagram	系统的图示快照	slreportgen.report
slreportgen.finder.SystemDiagramFinder	查找系统/子系统图示	slreportgen.finder
slreportgen.report.SystemIO	报告输入/输出（需要编译）	slreportgen.report
slreportgen.report.ExecutionOrder	报告模块执行顺序	slreportgen.report
slreportgen.report.LookupTable	报告查找表数据和图表	slreportgen.report
rptview	显示报告（更新 DOCX 字段）	函数
docview	处理 Word 文档（更新字段、转换）	函数

常见错误

易犯错误	正确做法
使用 mlreportgen.dom.Document 作为报告容器	使用 mlreportgen.report.Report。例外：多页 HTML 需要使用 "html-multipage" 的 Document
使用 mlreportgen.report.Report 处理 Simulink 内容	使用 slreportgen.report.Report——模型编译需要它
使用 "html" 的 Report 输出多页内容	使用 "html-multipage" 的 mlreportgen.dom.Document + HTMLPage 对象
将报告器追加到 DOM 对象（Paragraph、TableEntry）	报告器只能放在 Report、Chapter 或 Section 中。在 TableEntry 内使用 DOM 对象
在 FormalTable 单元格中放入原始 double 值	使用带有 Style 中 NumberFormat 的 Number：n = Number(42); n.Style = {NumberFormat("%.0f")}。将 n 直接放入单元格数组中。参见 references/dom-api-patterns.md § Number and NumberFormat
使用 NumberFormat("$%.0f") 或 NumberFormat("%,.0f")	仅支持标准 sprintf 格式说明符（不支持 $、%,、%d）。对于货币或单位，将 Number 包装在 Paragraph 中，并在前面或后面添加 Text
只自定义 "default"/"even" 页面页眉	自定义所有页面类型："first"、"default"、"even"——但要区分内容（见下文）
在首页页眉中放入 StyleRef（章节标题）	首页已显示章节标题——从 "first" 页眉中省略 StyleRef。仅在 "default"/"even" 中使用它来辅助导航
使用 winopen/open/start 打开 DOCX	使用 rptview(rpt) 或 docview(file,"updatefields")——触发字段更新
使用 ColSpec/ColSpecGroup 设置宽度	使用 TableColSpecGroup + TableColSpec，并在 Style 中设置 Width
设置宽度时未使用 ResizeToFitContents(false)	在表格 Style 中添加 ResizeToFitContents(false)；设置绝对值 ft.Width（而不是 "100%"）
使用 TemplateParagraphStyle.Formats = {Bold(true)}	使用数组：Formats = [Bold(true),FontSize("12pt")]
使用 Template(path,"pdf") 编辑现有模板	双参数形式会创建空白模板。使用三参数形式：Template(out,"pdf",src)
Template 构造函数的源路径与输出路径相同	OPC 无法同时读写。使用不同路径，然后调用 movefile
设置 PDFPageLayout.PageSize.Orientation 时未调用 rotate()	调用 rotate(pl)——它会交换 Width/Height 并设置 Orientation
使用 DOCXPageLayout 时未显式设置 Height 和 Width	DOCX 不会自动交换宽高——请同时显式设置二者
使用 PDFPageLayout 后页码重置	设置 pl.FirstPageNumber = ''（空字符串）以继续编号
将报告器包装在 Paragraph 中以使其居中	通过 Template API 自定义报告器的模板样式
使用 RawText(html) 将 HTML 用于 PDF	使用 HTMLFile(path) 或 HTML(string)——适用于任何格式
在 Table 单元格数组中使用 Group	使用嵌套单元格数组：Table({{img,caption},desc})
将 MATLAB table() 传给 BaseTable	传入 FormalTable(headers,body)——避免使用 MATLABTable 包装器
e.Style = {BackgroundColor("yellow")}（会覆盖现有样式）	追加：e.Style = [e.Style, {BackgroundColor("yellow")}]——保留继承的样式
强行将字段塞入 TitlePage.Subtitle	通过 customizeReporter 创建自定义标题页报告器
从头编写自定义报告器类	使用 customizeReporter 搭建框架——它会创建所需的二进制模板
在运行 customizeReporter 前编写 classdef	搭建框架时会覆盖 classdef 文件。先搭建框架，再编辑
在包中使用未限定的 TitlePage.getClassFolder()	使用完全限定名称：mypkg.TitlePage.getClassFolder()
对 PDF/HTML 使用 getStyle(ss,name,type)	type 参数会返回 []。使用不带 type 的 getStyle(ss,name)
使用 OuterMargin("12pt","6pt","0","0") 设置垂直间距	参数顺序为 (left,right,top,bottom)——与 CSS 顺序不同。使用 OuterMargin("0","0","12pt","6pt") 设置顶部/底部间距
使用 TemplateCharacterStyle	该类型不存在。对 PDF/HTML 中的字符/内联样式使用 TemplateTextStyle
解压 .pdftx/.htmtx/.dotx，并使用 fileread/regexprep 进行编辑	始终使用 DOM Template API——Template(out,fmt,src) + open + 修改对象 + close。直接编辑原始文件会绕过框架验证
使用 find_system + DiagramFinder 进行发现	使用带有筛选属性的 SystemDiagramFinder
对 ChartDiagramFinder 的结果调用 Diagram(result.Path)	使用 getReporter(result)——图表路径对 Diagram 构造函数无效
在查找器上使用 find() + for 循环	始终使用迭代器：while finder.hasNext() / result = finder.next()
使用 BlockFinder 并设置 SearchDepth=inf，期望找到引用模型	BlockFinder 不会遍历 Model Reference。使用 SystemDiagramFinder（IncludeReferencedModels=true）+ 针对每个系统的 BlockFinder（SearchDepth=1）
在虚拟子系统上使用 ExecutionOrder	先检查 get_param(obj,'IsSubsystemVirtual')
在 Simulink Functions 上使用 ExecutionOrder/SystemIO	使用 slreportgen.utils.isSimulinkFunction(result.Object) 进行保护

约定

• 追加完所有内容后，务必执行 close(rpt) — 生成输出文件
• 始终使用 rptview 或 docview 打开 DOCX — 切勿使用 winopen 或 open
• 绘制用于报告的图表时，使用 figure("Visible","off")
• 将图表保存到文件时，使用 exportgraphics（而非 print）
• 每章使用一个编号范围 — 图表按“章-序号”编号（例如，“Figure 2-1”）
• BaseTable 封装 FormalTable — 传入 FormalTable(headers,body)，不要传入 MATLAB table()
• **单元格级样式：**构造完成后使用 entry(t,row,col)，不要在构造过程中使用
• 模板样式使用 [] 数组；内联 .Style 属性使用 {}
• Reporter 位于 @ClassName 目录中 — 每个目录都需要自己的 resources/templates/
• 编辑前先搭建所有 Reporter — customizeReporter 会创建二进制模板并覆盖 classdef
• 搭建后修正未限定的类名 — 使用带包名限定的类名
• 自定义所有输出格式 — PDF/Word/HTML 模板彼此独立
• **Simulink：**始终使用 slreportgen.report.Report；始终设置 Diagram.Snapshot.ScaleToFit = true
• **Simulink 查找器：**对 get_param 使用 .Object 句柄（而非路径字符串）；标题使用 result.Name
• JSON 是多 Reporter 包的唯一真实来源 — 切勿将样式值硬编码

查看和处理报告

rptview(rpt);                           % Open in system viewer (updates DOCX fields)
rptview("MyReport.docx","pdf");         % Convert DOCX to PDF via Word
docview("Report.docx","updatefields","closedoc","closeapp");  % Update without display

**验证：**运行时没有报错并不能确认结果正确。执行 close(rpt) 后：

• 检查 isfile(rpt.OutputPath) 和 dir(rpt.OutputPath).bytes > 1000
• 对于 PDF：调用 open(rpt)，然后在追加内容前设置 rpt.Document.RetainFO = true，并搜索 *_FO/*.fo 文件
• 对于 DOCX：解压并搜索 word/document.xml
• 断言输出中包含预期的标题、章节标题和题注

完整的验证模式请参见 references/report-api-patterns.md。

所需工具箱

MATLAB Report Generator（使用 mcp__matlab__detect_matlab_toolboxes 验证）。Simulink 模型报告还需要 Simulink Report Generator。

---

版权所有 2026 The MathWorks, Inc.

---