创建和格式化列表

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

您可以使用 DOM API 在报告生成程序中创建和格式化无序、有序和多级列表。

列表表示为 mlreportgen.dom.UnorderedList 或 mlreportgen.dom.OrderedList 对象。列表项表示为 mlreportgen.dom.ListItem 对象。

您可以从指定列表项的 MATLAB^® 数组创建一个列表，或者一次创建一个列表项。从数组创建列表是最简单的方法。当项包含多个元素（例如一个段落和一个表）时，一次创建一个列表很有用。

使用模板定义的样式或以编程方式使用格式对象来格式化列表和列表项。

从 MATLAB 数组创建列表

您可以从一维数值数组、字符串数组、字符向量数组、元胞数组或分类数组创建列表。当列表项具有不同类型时，在元胞数组中指定列表项。

从数组创建无序列表

要从数组创建无序列表，请将数组直接追加到文档或文档部件。append 方法：

创建一个 mlreportgen.dom.UnorderedList 对象。
为数组的每个元素创建一个 mlreportgen.dom.ListItem 对象。
将 ListItem 对象追加到 UnorderedList 对象，将 UnorderedList 对象追加到文档或文档部件。

例如，此代码从字符串数组创建一个无序列表：

import mlreportgen.dom.*
d = Document("fruit","html");

ul = append(d,["apples","oranges","bananas"]);

close(d);
rptview(d);

以下是生成的报告中的列表：

Bulleted list that includes the items apples, oranges, and bananas

注意

要通过将数组追加到文档或文档部件来创建列表，数组必须是 1×n。将 n×1 数组追加到文档或文档部件会创建一个表，而不是列表。

或者，通过将数组作为 mlreportegen.dom.UnorderedList 构造函数的输入来创建无序列表。例如：

import mlreportgen.dom.*
d = Document("fruit","html");

ul = UnorderedList(["apples","oranges","bananas"]);
ul = append(d,ul);

close(d);
rptview(d);

构造函数为每个数组元素创建一个 mlreportgen.dom.ListItem 对象，并将 ListItem 对象追加到 UnorderedList 对象。

从数组创建有序列表

要从数组创建有序列表，请将该数组作为输入提供给 mlreportegen.dom.OrderedList 构造函数。构造函数为数组的每个元素创建一个 mlreportgen.dom.ListItem 对象，并将 ListItem 对象追加到 OrderedList 对象。例如，此代码根据字符串数组创建一个有序列表。

import mlreportgen.dom.*
d = Document("weekdays","html");

ol = OrderedList(["Monday","Tuesday","Wednesday","Thursday","Friday"]);
append(d,ol);

close(d);
rptview(d);

以下是生成的报告中的列表：

List of weekdays in order, Monday through Friday

从元胞数组创建列表

当列表项具有不同类型时，在元胞数组中指定列表项。在元胞数组中，您可以包含字符向量、字符串、数字和一些 DOM 对象，例如 mlreportgen.dom.Text 对象。有关可包含的 DOM 对象的列表，请参阅 mlreportgen.dom.ListItem。

例如，此代码从包含字符向量和 mlreportgen.dom.ExternalLink 对象元胞数组创建有序列表。

import mlreportgen.dom.*
d = Document("myreport","html");

ol = UnorderedList({...
    "apples",...
    "oranges",...
    ExternalLink("https://en.wikipedia.org/wiki/Mango",...
    "mango")});
append(d,ol);

close(d);
rptview(d);

以下是生成的报告中的列表：

Bulleted list with the items apples, oranges, and mango. Mango is a hyperlink.

从单个项创建列表

您不需要将整个列表指定为数组，而是可以将每个列表项指定为 mlreportgen.dom.ListItem 对象，并将 ListItem 对象追加到 mlreportgen.UnorderedList 或 mlreportgen.OrderedList 对象。当列表项包含多个段落、段落和表的混合或其他文档元素组合时，这种方法很有用。

例如，此代码创建一个列表，其中列表项由一个段落和一个表组成。

import mlreportgen.dom.*
d = Document("magicsquares","html");

