mlreportgen.dom.Document 类

命名空间: mlreportgen.dom

文档容器

描述

使用 mlreportgen.dom.Document 类的对象来表示文档对象模型 (DOM) 文档。使用 Document 对象属性指定：

是否生成 HTML、Microsoft^® Word 或 PDF 文档
生成的文档存储在何处以及如何存储
用于格式化文档的模板

mlreportgen.dom.Document 类是一个 handle 类。

类属性

`ConstructOnLoad`	`true`
`HandleCompatible`	`true`

有关类属性的信息，请参阅类属性。

创建对象

描述

documentObj = mlreportgen.dom.Document 创建一个具有默认属性值的 Document 对象，该对象使用默认 HTML 模板在当前文件夹中指定一个名为 Untitled.htmx 的输出文件。

documentObj = mlreportgen.dom.Document(outputPath) 指定输出文件的路径和名称，并将 OutputPath 属性设置为 outputPath。

documentObj = mlreportgen.dom.Document(outputPath,type) 还指定输出类型并将 Type 属性设置为 type。

示例

documentObj = mlreportgen.dom.Document(outputPath,type,templatePath) 还指定模板文件的路径和名称，并将 TemplatePath 属性设置为 templatePath。

属性

全部展开

`OutputPath` — 输出文件或文件夹的路径
`"untitled"` (默认) | 字符向量 | 字符串标量

输出文件或文件夹的路径，指定为字符向量或字符串标量。默认值是当前文件夹中名为 untitled 的文件或文件夹的路径。该路径可以是完整路径，例如 "C:/myreports/reportA.docx"。该路径也可以相对于当前 MATLAB 文件夹，例如 "reportA"。如果不指定文件扩展名，DOM 会根据文档的 Type 属性添加扩展名。您只能在打开文档之前设置此属性。

OutputPath 是否指定文件或文件夹的路径取决于 PackageType 属性的值，如表所示。

`PackageType`	`OutputPath` 值
`"zipped"` 或 `"single-file"`	ZIP 文件或单个文件的路径和名称
`"unzipped"`	解压后文件的文件夹
`"both"`	ZIP 文件和解压后文件夹的路径和名称

注意

在云驱动器（例如 MATLAB^® Drive™ 或 Microsoft OneDrive™）上生成 PDF 报告可能会导致报告生成软件与云驱动器同步软件之间发生文件冲突，从而导致以下错误：

Error closing document package: Could not commit changes: removeAll failed: fl:filesystem:AccessDenied: 
C:\Users\jdoe\OneDrive\Documents\MATLAB\reports\temp_FO\stylesheets: Permission denied.

要避免此问题，请在不与云同步的本地驱动器上生成报告。考虑编写一个脚本，在本地驱动器上生成报告，然后将报告复制到云端驱动器。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

数据类型: char | string

`PackageType` — 生成文件的打包
`"zipped"` (默认) | `"unzipped"` | `"both"` | `"single-file"`

用于生成文件的打包方式，指定为以下值之一：

值	支持的报告类型	描述
`"zipped"`	`"docx"` `"html"` `"html-multipage"` (自 R2024a 起)	将报告作为 ZIP 文件生成到 `OutputPath` 属性指定的位置。ZIP 文件的扩展名与文档类型匹配（Word 输出为 `docx`，HTML 输出为 `htmtx`。）例如，如果文档类型为 `docx`，`OutputPath` 为 `s:\docs\MyDoc`，则输出将打包为一个名为 `s:\docs\MyDoc.docx` 的 ZIP 文件。
`"unzipped"`	`"docx"` `"html"` `"html-multipage"` (自 R2024a 起)	将报告作为单独的文件生成在具有 `OutputPath` 属性文件名的文件夹中。例如，如果 `OutputPath` 是 `s:\docs\MyDoc`，则输出文件夹是 `s:\docs\MyDoc`。
`"both"`	`"docx"` `"html"` `"html-multipage"` (自 R2024a 起)	生成压缩和解压缩的输出。
`"single-file"`	`"html-file"` `"pdf"` `"pdfa"` (自 R2025a 起)	将报告生成为单个文件。

