mlreportgen.dom.Template 类

命名空间: mlreportgen.dom
超类: mlreportgen.dom.Document

创建报告模板对象

描述

使用 mlreportgen.dom.Template 类的实例创建报告模板。例如，您可以将 DOM 内容（如 Text、Paragraph 或 Image 对象和 TemplateHole 对象）追加到 mlreportgen.dom.Template 对象，以创建包含固定内容的模板，其中有用于生成内容的空位。

注意

Microsoft^® Word 适用于 Mac 的版本不支持为 DOM API 模板创建空位。要在 Mac 上创建用于生成 Word 文档的 Word 模板，请使用以下方法之一：

创建一个 mlreportgen.dom.Template 对象，并使用 mlreportgen.dom.TemplateHole 类添加空位。
在 Windows^® 上的 Word 中创建您的模板，然后将模板复制到您的 Mac。

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

创建对象

描述

templateObj = mlreportgen.dom.Template 创建一个模板对象并将 TemplatePath 属性设置为 Untitled.htmtx。

templateObj = mlreportgen.dom.Template(templatePath) 创建一个模板对象并将 TemplatePath 属性设置为 templatePath。如果 templatePath 不包含文件扩展名，则 Type 属性设置为默认值 HTML。

templateObj = mlreportgen.dom.Template(templatePath,fileType) 还将 Type 属性设置为 fileType。如果 templatePath 包含文件扩展名，则 fileType 必须与 templatePath 指定的文件扩展名匹配。

示例

templateObj = mlreportgen.dom.Template(templatePath,fileType,sourceTemplatePath) 根据 sourceTemplatePath 指定的模板创建模板对象。

输入参量

全部展开

`sourceTemplatePath` — 新模板的基础
字符向量 | 字符串标量

用作新模板基础的模板的路径，指定为字符向量或字符串标量。源模板类型必须与 fileType 参量匹配。

属性

全部展开

`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`

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

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

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

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

属性：

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

数据类型: logical

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

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

属性：

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

数据类型: char | string

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

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

属性：

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

数据类型: char | string

`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

`Stylesheet` — 应用于模板对象的样式表
`[]` (默认) | `mlreportgen.dom.TemplateStylesheet` 对象

代表模板样式表的 mlreportgen.dom.TemplateStylesheet 类型的对象。样式表包含可用于格式化报告元素（例如段落、列表和表）的样式定义。这些样式可由主模板主体、文档部件模板或使用该模板对象生成的模板的其他文档使用。当使用 open 方法打开此 Template 时，将创建样式表对象，并自动填充此 Template 所基于的模板中的样式。使用 Stylesheet 属性来访问和修改现有样式并添加新样式。当 Template 对象关闭时，样式会写入输出模板包（HTML、PDF、DOCX）或模板文档 (HTML-FILE)。

属性：

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

`TemplateDocumentParts` — 模板对象中使用的文档部件
`[]` (默认) | `mlreportgen.dom.TemplateDocumentPart` 对象数组

模板对象中使用的文档部件，指定为要包含在模板中的 mlreportgen.dom.TemplateDocumentPart 对象数组。当您关闭 Template 对象时，Report Generator 会将这些文档部件模板写入输出模板包（HTML、PDF、DOCX）或模板文档 (HTML-FILE)。如果 Template 对象正在使用的模板文档包含任何文档部件，则在打开 Template 对象时，Report Generator 会自动使用包含现有文档部件的 DOM 表示的 TemplateDocumentPart 对象填充此属性。

属性：

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

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

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

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

注意

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

属性：

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

数据类型: char | string

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

HTML 浏览器标题栏的文本，指定为字符向量或字符串标量。对于 HTML 文档，此属性指定出现在用于显示该文档的浏览器标题栏中的文本。Word 和 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

`Children` — 此对象的子对象
文档元素对象数组

此对象的子对象，指定为文档元素对象数组。此属性包含使用 append 方法追加的文档元素对象。

属性：

`GetAccess`	`public`
`SetAccess`	`private`
`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

方法

全部展开

公共方法