ol = UnorderedList();
item1 = ListItem(Paragraph("magic(2)"));
append(item1,Table(magic(2)));
append(ol,item1);
item2 = ListItem(Paragraph("magic(3)"));
append(item2,Table(magic(3)));
append(ol,item2);
append(d,ol);

close(d);
rptview(d);

以下是生成的报告中的列表：

A bulleted list with two items. Each list item is a call to the magic function, followed by the output.

创建多级列表

多级列表是包含嵌套列表的列表。您可以嵌套有序列表和无序列表的任意组合，最多可嵌套九层。

您可以使用以下方法来创建多级列表。每种方法生成的列表看起来相同，但 DOM API 表示不同。

从对列表层次结构进行建模的元胞数组创建多级列表。通过这种方法，DOM API 将子列表表示为包含它的列表的子项。
使用 mlreportgen.dom.UnorderedList、mlreportgen.dom.OrderedList 和 mlreportgen.dom.ListItem 对象一次创建一个多级列表。将子列表追加到列表或列表项。如果将子列表追加到列表，则 DOM API 会将子列表表示为列表的子项。如果将子列表追加到列表项，则 DOM API 会将子列表表示为列表项的子项。

从元胞数组创建多级列表

要从元胞数组创建多级列表，请使用以下方法之一：

如果子列表是无序列表，则可以将其表示为 1×n 元胞数组，该数组是表示上一级列表的 1×n 元胞数组的元素。例如，此代码将子列表表示为元胞数组是表示顶级列表的元胞数组的第三个元素。

import mlreportgen.dom.*;
d = Document("nestedListReport","html");

topList = OrderedList({...
    "Start MATLAB",...
    "Create a rank 3 or 4 magic square",...
        {"magic(3)",...  % sublist is third element
        "magic(4)"},...
    "Close MATLAB"});
append(d,topList);

close(d);
rptview(d);

以下是生成的报告中的列表：

A nested list with three items. A bulleted sublist is nested under the second item of the top-level list.

如果子列表是有序列表，则从表示子列表的 1×n 元胞数组创建一个 mlreportgen.dom.OrderedList 对象。将 OrderedList 对象作为表示上一级列表的元胞数组的元素包含在内。例如，此代码从表示子列表的元胞数组创建一个 OrderedList 对象，并将该对象作为用于创建顶级列表的元胞数组的第三个元素。
```
import mlreportgen.dom.*;
d = Document("orderedListReport","html");

topList = OrderedList({"Start MATLAB", ...
    "Create a rank 3 or 4 magic square",...
    OrderedList({...  % sublist is third element
        "magic(3)",...
        "magic(4)"}),...
    "Close MATLAB"});

append(d,topList);

close(d);
rptview(d);
```
以下是生成的报告中的列表：

在前面的两个示例中，DOM API 将子列表表示为顶级列表的第三个子项。要访问子列表，请使用顶级列表的 Children 属性。

topList.Children(3)

从多个列表创建多级列表

当子列表项包含多个段落、段落和表的混合或其他文档元素组合时，创建 mlreportgen.dom.ListItem 对象并将其追加到 mlreportgen.dom.UnorderedList 或 mlreportgen.dom.OrderedList 对象。然后，将子列表追加到列表或列表项。

此示例将子列表追加到顶级列表作为第三个列表项。子列表中的项由文本和表组成。

import mlreportgen.dom.*;
d = Document("orderedListReport","html");

subList = UnorderedList;
subListItem1 = ListItem(">> magic(3)");
table = append(subListItem1,Table(magic(3)));
table.Width = "1in";
append(subList,subListItem1);
subListItem2 = ListItem(">> magic(4)");
table = append(subListItem2,Table(magic(4)));
table.Width = "1in";
append(subList,subListItem2);

topList = OrderedList();
append(topList,ListItem("Start MATLAB"));
append(topList,ListItem("Create a rank 3 or 4 magic square"));
append(topList,subList); % sublist is item 3 of topList
append(topList,ListItem("Close MATLAB"));
    