提示

当 Type 属性为 "html" 或 "html-multipage" (自 R2024a 起) 时，若要生成无需解压即可打开的 HTML 报告，请将 PackageType 设置为 "unzipped" 或 "both"。在包含生成文件的文件夹中，打开 root.html 文件。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

数据类型: char | string

`ForceOverwrite` — 是否覆盖现有输出文件
`1` (`true`) (默认) | `0` (`false`)

是否覆盖现有输出文件，指定为逻辑值 1 (true) 或 0 (false)。当您指定：

1 (true) - 用同名的文件覆盖现有输出文件。
0 (false) - 请勿用同名的文件覆盖现有的输出文件。

如果此属性为 false，并且存在同名的可写文件，则关闭该文档会导致错误。如果现有文件是只读的，则无论此属性设置如何，关闭该文档都会导致错误。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

数据类型: logical

`StreamOutput` — 是否将输出流写入磁盘
`0` (`false`) (默认) | `1` (`true`)

是否将输出流写入磁盘，指定为逻辑 1 (true) 或 0 (false)。当您指定：

1 (true) - 在将文档元素追加到文档时，将其写入磁盘。
0 (false) - 将文档元素保存在内存中，直到文档关闭为止。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

数据类型: logical

`TitleBarText` — HTML 浏览器标题栏的文本
`""` (默认) | 字符向量 | 字符串标量

HTML 浏览器标题栏的文本，指定为字符向量或字符串标量。对于 HTML 文档，此属性指定出现在用于显示该文档的浏览器标题栏中的文本。Word 和 PDF 文档忽略此属性。

在打开文档之前设置此属性。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

数据类型: char | string

`HTMLHeadExt` — HTML 标头的自定义内容
`""` (默认) | 字符向量 | 字符串标量

HTML 标题的自定义内容，指定为字符向量或字符串标量。该属性的值追加到此文档的 <head> 元素中，位于文档模板的 head 部分指定的内容之后。仅在打开文档之前设置此属性。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

数据类型: char | string

`TemplatePath` — 要使用的模板路径
字符向量 | 字符串标量

要使用的模板的完整路径，可以选择包含文件扩展名，指定为字符向量或字符串标量。文件扩展名可以是下列值之一：

扩展名	文件类型
`.htmtx`	压缩 HTML
`.dotx`	Microsoft Word
`.htmt`	单文件 HTML
`.pdfx`	PDF

注意

打开文档进行输出后，此属性无法更改。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

数据类型: char | string

`Type` — 输出文件类型
`"html"` (默认) | `"docx"`, | `"html-file"` | `"html-multipage"` | `"pdf"` | `"pdfa"`

输出文件类型，指定为以下值之一：

值	文件类型
`"docx"`	Microsoft Word
`"html"`	HTML 输出为压缩或解压后的文件夹，其中包含 HTML 文档文本、图像、样式表和 JavaScript^® 文件
`"html-file"`	HTML 输出由单个文件组成，其中包含报告的文本、样式表、JavaScript 和图像
`"html-multipage"` (自 R2024a 起)	HTML 输出为压缩或解压后的文件夹，其中包含分为多个页面的 HTML 文档文本、图像、样式表和 JavaScript 文件
`"pdf"`	PDF
`"pdfa"` (自 R2025a 起)	PDF/A

如果使用 TemplatePath 属性指定模板，则该模板必须与 Type 属性一致。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

数据类型: char | string

`CurrentHoleId` — 文档中当前空位的 ID
`""` (默认) | 字符向量 | 字符串标量

文档中当前空位的 ID，指定为字符向量或字符串标量。

属性：

`GetAccess`	`public`
`SetAccess`	`private`
`Transient`	`true`
`NonCopyable`	`true`

数据类型: char | string

`CurrentHoleType` — 当前空位类型
`""` (默认) | `"Inline"` | `"Block"`

当前模板空位的类型，指定为 "Inline" 或 "Block"。

内联空位适用于段落元素可以包含的文档元素：Text、Image、LinkTarget、ExternalLink、InternalLink、CharEntity 或 AutoNumber。
块状空位可以包含 Paragraph、Table、OrderedList、UnorderedList、DocumentPart 或 Group 元素。

