本页采用了机器翻译。点击此处可查看英文原文。

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 指定的模板创建模板对象。

输入参量

全部展开

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

属性

全部展开

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

属性：

GetAccess
public
SetAccess
private
Transient
true
NonCopyable
true

数据类型: char | string

当前模板空位的类型，指定为 "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

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

属性：

GetAccess
public
SetAccess
private
Transient
true
NonCopyable
true

是否覆盖现有的输出文件，指定为 true 或 false。将此属性设置为 true 以覆盖具有相同名称的现有输出文件。如果此属性为 false，并且存在同名的可写文件，则关闭该文档会导致错误。如果现有文件是只读的，则无论此属性设置如何，关闭该文档都会导致错误。

属性：

GetAccess
public
SetAccess
public
NonCopyable
true

数据类型: logical

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

属性：

GetAccess
public
SetAccess
public
NonCopyable
true

数据类型: char | string

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

属性：

GetAccess
public
SetAccess
private
Transient
true
NonCopyable
true

数据类型: char | string

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

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

PackageTypeOutputPath 值
"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

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

值支持的报告类型描述

"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

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

属性：

SetAccess
private
NonCopyable
true

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

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

扩展名文件类型
.htmtx

压缩 HTML

.dotx

Microsoft Word

.htmt

单文件 HTML

.pdfx

PDF

注意

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

属性：

GetAccess
public
SetAccess
public
NonCopyable
true

数据类型: char | string

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

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

属性：

GetAccess
public
SetAccess
public
NonCopyable
true

数据类型: char | string

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

值文件类型
"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

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

属性：

GetAccess
public
SetAccess
private
NonCopyable
true

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

属性：

GetAccess
public
SetAccess
public
NonCopyable
true

数据类型: char | string

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

属性：

GetAccess
public
SetAccess
public
NonCopyable
true

数据类型: char | string

方法

全部展开

示例

全部折叠

打开实时脚本

此示例创建一个模板，其中有一个用于标题的空位和一个用于作者的空位。您可以更改 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)

版本历史记录

在 R2014b 中推出

另请参阅

| | | |

主题