方法	用途
`append`	`appendedContent = append(classObj,textContent)` 将文本 `textContent` 追加到类对象 `classObj`。 `appendedContent = append(classObj,textContent,styleName)` 使用样式 `styleName` 来追加文本。使用您追加内容的文档模板的样式表中定义的样式。 `appendedContent = append(classObj,contentToAppend)` 将 DOM 或 MATLAB 对象 `contentToAppend` 追加到类对象。输入参量 `classObj` - 要追加内容的类对象，指定为 `mlreportgen.dom.Template` 对象。 `textContent` - 要追加的文本，指定为字符向量或字符串标量。 `styleName` - 样式表的名称，指定为字符向量或字符串标量。指定此参量会将 `appendedContent` 对象的 `StyleName` 属性设置为 `styleName`。 `contentToAppend` - 要追加的内容，指定为 DOM 对象或 MATLAB 对象。返回值 `appendedContent` - 追加的内容，以 DOM 对象形式返回。要查看可作为 `classObj` 参量使用的 DOM 类对象和 MATLAB 数据类型的列表，请参阅将内容追加到 mlreportgen.dom.Template 对象。有关信息，请参阅 `mlreportgen.dom.Document` 类中的等效方法 `append`。
`close`	关闭此模板注意如果模板尚未打开或之前已被关闭，则无法将其关闭。
`mlreportgen.dom.Document.createTemplate`	创建默认模板
`fill`	填补文件空位
`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`	设置文档元素的核心属性

示例

全部折叠

创建模板并添加内容

打开实时脚本

此示例创建一个模板，其中有一个用于标题的空位和一个用于作者的空位。您可以更改 type 变量的值来创建其他类型之一的模板。

创建模板

导入 mlreportgen.dom 命名空间，这样您在调用对象构造函数和方法时不必包含完全限定名称。

import mlreportgen.dom.*;

指定模板的类型并创建模板对象。

type = "docx";
t = Template("mytemplate",type);

向模板添加标题空位并应用标题样式。

hole = append(t,TemplateHole("TITLE"));
hole.Description = ("Title Description");
hole.DefaultHoleStyleName = "Title";

添加一个包含样板文本的段落并应用子标题格式。

p = Paragraph("Author: ");
p.StyleName = "Subtitle";

定位段落并保留文本中的空白。

p.Style = {OuterMargin("0","0","1in","1in")};
p.WhiteSpace = "preserve";

为段落追加一个内联空位。

hole = append(p,TemplateHole("AUTHOR"));
append(t,p);

关闭您创建的模板对象。

close(t);

填充模板空位

创建使用模板 mytemplate 的文档 TitleAuthor。

rpt = Document("TitleAuthor",type,"mytemplate");
open(rpt);

创建一个循环来循环穿过这些空位。

将内容追加到每个空位。

while(~strcmp(rpt.CurrentHoleId,"#end#"))
    switch(rpt.CurrentHoleId)
        case "TITLE"
            append(rpt,Paragraph("This Is My Title"));
        case "AUTHOR"
            append(rpt,"My Name");
    end
    
    moveToNextHole(rpt);
end

生成并查看报告。

close(rpt);
rptview(rpt.OutputPath)

详细信息

全部展开

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

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

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

字符数组 - 追加并返回 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 中推出

另请参阅

mlreportgen.dom.TemplateHole | mlreportgen.dom.TemplateDocumentPart | mlreportgen.dom.Document | mlreportgen.dom.Document.createTemplate | rptview

mlreportgen.dom.Template 类

描述

创建对象

描述

输入参量

sourceTemplatePath — 新模板的基础 字符向量 | 字符串标量

属性

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

属性：

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

属性：

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

属性：

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

属性：

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

属性：

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

属性：

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

属性：

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

属性：

Stylesheet — 应用于模板对象的样式表 [] (默认) | mlreportgen.dom.TemplateStylesheet 对象

属性：

TemplateDocumentParts — 模板对象中使用的文档部件 [] (默认) | mlreportgen.dom.TemplateDocumentPart 对象数组

属性：

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

属性：

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

属性：

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

属性：

Children — 此对象的子对象 文档元素对象数组

属性：

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

属性：

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

属性：

方法

公共方法

示例

创建模板并添加内容

详细信息

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

版本历史记录

另请参阅

主题

`sourceTemplatePath` — 新模板的基础
字符向量 | 字符串标量

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

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

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

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

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

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

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

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

`Stylesheet` — 应用于模板对象的样式表
`[]` (默认) | `mlreportgen.dom.TemplateStylesheet` 对象

`TemplateDocumentParts` — 模板对象中使用的文档部件
`[]` (默认) | `mlreportgen.dom.TemplateDocumentPart` 对象数组

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

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

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

`Children` — 此对象的子对象
文档元素对象数组

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

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

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