属性：

`GetAccess`	`public`
`SetAccess`	`private`
`Transient`	`true`
`NonCopyable`	`true`

数据类型: char | string

`CurrentPageLayout` — 本文档的当前页面布局
`[]` (默认) | `mlreportgen.dom.DOCXPageLayout` 对象 | `mlreportgen.dom.PDFPageLayout` 对象 | `[]`

该文档的当前页面布局，指定为 mlreportgen.dom.DOCXPageLayout 对象、mlreportgen.dom.PDFPageLayout 对象或 []。此属性适用于 Word 和 PDF 文档。对于 Word 文档，该值是一个指定当前页面布局的 DOCXPageLayout 对象。对于 PDF 文档，如果文档当前指定了页面布局，则该值为 PDFPageLayout 对象。对于 HTML 文档，该值始终为 []。

属性：

`GetAccess`	`public`
`SetAccess`	`private`
`Transient`	`true`
`NonCopyable`	`true`

`OpenStatus` — 文档打开状态
`"unopened"` (默认) | `"open"` | `"closed"`

此文档对象的打开状态，指定为 "unopened"、"open" 或 "closed"。

注意

如果 mlreportgen.dom.Document 对象的 OpenStatus 属性是 "open" 并且您调用 rptview 来查看报告，则 OpenStatus 将被设置为 "closed"。要显示一份报告，需要调用 close 方法，该方法将报告在内存中的 DOM 表示形式转换为 Type 属性指定的类型的文件。如果 Document.OpenStatus 尚未设置为 "closed"，则 rptview 会自动为您发出所需的关闭命令。

属性：

`SetAccess`	`private`
`Transient`	`true`
`NonCopyable`	`true`

数据类型: char | string

`EndnoteOptions` — 文档尾注选项
`[]` (默认) | `mlreportgen.dom.EndnoteOptions` 对象

自 R2024a 起

文档尾注选项，指定为 mlreportgen.dom.EndnoteOptions 对象。如果 EndnoteOptions 的任何属性为空，则文档使用默认值。

注意

如果页面布局指定了尾注选项，则页面布局尾注选项将覆盖此处指定的文档尾注选项。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

`FootnoteOptions` — 文档脚注选项
`[]` (默认) | `mlreportgen.dom.FootnoteOptions` 对象

自 R2024a 起

文档脚注选项，指定为 mlreportgen.dom.FootnoteOptions 对象。如果 FootnoteOptions 的任何属性为空，则文档使用默认值。

注意

如果页面布局指定了脚注选项，则页面布局脚注选项将覆盖此处指定的文档脚注选项。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

`Parent` — 此 `mlreportgen.dom.Document` 对象的父级
文档元素对象

此文档元素的父级，指定为文档元素。一个文档元素只能有一个父元素。

属性：

`SetAccess`	`private`
`Transient`	`true`
`NonCopyable`	`true`

`Children` — 此 `mlreportgen.dom.Document` 对象的子项
文档元素对象

此文档元素的子元素，指定为文档元素对象数组。使用 append 方法追加的元素添加到此处。

属性：

`SetAccess`	`private`
`Transient`	`true`
`NonCopyable`	`true`

`Tag` — 标签
字符向量 | 字符串标量

标记，指定为字符向量或字符串标量。DOM API 在创建此对象的过程中生成一个会话唯一标记。生成的标记形式为 CLASS:ID，其中 CLASS 是对象类，ID 是对象的 Id 属性的值。使用此值来帮助确定在文档生成过程中出现的问题的位置。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

数据类型: char | string

`Id` — 目标标识符
字符向量 | 字符串标量

目标标识符，指定为字符向量或字符串标量。DOM API 在创建文档元素对象时会生成一个会话唯一标识符。

属性：

`GetAccess`	`public`
`SetAccess`	`public`
`NonCopyable`	`true`

数据类型: char | string

方法

全部展开

公共方法