append(d,topList);

close(d);
rptview(d);

以下是生成的报告中的列表：

A numbered list with three items. The sublist items contain text for the magic function call and a table for the output.

DOM API 将子列表表示为顶级列表的第三个子项。要访问子列表，请使用顶级列表的 Children 属性。

topList.Children(3)

您可以将子列表追加到列表项，而不是将子列表追加到列表。以下示例将子列表追加到顶级列表的第二个列表项。生成的列表看起来与前面的示例相同。

import mlreportgen.dom.*;
d = Document("orderedListReport","html");

topList = OrderedList({ ...
    "Start MATLAB", ...
    "Create a rank 3 or 4 magic square:", ...
    "Close MATLAB"});

subList = UnorderedList;
subListItem1 = ListItem(">> magic(3)");
table = append(subListItem1,Table(magic(3)));
table.Width = "1in";
append(subList,subListItem1);
subListItem2 = ListItem(">> magic(4)");
table = append(subListItem2,Table(magic(4)));
table.Width = "1in";
append(subList,subListItem2);

% Append the sublist to the second list item
topListItem2 = topList.Children(2);
append(topListItem2, subList);

append(d, topList);

close(d);
rptview(d);

DOM API 将子列表表示为顶级列表第二项的第二个子项。要访问子列表，请使用以下代码：

topList.Children(2).Children(2)

使用模板定义的样式格式化列表

您可以使用模板中定义的列表样式来指定列表每一级的缩进以及用于呈现列表项的项目符号类型或数字格式。

要使用模板定义的列表样式来格式化列表，请将列表的 StyleName 属性设置为样式的名称。例如，此代码指定列表样式名称为 MyListStyle。

import mlreportgen.dom.*;
d = Document("myListReport","html");

list = append(d,{"first item",...
    OrderedList({"step 1","step 2"}),"second item"});
list.StyleName = "MyListStyle";

close(d);
rptview(d);

对于 Microsoft^® Word 文档，您指定的列表样式必须在分配给该文档的模板中定义。

注意

列表样式决定了列表项的呈现方式，无论列表类型如何。如果您未指定列表样式，DOM API 将使用默认列表样式，根据类型呈现列表。例如，无序列表的默认列表样式使用项目符号来呈现列表项。如果为对项进行编号的 mlreportegen.dom.UnorderedList 对象指定列表样式，则即使对象类型是无序的，项也会被编号。

创建 Word 列表样式

有关创建 Word 模板的信息，请参阅创建 Microsoft Word 模板。

要在 Word 模板中定义列表样式：

使用以下方法之一打开 Word 模板文件：
- 在 MATLAB 的当前文件夹窗格中，右键点击模板文件，然后点击在 MATLAB 外部打开。
- 在 MATLAB 之外，右键点击文件，然后点击打开。
  注意
  不要双击 Word 模板文件来打开它。双击该文件将打开使用该模板的 Word 文档文件。
在 Word 中，在主页选项卡的段落组中，点击多级列表图标，然后点击定义新的列表样式。
将名称设置为您的样式名称。
指定格式，例如每个列表级别的项目符号样式和颜色。
选择基于此模板的新文档。
点击确定保存模板。

有关定义 Word 列表样式的示例，请参阅自定义样式的 Word 列表。

创建 HTML 或 PDF 列表样式

要在 HTML 或 PDF 模板的层叠样式表 (CSS) 中定义列表样式，请使用 ul 元素（用于无序列表样式）和 ol 元素（用于有序列表样式）。您可以使用子选择器 (>) 来定义多级列表样式。请参阅修改 HTML 模板中的样式和修改 PDF 模板中的样式。

例如，此 CSS 代码定义了可包含有序或无序子列表的两级无序列表的外观。

ul.MyUnorderedList {
	list-style-type:disc;
}

ul.MyUnorderedList > ul {
	list-style-type:circle;
}

ul.MyUnorderedList > ol {
	list-style-type:decimal;
}

有关编辑 CSS 的信息，请参阅 W3Schools.com CSS 教程等文档。

