リストの作成と書式設定

DOM API を使用して、レポート生成プログラム内で順序なしリスト、順序付きリスト、複数レベルのリストを作成および書式設定できます。

リストは mlreportgen.dom.UnorderedList オブジェクトまたは mlreportgen.dom.OrderedList オブジェクトとして表されます。リスト項目は mlreportgen.dom.ListItem オブジェクトとして表されます。

MATLAB^® 配列でリスト項目を指定してリストを作成するか、一度に 1 項目ずつリストを作成することができます。配列からリストを作成するのが最も簡単な方法です。一度に 1 項目ずつリストを作成する方法は、段落やテーブルなど、複数の要素が項目に含まれる場合に便利です。

テンプレート定義スタイルを使用して、またはプログラムで書式オブジェクトを使用して、リストおよびリスト項目を書式設定します。

MATLAB 配列からのリストの作成

1 次元の数値配列、string 配列、文字ベクトルの配列、cell 配列、または categorical 配列からリストを作成できます。リスト項目の型が異なる場合は、cell 配列で項目を指定します。

配列からの順序なしリストの作成

配列から順序なしリストを作成するには、その配列をドキュメントまたはドキュメントパーツに直接追加します。append メソッドは、次を行います。

mlreportgen.dom.UnorderedList オブジェクトを作成する。
配列の各要素に mlreportgen.dom.ListItem オブジェクトを作成する。
ListItem オブジェクトを UnorderedList オブジェクトに追加し、UnorderedList オブジェクトをドキュメントまたはドキュメントパーツに追加する。

たとえば、次のコードは string 配列から順序なしリストを作成します。

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 オブジェクトに追加します。たとえば、次のコードは string 配列から順序付きリストを作成します。

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

cell 配列からのリストの作成

リスト項目の型が異なる場合は、cell 配列で項目を指定します。cell 配列には、文字ベクトル、文字列、数値、および一部の DOM オブジェクト (mlreportgen.dom.Text など) を含めることができます。含めることができる DOM オブジェクトの一覧については、mlreportgen.dom.ListItem を参照してください。

たとえば、次のコードは、文字ベクトルと mlreportgen.dom.ExternalLink オブジェクトを含む cell 配列から、順序付きリストを作成します。

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.

複数レベルのリストの作成

複数レベルのリストは、入れ子形式のリストを含むリストです。順序付きリストおよび順序なしリストを自由に組み合わせて、入れ子レベルが最大 9 までの入れ子を作成できます。

複数レベルのリストは以下の方法で作成できます。各方法で生成されるリストは同じに見えますが、DOM API の表現が異なります。

リストの階層構造をモデル化する cell 配列から複数レベルのリストを作成します。この方法では、DOM API はサブリストをそのサブリストを含むリストの子として表します。
mlreportgen.dom.UnorderedList オブジェクト、mlreportgen.dom.OrderedList オブジェクト、mlreportgen.dom.ListItem オブジェクトを使用して、複数レベルのリストを一度に 1 つずつ作成します。リストまたはリスト項目にサブリストを追加します。リストにサブリストを追加した場合、DOM API はそのサブリストをリストの子として表します。リスト項目にサブリストを追加した場合、DOM API はそのサブリストをリスト項目の子として表します。

cell 配列からの複数レベルのリストの作成

複数の cell 配列から複数レベルのリストを作成するには、次のいずれかの方法を使用します。

サブリストが順序なしリストの場合、1 つ上位のリストを表す 1 行 n 列の cell 配列の要素において、1 行 n 列の cell 配列として、サブリストを表すことが可能です。たとえば、次のコードは、最上位リストを表す cell 配列の 3 番目の要素である cell 配列として、サブリストを表します。
```
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);
```
生成されたレポートのリストは次のようになります。
サブリストが順序付きリストの場合、そのサブリストを表す 1 行 n 列の cell 配列から mlreportgen.dom.OrderedList オブジェクトを作成します。1 つ上位のリストを表す cell 配列の要素として OrderedList オブジェクトを含めます。たとえば、次のコードは、サブリストを表す cell 配列から OrderedList オブジェクトを作成し、最上位リストを作成するのに使用する cell 配列の 3 番目の要素としてそのオブジェクトを含めます。
```
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);
```
生成されたレポートのリストは次のようになります。