`addHTML`	将 HTML 字符串追加到文档
`addHTMLFile`	将 HTML 文件内容追加到文档
`append`	将 DOM 或 MATLAB 对象追加到文档
`close`	关闭文档
`createAutoNumberStream`	创建编号流
`mlreportgen.dom.Document.createTemplate`	创建 DOM 模板文件
`fill`	使用生成的内容填充文档空位
`getAutoNumberStream`	返回编号流
`mlreportgen.dom.Document.getCoreProperties`	获取文档或模板核心属性
`mlreportgen.dom.Document.getImageDirectory`	获取文档的图像文件夹
`mlreportgen.dom.Document.getImagePrefix`	获取生成的图片名称前缀
`getMainPartPath`	文档输出包主体返回路径
`mlreportgen.dom.Document.getOPCMainPart`	返回文档的主体部分、文档部件或模板
`moveToNextHole`	将文档追加点移动到下一个模板空位
`open`	打开文档
`package`	将 OPC 部件文件添加到文档包中
`mlreportgen.dom.Document.setCoreProperties`	设置输出文档或模板的 OPC 核心属性

示例

全部折叠

创建 Word 文档

打开实时脚本

创建 Word 文档，添加内容，并在 Word 中查看报告。

import mlreportgen.dom.*;
d = Document("mydoc","docx");

append(d,"Hello World");

close(d);
rptview(d);

将 HTML 文档创建为单个文件

将 HTML 文档创建为包含图像的单个 HTML 文件。该示例假设有一个 MyImage.jpg 文件和一个 myHTMLTemplate.htmt HTML 模板文件。

创建一个文档，其输出为单个 HTML 文件并使用模板 myHTMLTemplate。向报告中添加文本和图像。关闭并查看文档。

import mlreportgen.dom.*;
d = Document("mydoc","html-file","myHTMLTemplate.htmt"); 
open(d); 

append(d,"Hello world"); 
append(d,Image("C:/images/LocalSystem/MyImage.jpg"));

close(d); 
rptview(d);

详细信息

全部展开

将内容追加到 `mlreportgen.dom.Document` 对象

您可以将这些 DOM 对象追加到 mlreportgen.dom.Document 对象：

您可以将这些 MATLAB 数据类型追加到 mlreportgen.dom.Document 对象：

字符数组 - 追加并返回 mlreportgen.dom.Text 对象
字符串标量 - 追加并返回 mlreportgen.dom.Text 对象
数值变量 - 追加并返回 mlreportgen.dom.Number 对象
逻辑变量 - 追加并返回值为 1 或 0 的 mlreportgen.dom.Number 对象
一维双精度值或字符串水平数组 - 追加并返回 mlreportgen.dom.UnorderedList 对象
二维双精度值或字符串数组 - 追加并返回 mlreportgen.dom.Table 对象
MATLAB 表 - 追加并返回 mlreportgen.dom.MATLABTable 对象

版本历史记录

在 R2014b 中推出

全部展开

R2025a: 以 PDF/A 格式输出报告

您可以以 PDF/A 格式输出 DOM 和报告 API 报告。

R2024a: DOM API 中的脚注和尾注支持

DOM API 支持脚注 mlreportgen.dom.Footnote 和尾注 mlreportgen.dom.Endnote。这些选项是使用 mlreportgen.dom.FootnoteOptions 和 mlreportgen.dom.EndnoteOptions 类设置的。您可以自定义脚注和尾注的编号和样式。脚注和尾注适用于 Microsoft Word 和 PDF 输出格式。

另请参阅

mlreportgen.dom.DocumentPart | mlreportgen.dom.Text | mlreportgen.dom.Paragraph | mlreportgen.dom.Image

主题

创建报告容器

mlreportgen.dom.Document 类

描述

类属性

创建对象

描述

属性

OutputPath — 输出文件或文件夹的路径 "untitled" (默认) | 字符向量 | 字符串标量

属性：

PackageType — 生成文件的打包 "zipped" (默认) | "unzipped" | "both" | "single-file"

属性：

ForceOverwrite — 是否覆盖现有输出文件 1 (true) (默认) | 0 (false)

属性：

