Structured Document Tags を .NET で操作する方法

ステップ 1: パッケージのインストール

Aspose.Words FOSS for .NET はまだ NuGet パッケージを公開していません — 代わりにソースからライブラリをビルドしてください。https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git をクローンし、.NET SDK を使用して Release 設定で Aspose.Words.sln をビルドし、生成された Aspose.Words アセンブリをプロジェクトから参照します。このライブラリは .NET Standard 2.0 を対象としているため、.NET Framework 4.6.2 以降および .NET 6/8/10 で動作します。

ステップ 2: 必要なクラスのインポート

Document と DocumentBuilder のために using Aspose.Words; ディレクティブを追加し、StructuredDocumentTag、SdtType、SdtListItem、SdtListItemCollection、XmlMapping、および本ガイドで取り上げるその他のコンテンツコントロールクラスのために using Aspose.Words.Markup; ディレクティブを追加します。

ステップ 3: 挿入できるコンテンツ コントロールの種類を確認する

挿入する前に、対象の SdtType が DocumentBuilder.InsertStructuredDocumentTag(SdtType) が受け入れる 7 種類のうちの一つかどうかを確認してください: PlainText、RichText、Checkbox、DropDownList、ComboBox、Picture、および Date。RepeatingSection と RepeatingSectionItem はこの方法ではテキストカーソルに挿入できません――それらは段落全体やテーブル行全体をラップします。Word ファイルに現れるが、Word UI の挿入可能なタイプとして表示されない残りの SdtType 値――None、Bibliography、Citation、Equation、BuildingBlockGallery、DocPartObj、Group、および EntityPicker――は、この挿入方法ではまったく受け付けられません。

ステップ 4: カーソル位置にコンテンツ コントロールを挿入する

ビルダーの現在のカーソル位置に新しいコントロールを挿入するため、DocumentBuilder.InsertStructuredDocumentTag(SdtType) を 7 つのサポートされたタイプのいずれかで呼び出します；呼び出しは新しい StructuredDocumentTag を返します。返されたコントロールに対して Tag と Title を設定し、作者が Word で見る識別文字列を付与し、PlaceholderName（Placeholder BuildingBlock に裏付けられる）を設定して、コントロールが空の場合に Word が表示するプロンプトテキストを指定します――IsShowingPlaceholderText はそのプロンプトが現在表示されているかどうかを報告します。

ステップ 5: タイプ固有のコンテンツを構成する

チェックボックス コントロールの場合、StructuredDocumentTag.Checked を読み書きし、SetCheckedSymbol() / SetUncheckedSymbol() を呼び出して各状態に表示されるグリフをカスタマイズします。日付コントロールの場合、FullDate を設定し、DateDisplayFormat と DateDisplayLocale が表示方法を制御し、DateStorageFormat（SdtDateStorageFormat）が XML データにバインドされたときの保存方法を制御し、CalendarType（SdtCalendarType）がカレンダー システムを選択します。ドロップダウン リストまたはコンボ ボックスの場合、ListItems を入力します――SdtListItem（DisplayText、Value）の SdtListItemCollection です――その後 SelectedValue を設定してアクティブな選択肢を選びます。プレーンテキスト コントロールの場合、Multiline は StructuredDocumentTag 上の bool プロパティで、コントロールの構成に設定できます。

ステップ 6: コントロールの外観とロック設定

Appearance（SdtAppearance）を設定して、Word でコントロールが視覚的にどのように区切られるかを制御し、Color でハイライト色を設定します。ContentsFont と EndCharacterFont はコントロールの内容と末尾文字に適用されるフォントを制御します。LockContentControl と LockContents は独立したスイッチです――LockContentControl を設定するとコントロール自体の削除をブロックし、LockContents を設定すると内部の編集をブロックしますが、互いには影響しません。

ステップ7: コンテンツ コントロールの検索と削除

Range.StructuredDocumentTags を読み取ります――その範囲にスコープされた StructuredDocumentTagCollection――そして GetById()、GetByTag()、または GetByTitle() を呼び出して特定のコントロールを検索するか、コレクション上の Remove() / RemoveAt() を使用して参照またはインデックスで削除します。個々のコントロールに対しては、Remove() を呼び出してコントロールとその内容を同時に削除し、RemoveSelfOnly() を呼び出してラッパーのみを削除し内容は文書に残し、または Clear() を呼び出して内容を空にし、コントロール自体はそのまま残します。

ステップ8: コントロールをカスタム XML データにバインドする

StructuredDocumentTag.XmlMapping を読み取ります――XmlMapping インスタンス――そして SetMapping(customXmlPart, xPath, prefixMapping) を呼び出して、ドキュメントのカスタム XML データストアに既に存在するカスタム XML パートにコントロールをバインドします。その際、バインド対象の要素を選択するために XPath 式を使用します。XmlMapping.IsMapped はバインドが現在アクティブかどうかを報告し、CustomXmlPart と StoreItemId はバインドされたデータパートを特定し、Delete() はマッピングを削除します。

ステップ9: 複数のセクションにまたがるコンテンツ コントロールの処理

1つ以上のドキュメント セクションにまたがるコンテンツ コントロール――IsMultiSection が報告――は、単一の StructuredDocumentTag ノードではなく、StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd のペアで表され、StructuredDocumentTagRangeStart.RangeEnd を介して接続されます。具体的な型で分岐するのではなく、単一ノード形式と範囲形式の両方を統一的に処理する必要がある場合は、共通の IStructuredDocumentTag インターフェイス（Tag、Title、Placeholder、PlaceholderName、Appearance、IsShowingPlaceholderText、RemoveSelfOnly()）を使用してプログラミングしてください。