什么是报告器？

报告器是 MATLAB^® 对象，当添加到 MATLAB Report Generator™ 报告对象时会生成格式化的内容。MATLAB Report Generator 提供用于生成常见报告组件的报告器，例如标题页、目录、章节、小节、图窗和 MATLAB 变量值。您可以自定义这些报告器的内容和外观。您还可以创建自己的报告器。要获取内置报告 API 对象的列表，请输入此 MATLAB 命令：

help mlreportgen.report

报告器和 DOM 对象

除了报告器之外，MATLAB Report Generator 还提供了另一组用于生成报告内容的对象。这些对象是文档对象模型 (DOM) 对象。它们实现了 HTML、Word 和其他文档创建软件使用的文档模型。该模型将文档定义为文档中常见的对象的层次结构，例如文本字符串、段落、图像和表格。DOM API 包含生成这些基本文档对象的软件对象。要获取 DOM 对象的列表，请输入此 MATLAB 命令：

help mlreportgen.dom

相比之下，报告器创建高级文档结构，例如标题页、目录和章节，这些结构出现在许多但并非所有类型的文档中。报告器的优势在于单个报告器可以创建需要许多 DOM 对象的内容。然而，报告生成器程序通常需要 DOM 和报告器对象。例如，章节报告器会生成报告章节的标题和页面布局，但不生成其内容。DOM API 提供文本、段落、表格、列表、图像和其他对象，您可以使用它们来创建报告器内容。

以下 MATLAB 程序说明如何使用报告器和 DOM 对象来创建 PDF 报告。该程序使用 DOM Text 对象向章添加模块文本。本例中的所有其他对象（Report、TitlePage、TableOfContents 和 Chapter）都是报告对象。

rpt = mlreportgen.report.Report('myreport','pdf');
append(rpt,mlreportgen.report.TitlePage('Title','My Report',...
   'Author','Myself'))
append(rpt,mlreportgen.report.TableOfContents)
ch = mlreportgen.report.Chapter('Title','Sample Text');
append(ch,mlreportgen.dom.Text...
   ('Here is sample text using a DOM Text object.'))
append(rpt,ch)
close(rpt)
rptview(rpt)

Title page of the report with the title "My Report", the author "Myself", and the date

Table of contents listing one chapter

Chapter one has the title "Sample Text" and the text, "here is sample text using a DOM Text object".

报告元素

报告通常包括以下要素：

定义报告器生成的动态内容的外观、固定内容和空位的模板文档。报告器通常会提供一组模板文件，每个模板文件对应一个支持的输出类型：Word、PDF 和 HTML。每个模板文件都包含一个模板库，供报告器格式化其内容。例如，报告 API TitlePage 报告器使用名为 TitlePage 的模板来格式化标题页。TitlePage 模板存储在其模板文件的模板库中。您可以修改此模板来重新排列或向标题页添加内容。有关信息，请参阅模板。
指定报告器生成的动态内容的属性。这些属性与报告模板中的空位相对应。报告器用相应属性的值填充模板空位。
MATLAB 类定义用于创建和操作报告器的报告器属性和方法。报告类名称以前缀 mlreportgen.report 开头。例如，标题页报告器是 mlreportgen.report.TitlePage 。您可以通过在脚本或函数的开头插入此语句来省略 MATLAB 脚本或函数中的前缀：
```
import mlreportgen.report.*
```
同样，您可以包含 import mlreportgen.dom.* 来使用短 DOM 类名。
构造方法创建一个报告器对象作为报告器类的实例。构造函数的名称与类的名称相同。
包含报告生成的内容的 DOM 对象。这个对象被称为报告器的实现。每个报告器都有一个 getImpl 方法来创建实现对象，该对象通常是一个 DOM DocumentPart 对象。

在 MATLAB 程序中使用报告器

要在报告程序中生成内容，请按照以下步骤操作：

这些步骤中描述的示例程序创建一个仅包含标题页的简单文档。但是，这些步骤演示了创建完整报告的任务。完整的程序列表显示在步骤描述之后。

创建报告对象

创建一个报告对象（mlreportgen.report.Report）来包含报告生成的内容。报告对象使用 DOM Document 对象来保存添加到报告中的报告器生成的内容。此代码导入了报告 API 命名空间，这使得代码可以使用短类名。然后，它创建一个 PDF 报告对象 (rpt)。

import mlreportgen.report.*
rpt = Report('myReport','pdf');

创建报告器实例

创建报告器类的实例，即使用其构造函数实例化报告器。构造函数还可以设置它创建的报告对象的属性。例如，此代码创建一个标题页报告器（tp）并设置其 Title 和 Author 属性。

tp = TitlePage('Title','My Report','Author','John Smith');

设置现有报告器的属性

要在程序创建报告器后设置报告器属性，程序可以使用 MATLAB 圆点表示法。例如，此代码设置 TitlePage 报告器 (tp) 的 Subtitle 和 PubDate 属性。

tp.Subtitle = 'on My Project';
tp.PubDate = date;

将报告器添加到报告中

要使用报告器生成内容，报告程序必须使用报告对象的 append 方法将报告器添加到报告对象。append 方法通过调用该报告器的 getImpl 方法来工作。getImpl 方法创建了报告器的实现。然后，append 方法将该实现添加到作为报告对象实现的 DOM Document 对象中。您还可以使用 append 方法将 DOM 对象添加到报告中。但是，您不能向报告中添加另一个 DOM Document。

例如，此代码将标题页报告器（tp）添加到报告（rpt）。

append(rpt,tp)

关闭报告对象

当报告程序完成向报告添加内容时，它必须使用报告对象的 close 方法关闭该报告。关闭报告会将报告内容写入报告对象构造函数指定的类型的文档文件（例如 PDF）。

close(rpt)

此代码是该报告的完整程序，仅包含标题页。

import mlreportgen.report.*

rpt = Report('myReport','pdf');

tp = TitlePage('Title','My Report',...
    'Author','John Smith');
tp.Subtitle = 'on My Project';
tp.PubDate = date;

append(rpt,tp)
close(rpt)
rptview(rpt)

Report title page with the title "My Report on My Project", the author "John Smith", and the date