StreamOutput — 是否将输出流写入磁盘 0 (false) (默认) | 1 (true)

属性：

TitleBarText — HTML 浏览器标题栏的文本 "" (默认) | 字符向量 | 字符串标量

属性：

HTMLHeadExt — HTML 标头的自定义内容 "" (默认) | 字符向量 | 字符串标量

属性：

TemplatePath — 要使用的模板路径 字符向量 | 字符串标量

属性：

Type — 输出文件类型 "html" (默认) | "docx", | "html-file" | "html-multipage" | "pdf" | "pdfa"

属性：

CurrentHoleId — 文档中当前空位的 ID "" (默认) | 字符向量 | 字符串标量

属性：

CurrentHoleType — 当前空位类型 "" (默认) | "Inline" | "Block"

属性：

CurrentPageLayout — 本文档的当前页面布局 [] (默认) | mlreportgen.dom.DOCXPageLayout 对象 | mlreportgen.dom.PDFPageLayout 对象 | []

属性：

OpenStatus — 文档打开状态 "unopened" (默认) | "open" | "closed"

属性：

EndnoteOptions — 文档尾注选项 [] (默认) | mlreportgen.dom.EndnoteOptions 对象

属性：

FootnoteOptions — 文档脚注选项 [] (默认) | mlreportgen.dom.FootnoteOptions 对象

属性：

Parent — 此 mlreportgen.dom.Document 对象的父级 文档元素对象

属性：

Children — 此 mlreportgen.dom.Document 对象的子项 文档元素对象

属性：

Tag — 标签 字符向量 | 字符串标量

属性：

Id — 目标标识符 字符向量 | 字符串标量

属性：

方法

公共方法

示例

创建 Word 文档

将 HTML 文档创建为单个文件

详细信息

将内容追加到 mlreportgen.dom.Document 对象

版本历史记录

R2025a: 以 PDF/A 格式输出报告

R2024a: DOM API 中的脚注和尾注支持

另请参阅

主题

`OutputPath` — 输出文件或文件夹的路径
`"untitled"` (默认) | 字符向量 | 字符串标量

`PackageType` — 生成文件的打包
`"zipped"` (默认) | `"unzipped"` | `"both"` | `"single-file"`

`ForceOverwrite` — 是否覆盖现有输出文件
`1` (`true`) (默认) | `0` (`false`)

`StreamOutput` — 是否将输出流写入磁盘
`0` (`false`) (默认) | `1` (`true`)

`TitleBarText` — HTML 浏览器标题栏的文本
`""` (默认) | 字符向量 | 字符串标量

`HTMLHeadExt` — HTML 标头的自定义内容
`""` (默认) | 字符向量 | 字符串标量

`TemplatePath` — 要使用的模板路径
字符向量 | 字符串标量

`Type` — 输出文件类型
`"html"` (默认) | `"docx"`, | `"html-file"` | `"html-multipage"` | `"pdf"` | `"pdfa"`

`CurrentHoleId` — 文档中当前空位的 ID
`""` (默认) | 字符向量 | 字符串标量

`CurrentHoleType` — 当前空位类型
`""` (默认) | `"Inline"` | `"Block"`

`CurrentPageLayout` — 本文档的当前页面布局
`[]` (默认) | `mlreportgen.dom.DOCXPageLayout` 对象 | `mlreportgen.dom.PDFPageLayout` 对象 | `[]`

`OpenStatus` — 文档打开状态
`"unopened"` (默认) | `"open"` | `"closed"`

`EndnoteOptions` — 文档尾注选项
`[]` (默认) | `mlreportgen.dom.EndnoteOptions` 对象

`FootnoteOptions` — 文档脚注选项
`[]` (默认) | `mlreportgen.dom.FootnoteOptions` 对象

`Parent` — 此 `mlreportgen.dom.Document` 对象的父级
文档元素对象

`Children` — 此 `mlreportgen.dom.Document` 对象的子项
文档元素对象

`Tag` — 标签
字符向量 | 字符串标量

`Id` — 目标标识符
字符向量 | 字符串标量

将内容追加到 `mlreportgen.dom.Document` 对象