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

创建目录

您可以使用 mlreportgen.report.TableOfContents 类向报告中添加目录。此预定义类会自动将包含报告标题的格式化目录添加到您的报告之中。使用此类创建目录比使用 DOM 对象要容易得多，而且效率更高。有关信息和示例，请参阅 mlreportgen.report.TableOfContents。

或者，使用 DOM 对象，您可以在报告程序中创建目录，或者使用模板来定义目录。要以编程方式创建目录，请将 mlreportgen.dom.TOC 对象追加到报告文档。

使用模板可确保所有使用该模板的报告程序创建相同类型的目录。此外，使用模板，如果格式发生变化，您只需在一个地方更新目录。

如果您使用模板，您可以：

  • 将目录引用包含在您的 Word 模板或 HTML 或 PDF 模板包 (root.html) 中。

  • 为目录创建文档部件模板并以编程方式插入文档部件。

无论使用哪种方法，报告程序都必须创建指定数字级别的标题对象或指定大纲级别的段落对象。TOC 生成器使用带有级别信息的内容来定义结构体。

在报告程序中创建目录

DOM API 支持自动生成文档的目录。要启用自动目录生成：

  • 在文档中使用 Paragraph 或标题对象（Heading、Heading1 等等）来指定章节标题。如果使用 Paragraph 对象作为标题，则必须将段落的 OutlineLevel 属性设置为适当的值，例如，对于章节或其他顶级标题，设置为 1。

  • 在文档中想要生成目录的位置插入目录占位符。您可以通过编程方式或在文档模板中插入目录占位符。

以编程方式创建目录

要以编程方式创建 TOC 占位符，请在想要生成 TOC 的位置追加一个 mlreportgen.dom.TOC 对象。您可以指定目录中包含的级别数以及引导符的类型。默认值为三个级别和一个点引导符。此示例使用了两个级别和一个点引导符。 

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

title = append(d,Paragraph("My TOC Document"));
title.Bold = true;
title.FontSize = "28pt";

toc = append(d,TOC(2));
toc.Style = {PageBreakBefore(true)};

h1 = append(d,Heading1("Chapter 1"));
h1.Style = {PageBreakBefore(true)};
p1 = append(d,Paragraph("Hello World"));

h2 = append(d,Heading2("Section 1.1"));
h2.Style = {PageBreakBefore(true)};
p2 = append(d,Paragraph("Another page"));

h3 = append(d,Heading3("My Subsection 1.1.a"));
p3 = append(d, Paragraph("My Level 3 Heading Text"));

close(d);
rptview(d.OutputPath);

使用模板创建 Microsoft Word 目录

您可以使用 Word 在 Word 文档或文档部件模板中插入 Word TOC 引用对象。当 Word 更新文档时，它会用自动生成的目录替换目录引用。

要使用包含目录引用的模板在 DOM Word 报告中生成目录：

  1. 要指定在报告中生成目录的位置，请在 Word 模板中创建目录引用。请参阅创建 Word 目录引用。

  2. 设置想要在目录中显示的章节标题的大纲级别。请参阅设置章节标题的大纲级别。

  3. 更新生成的文档。请参阅更新 Word 报告中的目录。

创建 Word 目录引用

  1. 在 Word 中打开模板。

  2. 点击要创建目录的位置。

  3. 在引用选项卡上，点击目录。

    References tab in Word template with Table of Contents selected

  4. 选择 TOC 格式选项来生成目录。例如，选择内置格式选项。出现目录。

    Table of contents appearing in Word template

  5. 保存模板。

注意

如果要使用文档部件插入目录，请在文档部件的模板中插入目录引用。保存之前从模板中删除该实例。请参阅创建 Microsoft Word 文档部件模板库和使用文档部件以编程方式插入目录占位符。

更新 Word 报告中的目录

您必须更新包含目录引用的 Word 文档才能生成目录。在 Windows® 系统上，DOM API rptview 命令使用 Word 来更新其显示的 Word 文档。如果直接打开 Word 文档，例如由 Windows 以外的系统上的 DOM API 生成的文档，则必须更新目录。

  1. 在 Word 模板中，选择目录引用。

  2. 在引用选项卡上，点击更新表。

  3. 在更新目录对话框中，选择更新整个表并点击确定。

    Update Table of Contents dialog box with Update page numbers only selected

在 HTML 或 PDF 模板中创建目录

当您使用 PDF 或 HTML 模板添加目录时，您可以：

  • 在模板包中的主模板 (root.html) 中包含目录占位符。

  • 将目录占位符包含在文档部件模板中。

