FieldBuilder を使用したフィールドの構築
FieldBuilder を使用したフィールドの構築
このガイドでは、Aspose.Words FOSS を使用し、.NET 用に Word フィールドをゼロから構築する方法を示します FieldBuilder and FieldArgumentBuilder, 既に文書内に存在するフィールドを操作する代わりに。既存のフィールドを読み取り、更新、または削除する場合は、以下をご覧ください フィールドの操作 ガイド。
FieldBuilder でフィールドを作成する
FieldBuilder はフィールドコードトークン（引数とスイッチ）からフィールドを構築します。new FieldBuilder(fieldType) を使用して、構築したいフィールドの FieldType を渡すことで作成します。引数は、オーバーロードされた AddArgument(argument) メソッドで追加でき、string、int、double、入れ子の FieldBuilder、または FieldArgumentBuilder を受け取ります。スイッチは、オーバーロードされた AddSwitch(switchName)、AddSwitch(switchName, switchArgument)（文字列）、または AddSwitch(switchName, switchArgument)（int/double）メソッドで追加します。
構築したフィールドの挿入
FieldBuilder に引数とスイッチが設定されたら、BuildAndInsert(refNode) を呼び出してドキュメントに挿入します。オーバーロードの一つは Inline ノードを受け取り、その前にフィールドを挿入し、もう一つは Paragraph を受け取ってその段落の末尾にフィールドを挿入します。
FieldArgumentBuilder で複雑な引数を構成する
FieldArgumentBuilder は、フィールド、ノード、プレーンテキストで構成された複合フィールド引数を構築します。単一の引数がプレーン文字列だけでは足りない場合に使用します。new FieldArgumentBuilder() で作成し、プレーンテキストを追加するには AddText(text) を呼び、Inline ノードを追加するには AddNode(node) を、または別のフィールド（自身の FieldBuilder で構築された）を引数内にネストするには AddField(fieldBuilder) を使用します。完成した FieldArgumentBuilder を FieldBuilder.AddArgument(argument) に渡すと、外側フィールドの引数の一つとして使用できます。
ヒントとベストプラクティス
- 専用のフィールドクラス（
FieldDateやFieldSymbolなど）に裏付けられていないフィールドタイプを構築する場合、またはデータからプログラム的にフィールドコードを生成し、手作業で作成しない場合は、FieldBuilderを使用します。 - シンプルなケースでは
FieldBuilder.AddArgument(FieldBuilder)を使用して子フィールドを外側フィールドの引数にネストし、引数が単一フィールド以上の場合は、テキスト、ノード、ネストされたフィールドを混在させた引数をFieldArgumentBuilderで構築します。 - フィールドを配置したい場所に合う
BuildAndInsert(refNode)のオーバーロードを選択してください — 特定のInlineノードの前、またはParagraphの末尾です。 BuildAndInsertの後、結果をツリー内の他のフィールドと同様に扱います — 例えば、フィールドタイプが明示的な再計算を必要とする場合は、Update()を呼び出します。
一般的な問題
| 問題 | 原因 | 修正 |
|---|---|---|
BuildAndInsert が誤った場所を対象としています | 意図した挿入位置に対して誤ったオーバーロードが使用されました | それの前に挿入するには Inline ノードを渡し、末尾に挿入するには Paragraph を渡してください |
| フィールド引数はプレーンテキストとノードを同時に受け付けません | AddArgument は、合成引数ではなく単一の string/int/double で呼び出されました | 混合引数を FieldArgumentBuilder（AddText, AddNode, AddField）で構築し、それを AddArgument に渡してください |
| 構築されたフィールドコードでスイッチ値が認識されません | スイッチが実際には引数を必要とするのに、AddSwitch(switchName) が使用されました | スイッチの文字列、int、または double 値とともに AddSwitch(switchName, switchArgument) オーバーロードを使用してください |
FAQ
事前に作成されたフィールドコードを挿入する代わりに、FieldBuilder を使用すべきはいつですか？
事前に作成されたフィールドコード文字列を挿入するのではなく、フィールドの引数やスイッチをプログラムで構築する際に明示的な制御が必要なときに、FieldBuilder を使用します。
フィールドに複数の引数を追加するにはどうすればよいですか？
各引数ごとに AddArgument を呼び出します — それは string、int、double、入れ子の FieldBuilder、および FieldArgumentBuilder 用にオーバーロードされています。
引数にテキストと別のフィールドの混在を含むフィールドを構築できますか？
はい — 必要に応じて AddText、AddNode、AddField を呼び出す FieldArgumentBuilder を使用し、最後にそれを FieldBuilder.AddArgument に渡します。
実際に構築したフィールドを文書に挿入するにはどうすればよいですか？
BuildAndInsert(refNode) を呼び出し、Inline ノード（その前に挿入）または Paragraph（その末尾に挿入）のいずれかを渡します。
API Reference 概要
| クラス/メソッド | 説明 |
|---|---|
FieldBuilder | フィールドコードトークン（引数とスイッチ）からフィールドを構築します |
FieldBuilder(fieldType) | 構築するために FieldType を受け取るコンストラクタ |
FieldBuilder.AddArgument(argument) | 引数（string、int、double、FieldBuilder、または FieldArgumentBuilder）を追加します |
FieldBuilder.AddSwitch(switchName) / AddSwitch(switchName, switchArgument) | フィールドスイッチを追加します（値があってもなくても） |
FieldBuilder.BuildAndInsert(refNode) | 構築したフィールドを Inline ノードの前、または Paragraph の末尾に挿入します |
FieldArgumentBuilder | テキスト、ノード、入れ子フィールドから複雑なフィールド引数を構築します |
FieldArgumentBuilder.AddText(text) | 引数にプレーンテキストを追加します |
FieldArgumentBuilder.AddNode(node) | 引数に Inline ノードを追加します |
FieldArgumentBuilder.AddField(fieldBuilder) | 引数に FieldBuilder が構築したフィールドを入れ子にします |
