mlreportgen.dom.Template 类

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

创建报告模板对象

描述

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

注意

Microsoft^® Word for Mac 不支持为 DOM API 模板创建空位。如果您需要创建一个用于在 Mac 上生成 Word 文档的 Word 模板，则可以使用 DOM API 创建模板。创建一个 Template 对象并使用 mlreportgen.dom.TemplateHole 添加空位。或者，使用 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，指定为字符向量或字符串标量。

属性：

`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 元素。

属性：

`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 文档，该值始终为 []。

属性：

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

`ForceOverwrite` — 覆盖现有输出文件的选项
`true` (默认) | `false`

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

属性：

NonCopyable true

数据类型: logical

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

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

属性：

NonCopyable true

数据类型: char | string

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

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

属性：

`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™）上生成 PDF 报告可能会因报告生成软件和云盘同步软件之间的文件争用而导致错误。为了避免此错误，请在未与云同步的本地驱动器上生成报告。考虑编写一个脚本，在本地驱动器上生成报告，然后将报告复制到云端驱动器。

属性：

NonCopyable true

数据类型: char | string

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

用于生成文件的打包，指定为表中的值之一。

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

提示

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

属性：

NonCopyable true

数据类型: char | string

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

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

属性：

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

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

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

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

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

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

注意

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

属性：

NonCopyable true

数据类型: char | string

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

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

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

属性：

NonCopyable true

数据类型: char | string

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

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

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

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

属性：

NonCopyable true

数据类型: char | string

`Children` — `mlreportgen.dom.Template` 对象的子级
文档元素对象数组

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

属性：

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

`Tag` — `mlreportgen.dom.Template` 对象的标签
字符向量 | 字符串标量

mlreportgen.dom.Template 对象的标签，指定为字符向量或字符串标量。DOM API 在创建此对象的过程中生成一个会话唯一标签。生成的标签形式为 CLASS:ID，其中 CLASS 是对象类，ID 是对象的 Id 属性的值。指定您自己的标签值，以帮助您确定在文档生成过程中出现问题时要查找的位置。

属性：

NonCopyable true

数据类型: char | string

`Id` — `mlreportgen.dom.Template` 对象的标识符
字符向量 | 字符串标量

mlreportgen.dom.Template 对象的对象标识符，指定为字符向量或字符串标量。DOM API 在创建文档元素对象时会生成一个会话唯一标识符。您可以为 Id 指定自己的值。

属性：

NonCopyable true

数据类型: char | string

方法

全部展开

公共方法

使用 Template 方法的方式与使用相应的 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)

版本历史记录

在 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 — 覆盖现有输出文件的选项 true (默认) | 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"

属性：

Children — mlreportgen.dom.Template 对象的子级 文档元素对象数组

属性：

Tag — mlreportgen.dom.Template 对象的标签 字符向量 | 字符串标量

属性：

Id — mlreportgen.dom.Template 对象的标识符 字符向量 | 字符串标量

属性：

方法

公共方法

示例

创建模板并添加内容

版本历史记录

另请参阅

主题

WeChat

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

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

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

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

`ForceOverwrite` — 覆盖现有输出文件的选项
`true` (默认) | `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"`

`Children` — `mlreportgen.dom.Template` 对象的子级
文档元素对象数组

`Tag` — `mlreportgen.dom.Template` 对象的标签
字符向量 | 字符串标量

`Id` — `mlreportgen.dom.Template` 对象的标识符
字符向量 | 字符串标量