要使用文档部件模板在 HTML 或 PDF 报告中创建目录：

  • 定义包含 TOC 占位符的文档部件模板。

  • 以编程方式将文档部件插入到您的报告中。

  • 使用 Paragraph 或标题对象（Heading、Heading1 等等）来指定报告的标题。如果使用 Paragraph 对象作为标题，则必须将其 OutlineLevel 属性设置为适当的值。

为目录定义文档部件模板

要创建或修改目录的文档部件模板，请使用以下形式的代码：

<dptemplate name="ReportTOC">
     <TOC number-of-levels ="3" leader-pattern="dots" />
</dptemplate>

您可以：

  • 将 ReportTOC 替换为您喜欢的名称

  • 将 number-of-levels 设置为您想要包含在目录中的标题级别数

  • 将 leader-pattern 设置为 dots 或 spaces

相关示例，请参阅PDF 和 HTML 文档的部件和空位。

使用文档部件以编程方式插入目录占位符

使用 DocumentPart 类插入包含 TOC 占位符的文档部件的实例。如果在模板中定义文档部件模板，请在定义文档对象时包含模板包名称。例如：

d = Document("MyReport","html","MyTemplate");

此代码使用默认模板中提供的文档部件 ReportTOC 来生成目录。

import mlreportgen.dom.*;
d = Document("MyReport","pdf");
append(d,"My Report");

append(d,DocumentPart(d,"ReportTOC"));
append(d,Heading1("Chapter 1"));
append(d,Heading2("Section 1"));

close(d);
rptview(d.OutputPath);

提示

使用 Document 语法中分配给 DocumentPart 对象的变量来使用与文档对象关联的文档部件模板：

append(d,DocumentPart(d,"ReportTOC"));

如果使用此语法，则引用文档部件时不需要调用模板并指定文档类型。这种方法简化了您的代码并更有效地生成报告。

设置章节标题的大纲级别

要在报告中生成目录，您的程序必须设置目录中所需章节标题的大纲级别。大纲级别是一种段落格式属性，它指定段落的内容是否出现在目录中以及出现在什么级别中。例如，如果某个段落的大纲级别为 1，则其内容会出现在生成的目录的顶层。您最多可以指定 9 个大纲级别。

要设置段落的大纲级别，请使用以下方法之一。

使用模板定义的样式设置大纲级别

您可以使用报告模板中定义的样式来设置段落的大纲级别。默认情况下，Word 文档包含一组定义大纲级别的样式，标题 1、标题 2 等。您的程序可以使用这些内置样式来指定这些标题出现在目录中。此示例使用模板定义的样式来设置章节标题的大纲级别，并假定模板 MyTemplate 包含目录引用。

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

append(d,Paragraph("Chapter 1","Heading 1"));
append(d,Paragraph("Section 1","Heading 2"));

close(d);
rptview(d.OutputPath); % Updates the TOC

您还可以使用 Word 或 HTML 编辑器定义自己的标题样式，然后使用它们生成报告。

使用格式对象设置大纲级别

您可以使用格式对象来设置大纲级别。此示例假设模板 MyTemplate 包含 TOC 引用。

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

h1 = {FontFamily("Arial"),FontSize("16pt"),OutlineLevel(1)};
h2 = {FontFamily("Arial"),FontSize("14pt"),OutlineLevel(2)};
p = append(d,Paragraph("Chapter 1"));
p.Style = h1;
p = append(d,Paragraph("Section 1"));
p.Style = h2;

close(d);
rptview(d.OutputPath); % Updates the TOC

使用标题对象设置大纲级别

您可以使用 mlreportgen.dom.Heading1 对象（以及 Heading2、Heading3 等）来指定大纲级别。Heading1 对象是一个段落，其构造函数指定了其大纲级别。您可以单独使用 Heading1 对象，也可以将其与基于模板的样式或基于格式对象的样式一起使用。此示例假设模板 MyTemplate 包含 TOC 引用。

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

h1 = {FontFamily("Arial"),FontSize("16pt")};
h2 = {FontFamily("Arial"),FontSize("14pt")};
h = append(d,Heading1("Chapter 1"));
h.Style = h1;
h = append(d,Heading2("Section 1"));
p.Style = h2;

close(d);
rptview(d.OutputPath); % Updates the TOC

在 HTML 和 PDF 报告中，Heading1 和 Heading2 对象生成 HTML 元素 h1 和 h2。通过使用对象 Heading1、Heading2 等，您可以确保您的报告使用默认标题样式。

另请参阅

函数

类

主题