フィールドの操作
概要
Word フィールド – DATE, IF, DATABASE, REF、他にも何十ものフィールドが – は次で表現されます Aspose.Words FOSS for .NET によって Field クラスおよびそのサブクラス、すべてが Aspose.Words.Fields 名前空間です。このページはコア フィールド エンジンをカバーしています: Field オブジェクトモデル自体、フィールドの収集と更新の方法、そしてフィールド更新時にカスタムデータや動作をプラグインできるコールバックインターフェイスについて説明します。特定のフィールドファミリ―――ハイパーリンクと相互参照、日付/時刻フィールド、メールマージフィールド、インデックスおよび目次フィールド――それぞれに専用の開発者向けガイドページがあります。
フィールド オブジェクトモデル
文書内のすべてのフィールドは Field インスタンスであり、3 つのマーカーノード – FieldStart、Separator、FieldEnd – で構成され、これらは Field.Start、Field.Separator、Field.End プロパティとして公開されます。Field.Type はフィールドが表す FieldType を識別し、Field.Result と Field.DisplayResult は最後に計算された値を示し、Field.Format はフィールドコードに付随するスイッチ(数値形式や日時形式文字列など)を保持します。Field.IsLocked と Field.IsDirty はフィールドのロック状態と古さ(ステイル)状態を報告します。Field.GetFieldCode() を呼び出すと生のフィールドコードテキストを取得でき、Field.Update() で結果を再計算し、Field.Unlink() でフィールドを静的テキストに置き換え、Field.Remove() で完全に削除します。
文書内のフィールドへのアクセスと更新
Document.Range.Fields は FieldCollection を返します――その範囲に含まれるフィールドで、Count、Remove()、RemoveAt()、Clear() を使用して一括削除が可能です。Range.UpdateFields() は範囲内のすべてのフィールドを再計算し、Range.UnlinkFields() は範囲内のすべてのフィールドを静的テキストに変換し、Range.NormalizeFieldTypes() は手動編集後にフィールドの保存されたタイプコードと実際のフィールドコードを照合します。DocumentBuilder.InsertField() はカーソル位置に新しいフィールドを挿入し、オーバーロードにより新しいフィールドの結果を即座に更新するか、後の Range.UpdateFields() パスで更新するかを選択できます。
フィールド更新オプションとカルチャ
Document.FieldOptions は、更新時にドキュメント全体のフィールドの挙動を制御する FieldOptions インスタンスです。CurrentUser は ID フィールドで使用される UserInformation を提供し、DefaultDocumentAuthor は著者関連の結果をシードし、LegacyNumberFormat と UseInvariantCultureNumberFormat は数値書式を制御し、PreProcessCulture と FieldUpdateCultureSource(IFieldUpdateCultureProvider コールバックとペアで)は、更新時に日付と数値書式を支配するカルチャーを決定します。TemplateName、FileName、および BuiltInTemplatesPaths は、テンプレートおよびファイル名対応フィールドが読み戻す値を提供します。
フィールド更新の追跡とカスタマイズ
IFieldUpdatingCallback(FieldUpdating と FieldUpdated)を FieldOptions に実装すると、各フィールドが再計算される直前と直後にコードを実行できます――バッチジョブでどのフィールドが変更されたかを監査するのに便利です。IFieldUpdatingProgressCallback(Notify)を実装すると、大規模ドキュメント全体の進捗を追跡できます;それは FieldUpdatingProgressArgs を受け取り、TotalFieldsCount、UpdatedFieldsCount、UpdateCompleted を含みます。フィールドの数値または一般的な結果がテキストとしてどのように表示されるかを変更するには、IFieldResultFormatter(Format(value, format) と FormatNumeric(value, format))を実装し、FieldOptions.ResultFormatter に割り当てます。
フィールドへの外部データの供給
DATABASE フィールドは IFieldDatabaseProvider.GetQueryResult() を通じて行を読み取り、IFieldDatabaseProvider.GetQueryResult() は FieldDatabaseDataRow(Values)インスタンスから構築された FieldDatabaseDataTable(ColumnNames、Rows)を返します――実装は FieldOptions.FieldDatabaseProvider に割り当ててください。IF のような比較フィールドは IComparisonExpressionEvaluator.Evaluate() を通じて条件を評価し、IComparisonExpressionEvaluator.Evaluate() は ComparisonExpression(LeftExpression、ComparisonOperator、RightExpression)を受け取り、ComparisonEvaluationResult(Result、ErrorMessage)を返します。デフォルトの比較ロジックを上書きするには、カスタム評価子を FieldOptions.ComparisonExpressionEvaluator に割り当てます。通常、更新時にユーザーに入力を求めるフィールド(例:ASK と FILLIN)は、FieldOptions.UserPromptRespondent に割り当てられたときに IFieldUserPromptRespondent.Respond() を呼び出すため、無人更新が対話的入力でブロックされることはありません。
フィールド用のユーザーおよびドキュメント ID
UserInformation(Name、Initials、Address、および静的な UserInformation.DefaultUser)は、著者名およびユーザー名に関連するフィールドが参照する ID を提供します。ドキュメントの著者またはユーザー ID に依存するフィールドを更新する前に、Document.FieldOptions.CurrentUser にインスタンスを割り当ててください。
ヒントとベストプラクティス
- Aspose.Words FOSS は、Word のようにロードや保存時にフィールドを自動的に再計算しません – プログラム的に編集した後で、フィールド結果に反映させる必要がある場合は、必ず
Range.UpdateFields()(単一フィールドの場合はField.Update())を呼び出してください。 FieldStart、Separator、FieldEndは文書ツリー内の実際のノードです。マーカーノードを直接削除せず、Field.Remove()またはField.Unlink()を介してフィールドを削除してください。そうしないと、フィールド構造が不整合になる可能性があります。- ページレイアウトに依存する結果を持つフィールド(
PAGE、NUMPAGES、および目次のページ番号エントリ)は、プレースホルダー0に評価されます。これは、本エディションにページレイアウト/レンダリングエンジンが含まれていないためです。 - 大規模または未知の文書に対して
Range.UpdateFields()を実行する前に、変更されたフィールドを正確に記録または監査する必要がある場合は、IFieldUpdatingCallbackを登録してください。 - 無人パイプラインで文書を更新する前に
FieldOptions.UserPromptRespondentを設定する(または個々のプロンプト駆動フィールドクラスにDefaultResponseの値を提供する)ことで、ASK/FILLINフィールドが対話入力を待って停止しないようにします。
一般的な問題
| 問題 | 原因 | 修正 |
|---|---|---|
| ドキュメントを編集した後、フィールド結果が古くなっています | Aspose.Words FOSS はロード時または保存時にフィールドを自動更新しません | Range.UpdateFields() または Field.Update() を明示的に呼び出してください |
PAGE、NUMPAGES、または TOC ページ番号が 0 を示します | ページレイアウト/レンダリングはこのエディションには含まれていません | 期待される動作 – 商用版を使用してください Aspose.Words(.NET 用) 計算されたページ番号が必要な場合 |
DATABASE フィールドは行を生成しません | FieldOptions.FieldDatabaseProvider に IFieldDatabaseProvider が割り当てられていません | IFieldDatabaseProvider を実装し、Range.UpdateFields() を呼び出す前に割り当ててください |
| バッチフィールドの更新がハングしているようです | プロンプト駆動フィールド(ASK, FILLIN)に IFieldUserPromptRespondent が割り当てられていません | FieldOptions.UserPromptRespondent を割り当てるか、フィールドインスタンス上で DefaultResponse を設定してください |
FAQ
Aspose.Words FOSS はすべての Word フィールドタイプを評価しますか?
Field オブジェクトモデルはすべての FieldType 値を表し、ほとんどを更新しますが、ページレイアウトに依存する結果を持つフィールド(例: PAGE と NUMPAGES)– このエディションにはレイアウト/レンダリングエンジンが含まれていないため、プレースホルダー 0 と評価されます。
プログラムで文書を編集した後、フィールドを再評価するにはどうすればよいですか?
編集されたコンテンツをカバーする範囲に対して Range.UpdateFields() を呼び出すか、文書内のすべてのフィールドを更新するには Document.Range.UpdateFields() を使用します。
フィールドを普通の静的テキストに変換できますか?
はい – Field.Unlink() はフィールドを最後に計算された結果の普通のテキストに置き換え、基になるフィールドコードを削除します。
結果も含めてフィールドを完全に削除するにはどうすればよいですか?
Field.Remove() を呼び出します。これにより、フィールドのコードと結果コンテンツとともに、FieldStart、Separator、FieldEnd ノードが削除されます。
カスタムデータを DATABASE フィールドに供給するにはどうすればよいですか?
IFieldDatabaseProvider を実装し、Document.FieldOptions.FieldDatabaseProvider に割り当ててください。あなたの GetQueryResult() 実装は、FieldDatabaseDataRow インスタンスから構築された FieldDatabaseDataTable を返します。
API Reference 概要
| クラス / インターフェイス | 説明 |
|---|---|
Field | Word フィールドの基底クラス; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | 範囲内のフィールド、Range.Fields を使用; Count, Remove(), Clear() |
FieldType | どの Word フィールドを Field インスタンスが表すかを識別する列挙型 |
FieldOptions | ドキュメント全体のフィールド更新設定、Document.FieldOptions を介して |
IFieldUpdatingCallback | 各フィールド更新の前後に FieldUpdating / FieldUpdated フック |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | バルクフィールド更新における進捗報告 |
IFieldResultFormatter | フィールドの計算結果のカスタム書式設定 |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | 「DATABASE」フィールドの外部データソース |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | 比較形式フィールド式のカスタム評価 |
IFieldUserPromptRespondent | 無人アップデートのプロンプト駆動フィールドに対する応答を提供します |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | フィールド更新時のカルチャー選択 |
UserInformation | 作成者/ユーザーのアイデンティティ(Name, Initials, Address)は、アイデンティティフィールドによって読み取られます |