前の 2 つの例では、DOM API はこのサブリストを最上位リストの 3 番目の子として表します。このサブリストにアクセスするには、最上位リストの Children プロパティを使用します。

topList.Children(3)

複数のリストからの複数レベルのリストの作成

サブリスト項目に複数の段落が含まれる場合や、段落とテーブルが混在している場合、またはその他のドキュメント要素の組み合わせが含まれる場合は、mlreportgen.dom.ListItem オブジェクトを作成し、それらを mlreportgen.dom.UnorderedList オブジェクトまたは mlreportgen.dom.OrderedList オブジェクトに追加します。次に、そのサブリストをリストまたはリスト項目に追加します。

この例では、サブリストを 3 番目のリスト項目として最上位リストに追加しています。サブリストの項目はテキストとテーブルで構成されます。

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 はこのサブリストを最上位リストの 3 番目の子として表します。このサブリストにアクセスするには、最上位リストの Children プロパティを使用します。

topList.Children(3)

サブリストをリストに追加する代わりに、リスト項目に追加できます。次の例では、サブリストを最上位リストの 2 番目のリスト項目に追加しています。生成されるリストは、前の例と同じに見えます。

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 はこのサブリストを最上位リストの 2 番目の項目における 2 番目の子として表します。このサブリストにアクセスするには、次のコードを使用します。

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 の [ホーム] タブにある [段落] グループで、[アウトライン] アイコンをクリックしてから、[新しいリストスタイルの定義] をクリックします。
[名前] にスタイル名を設定します。
箇条書きのタイプや各リストレベルの色などの書式を指定します。
[このテンプレートを使用した新規文書] を選択します。
[OK] をクリックしてテンプレートを保存します。

Word リストスタイルを定義する例については、Custom Styled Word Listを参照してください。

HTML または PDF のリストスタイルの作成

HTML または PDF テンプレートのカスケードスタイルシート (CSS) でリストスタイルを定義するには、順序なしリストスタイルには ul 要素を使用し、順序付きリストスタイルには ol 要素を使用します。子セレクター (>) を使用すると、複数レベルのリストスタイルを定義できます。HTML テンプレートでのスタイルの変更とPDF テンプレートでのスタイルの変更を参照してください。

たとえば、次の CSS コードは、順序付きまたは順序なしサブリストを含むことができる 2 レベルの順序なしリストについて、その外観を定義します。

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

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

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

CSS の編集の詳細については、W3Schools.com の CSS Tutorial などのドキュメンテーションを参照してください。

プログラムによるリストの書式設定

mlreportgen.dom.Color オブジェクトなどの書式オブジェクトを mlreportgen.dom.UnorderedList オブジェクト、mlreportgen.dom.OrderedList オブジェクト、mlreportgen.dom.ListItem オブジェクトの Style プロパティに追加して、プログラムでリストを書式設定します。Style プロパティで指定した書式設定は、テンプレート定義スタイルをオーバーライドします。

PDF レポートおよび HTML レポートのリストの場合、mlreportgen.dom.ListStyleType 書式オブジェクトを使用して、箇条書きのタイプまたは番号付けのタイプを指定できます。

たとえば、次のコードは、小文字アルファベットの箇条書きによる、緑色の順序付きリストを作成します。3 番目のリスト項目は青色かつイタリックです。

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.

複数レベルのリストのリスト項目の書式設定

複数レベルのリストを作成する方法に基づいて、サブリストは、親リストの子となる場合と、親リスト内の前のリスト項目の子となる場合があります。複数レベルのリストの作成を参照してください。

サブリストが親リストのリスト項目の子である場合、サブリストはそのリスト項目から書式設定を継承します。たとえば、次のコードでは、サブリストは親リストにおける 2 番目のリスト項目の子となります。

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);

親リストの 2 番目のリスト項目は赤色ですが、サブリストは黒色です。

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