リストの操作
概要
このガイドでは、Aspose.Words FOSS for .NET において、番号付きリストと箇条書きリストがどのように表現・制御されるかを示します。List はそれを使用するすべての段落で共有される再利用可能なリスト定義であり、ListFormat は個々の段落がリストとその現在のレベルを参照する方法、ListLevel はリストの 1 レベル分の実際の番号付けまたは箇条書きの書式を保持します。
リストオブジェクトと ListCollection
List は 1 つのリスト定義を表します — 文書が複数の段落に適用できる番号付けルールです。List.ListId はそれを識別し、List.IsMultiLevel は複数レベルを定義しているかどうかを報告し、List.ListLevels はリストが定義する各レベルにつき 1 つの ListLevel を保持する ListLevelCollection を返します。List.IsListStyleDefinition と IsListStyleReference は、独自の書式を定義するリストと、リンクされた Style(List.Style で利用可能)を介して書式を参照するリストを区別します。すべての文書のリストは Document.Lists を通じて取得でき、ListCollection を返します:ListCollection.Add(listTemplate) は Word の事前定義された ListTemplate 書式のいずれかから新しいリストを作成し、Add(listStyle) は Style から作成し、AddSingleLevelList(listTemplate) は単一レベルのバリアントを作成し、AddCopy(srcList) は既存のリストを複製します — これにより、段落が同じカウンタを共有せずに独立した番号付け(新たな再開)を持たせたい場合に便利です。ListCollection.GetListByListId(listId) は特定のリストを取得し、Count は文書が持つリスト数を報告します。
ListFormat を使用した段落へのリスト適用
ListFormat は段落の書式設定から取得でき、段落がどのリストに属し、どのレベルにあるかを制御します。ListFormat.List は段落が使用している List で、ListFormat.ListLevelNumber はそのリスト内のゼロベースのレベルです;IsListItem は段落がリストの一部であるかどうかを報告します。ApplyBulletDefault() と ApplyNumberDefault() は、Word のデフォルトの箇条書きまたは番号付きリスト書式を段落に一度に適用し、RemoveNumbers() はリスト書式を削除します。ListIndent()/ListOutdent() は段落をリストのレベルを深くしたり浅くしたり移動させます — これは、リスト段落の先頭で Tab キーまたは Shift+Tab キーを押したときに Word が実行する操作と同じです。
リストレベルと番号付けスタイル
ListLevel はリストの 1 レベルの書式設定を保持します: NumberStyle(NumberStyle 列挙値、たとえばアラビア数字やローマ数字)、NumberFormat(番号とリテラルテキスト(句点や括弧など)を結合した書式文字列)、StartAt(開始番号)、および RestartAfterLevel(どの上位レベルのインクリメントがこのレベルのカウンタをリセットするか)。Alignment(ListLevelAlignment 値: Left, Center, Right)および TrailingCharacter(ListTrailingCharacter 値: Tab, Space, Nothing)は、ラベルの位置と段落テキストからの区切り方を制御し、TabPosition, NumberPosition, TextPosition と共に正確なレイアウトを調整します。IsLegal は法的スタイルの番号付けを強制します(NumberStyle に関係なく常にアラビア数字)、LinkedStyle はレベルを段落 Style に関連付けます。画像の箇条書きについては、CreatePictureBullet() と DeletePictureBullet() が ImageData の箇条書き画像を管理し、ListLevel.Font が番号または箇条書き文字自体の書式設定を設定します。ListLevel.GetEffectiveValue(index, numberStyle, customNumberStyleFormat) は番号付けシーケンスの特定位置で実際のラベル値を計算します。
リストラベルと定義済みテンプレート
ListLabel は特定のリスト項目インスタンスに対してレンダリングされたラベルを記述します — LabelString は Word が表示するリテラルテキスト(例: “3.” や “•")で、LabelValue は基礎となる数値、Font はラベルの書式です。ListTemplate は Word の定義済みリスト形式の列挙型で(箇条書きスタイルは BulletDefault, BulletDisk, BulletCircle, BulletSquare, BulletDiamonds、および番号付き形式)、ListCollection.Add(listTemplate) と組み合わせて、プロパティを一つずつ構築する代わりに組み込み形式から開始するために使用されます。
ヒントとベストプラクティス
- 他の段落にすでに付与されている
Listを再利用するのではなく、段落の新しいグループが独立してリスト番号付けを最初からやり直す必要がある場合は、ListCollection.AddCopy(srcList)を使用します。 - 標準的なリストでは、すべての
ListLevelプロパティを手動で設定する代わりに、ListFormat.ApplyNumberDefault()/ApplyBulletDefault()を使用することを推奨します。 - リストの書式設定を直接変更する前に、
List.IsListStyleReferenceとIsListStyleDefinitionを比較してください — スタイル参照リストの書式は、リンクされたStyleによって制御されている場合があります。 - 番号付けを特定のアウトラインレベルでリセットする必要がある場合に、デフォルトの再開動作に依存するのではなく、入れ子リストでは
RestartAfterLevelを明示的に設定してください。 ListFormat.ListIndent()/ListOutdent()を使用して段落をリストレベル間で移動してください。ListLevelNumberを直接設定する代わりに、これらの方法は段落のリスト書式を内部的に一貫させたまま保ちます。
一般的な問題
| 問題 | 原因 | 修正 |
|---|---|---|
| 独立して番号付けすべき2つの段落が同じシーケンスで続いている | 両方の段落のListFormat.Listは同じ共有Listオブジェクトを参照しています | 2番目の段落には、同じListを再利用するのではなく、ListCollection.AddCopy(srcList)を使って独自のリストを付与してください |
| カスタム番号付けフォーマット文字列が期待どおりにレンダリングされません | ListLevel.NumberFormatは、レベルのNumberStyleに対する期待されるパターンと一致しません | 編集中のレベルに対して、NumberFormat と NumberStyle が一貫して設定されていることを確認してください |
| レベルをプログラムで変更した後、リストのインデントが正しくないように見えます | ListLevelNumber が直接設定され、関連する位置プロパティが更新されていませんでした | ListLevelNumber を直接設定する代わりに、ListFormat.ListIndent()/ListOutdent() を使用してください |
| 画像の箇条書きが表示されません | そのレベルに画像の箇条書きが作成されていないか、デフォルトのテキスト箇条書き書式がまだ有効です | テキスト箇条書きの書式を削除する前に、ListLevel.CreatePictureBullet() を呼び出し、画像データを提供してください |
FAQ
List と ListFormat の違いは何ですか?
List は段落間で共有される再利用可能な番号付け/箇条書き定義です。ListFormat は段落単位で、特定の段落が使用する List とそのレベルを ListFormat.List と ListLevelNumber を通じて指し示します。
段落がリストの一部かどうかを確認するにはどうすればよいですか?
段落の書式に関しては ListFormat.IsListItem を参照してください。true の場合、ListFormat.List と ListLevelNumber がその段落が属するリストとレベルを記述します。
既存のリストとは独立して、新しいリストを 1 から番号付けさせるにはどうすればよいですか?
ListCollection.AddCopy(srcList) を使用してリスト定義の独立したコピーを作成し、そのコピーを新しい段落に適用します — 元の List を再利用せずに、同じカウンタが継続されるのを防ぎます。
箇条書きまたは番号付きリストをゼロから作成するにはどうすればよいですか?
Word の既定書式には ListFormat.ApplyBulletDefault() または ApplyNumberDefault() を使用し、Word の事前定義された書式のいずれかから開始し、ListTemplate 値を伴う ListCollection.Add(listTemplate) を使用して、結果として得られる List.ListLevels をカスタマイズします。
「1.」ではなく「1)」のように番号形式を制御するにはどうすればよいですか?
該当レベルで ListLevel.NumberFormat を希望の書式文字列に設定し、数値スタイル自体には NumberStyle を併せて設定します。
API Reference の概要
| クラス/メソッド | 説明 |
|---|---|
List | 再利用可能なリスト(番号付/箇条書き)定義 |
ListCollection | 文書内のすべてのリストのコレクション |
ListCollection.Add(listTemplate) / AddCopy(srcList) | 事前に定義されたテンプレートからリストを作成するか、既存のリストをコピーする |
ListFormat | 各段落ごとに List と現在のレベルへの参照 |
ListFormat.ApplyBulletDefault() / ApplyNumberDefault() | 段落にデフォルトの箇条書きまたは番号付き書式を適用する |
ListLevel | List の 1 レベルの番号付け/箇条書き書式 |
ListLevel.NumberStyle / NumberFormat | レベルの数値スタイルと書式文字列 |
ListLabel | 特定のリスト項目に対してレンダリングされたラベル(テキストと値) |
ListTemplate | Word の事前定義されたリスト形式の列挙型 |