通过编程设置列表格式

通过将格式对象（例如 mlreportgen.dom.Color 对象）添加到 mlreportgen.dom.UnorderedList、mlreportgen.dom.OrderedList 或 mlreportgen.dom.ListItem 对象的 Style 属性，以编程方式格式化列表。您在 Style 属性中指定的格式将覆盖模板定义的样式。

对于 PDF 和 HTML 报告中的列表，您可以使用 mlreportgen.dom.ListStyleType 格式对象指定项目符号类型或编号类型。

例如，此代码创建一个带有小写字母项目符号的绿色有序列表。第三个列表项是蓝色和斜体。

import mlreportgen.dom.*
d = Document("myreport","html");

ol = OrderedList(["one", "two", "three"]);
ol.Style = {Color("Green"),ListStyleType("lower-alpha")};
ol.Children(3).Style = {Color("blue"),Italic(true)};
append(d,ol);

close(d);
rptview(d);

以下是生成的报告中的列表：

A list with lowercase letters for bullets showing different colors and styles for list items

您还可以使用格式属性或与对象关联的格式对象来格式化用于创建列表项的 DOM 对象。例如，此代码在使用 mlreportgen.dom.Text 对象创建列表之前对其进行格式化。

import mlreportgen.dom.*
d = Document("myreport","html");

li1 = Text("red");
li1.Color = "Red";
li2 = Text("blue");
li2.Color = "Blue";

append(d,{li1, li2});

close(d);
rptview(d);

以下是生成的报告中的列表：

Bulleted list where item one is red and item two is blue.

设置多级列表中列表项的格式

根据创建多级列表的方式，子列表可以是父列表的子项，也可以是父列表中前一个列表项的子项。请参阅创建多级列表。

如果子列表是父列表的列表项的子项，则子列表将继承列表项的格式。例如，此代码使子列表成为父列表中第二个列表项的子列表。

import mlreportgen.dom.*;
d = Document("nestedListReport","html");

parentlist = OrderedList();
li1 = ListItem("List Item 1");
li2 = ListItem("List Item 2");
li2.Style = [li2.Style {Color("red")}];

sublist = UnorderedList({"Sublist Item 1" "Sublist Item 2"});
append(li2,sublist);

append(parentlist,li1);
append(parentlist,li2);
append(d,parentlist);

close(d);
rptview(d);

子列表从包含它的列表项继承红色。

Ordered list where first item is black and the second item and the sublist that it contains are red

如果您不希望子列表继承前一个列表项的格式，请格式化前一个列表项中的段落或文本，而不是格式化列表项。例如：

import mlreportgen.dom.*;
d = Document("nestedListReport","html");

parentlist = OrderedList();
li1 = ListItem("List Item 1");
txt = Text("List Item 2");
txt.Color = "red";
li2 = ListItem(txt);

sublist = UnorderedList({"Sublist Item 1" "Sublist Item 2"});

append(parentlist,li1);
append(parentlist,li2);
append(parentlist,sublist);

append(d,parentlist);

close(d);
rptview(d);

或者，您可以将子列表创建为父列表的子项，而不是父列表中前一个列表项的子项。如果子列表是父列表的子项，则子列表不会继承父列表中前一个列表项的格式。例如，此代码使子列表成为父列表的子列表：

import mlreportgen.dom.*;
d = Document("nestedListReport","html");

parentlist = OrderedList();
li1 = ListItem("List Item 1");
li2 = ListItem("List Item 2");
li2.Style = [li2.Style {Color("red")}];

sublist = UnorderedList({"Sublist Item 1" "Sublist Item 2"});

append(parentlist,li1);
append(parentlist,li2);
append(parentlist,sublist);

append(d,parentlist);

close(d);
rptview(d);

父列表的第二个列表项是红色，但子列表是黑色。

Ordered list where the first list item is black, the second list item is red, and the sublist is black

另请参阅

mlreportgen.dom.OrderedList | mlreportgen.dom.UnorderedList | mlreportgen.dom.ListItem | mlreportgen.dom.ListStyleType