構造化ドキュメントタグ（コンテンツコントロール）の操作

構造化ドキュメントタグ（コンテンツ コントロール）の操作

構造化文書タグ (SDT) は、Word UI ではコンテンツコントロールとして知られ、型付けされた制約付き編集動作――チェックボックス、日付ピッカー、ドロップダウンリスト、またはプレーンテキストまたはリッチテキストのプレースホルダー――で文書の一部をラップします。 Aspose.Words の .NET 用 FOSS これらを通じてモデル化します Aspose.Words.Markup 名前空間で、先頭にあるのは StructuredDocumentTag クラス。このページでは、コンテンツコントロールの挿入、各タイプの設定、検索と削除、そしてカスタム XML データへのバインディングについて説明します。

構造化ドキュメントタグオブジェクトモデル

StructuredDocumentTag は CompositeNode であり、IMarkupNode、ITrackableNode、IStructuredDocumentTag も実装しています。SdtType はコントロールの種類を識別します。Tag と Title は、作者が Word で設定した識別文字列を保持します；Placeholder（BuildingBlock）と PlaceholderName は、コントロールが空の場合に表示されるプロンプトテキストを提供し、IsShowingPlaceholderText を通じて報告されます。LockContentControl はコントロールの削除を防止し、LockContents はその内容の編集を防止します。これらは互いに独立しています。

コンテンツ コントロールの挿入

DocumentBuilder.InsertStructuredDocumentTag(SdtType) はカーソル位置に新しいコントロールを挿入しますが、SdtType のうち 7 つの値に限られます：PlainText、RichText、Checkbox、DropDownList、ComboBox、Picture、および Date。RepeatingSection と RepeatingSectionItem はこの方法でテキストカーソルに挿入できません——代わりに段落全体やテーブル行全体をラップします。Word ファイルに存在するが Word UI では挿入可能なタイプとして表示されない残りの SdtType 値、すなわち None、Bibliography、Citation、Equation、BuildingBlockGallery、DocPartObj、Group、および EntityPicker は、この挿入方法ではサポートされていません。

タイプ固有のコンテンツ

チェックボックスコントロールの状態は StructuredDocumentTag.Checked です；SetCheckedSymbol() と SetUncheckedSymbol() は各状態で表示されるグリフを設定します。日付コントロールはその値を FullDate に保存し、DateDisplayFormat と DateDisplayLocale がレンダリング方法を制御し、DateStorageFormat（SdtDateStorageFormat）が XML データにバインドされたときの保存方法を制御し、CalendarType（SdtCalendarType）がカレンダーシステムを選択します。ドロップダウンリストまたはコンボボックスは ListItems を介して選択肢を公開し、SdtListItemCollection は SdtListItem（DisplayText、Value）の SelectedValue です。プレーンテキストコントロールの Multiline プロパティは、内部で改行を許可または禁止します。

外観とロック

Appearance（SdtAppearance）は、Word でコントロールが視覚的に区切られる方法を制御します。Color はハイライト色を設定し、ContentsFont / EndCharacterFont は内容に適用されるフォントと末尾文字を制御します。LockContentControl と LockContents は独立したスイッチで、前者はコントロール自体の削除をブロックし、後者は内部の編集をブロックします。

コンテンツコントロールの検索と削除

Range.StructuredDocumentTags は、その範囲にスコープされた StructuredDocumentTagCollection を返し、GetById()、GetByTag()、GetByTitle() をターゲット検索に使用し、Remove() と RemoveAt() と併せて利用できます。個々の StructuredDocumentTag に対しては、Remove() がコントロールとその内容を一緒に削除し、RemoveSelfOnly() がラッパーだけを削除して内容は文書に残し、Clear() がコントロール自体は残したまま内容を空にします。

XML データバインディング

StructuredDocumentTag.XmlMapping は、ドキュメント内のカスタム XML パートへのバインディングを記述する XmlMapping インスタンスです：CustomXmlPart、XPath、PrefixMappings、StoreItemId、および IsMapped。SetMapping() は既存のカスタム XML パートへのバインディングを確立し、Delete() はそれを削除します。

マルチセクション（範囲）コンテンツコントロール

1つ以上のセクションにまたがるコンテンツ コントロール – IsMultiSection によって報告される – は、単一の StructuredDocumentTag ノードではなく、StructuredDocumentTagRangeStart と StructuredDocumentTagRangeEnd のペアで表され、StructuredDocumentTagRangeStart.RangeEnd を介して接続されます。単一ノード形式と範囲形式はどちらも共通の IStructuredDocumentTag インターフェイスを実装しているため、Tag、Title、SdtType、Placeholder などの識別プロパティだけが必要なコードは、どちらの形式でも同様に動作できます。

ヒントとベストプラクティス

• 使用する前に DocumentBuilder.InsertStructuredDocumentTag() のサポートされているタイプ一覧を確認してください – カーソルに挿入できるのは PlainText、RichText、Checkbox、DropDownList、ComboBox、Picture、Date のみです。その他のタイプは例外をスローします。
• コンテンツ コントロールを “flatten” したい場合は、Remove() の代わりに RemoveSelfOnly() を使用してください – 内容は文書に残しつつ、コントロールのラッパーは削除します。
• ListItems を、DropDownList または ComboBox コントロールが選択肢を表示する前に設定し、SelectedValue を使用してアクティブなものを選択してください。
• コードが通常のコンテンツ コントロールとマルチセクション（範囲）コンテンツ コントロールの両方を同じ方法で処理する必要がある場合は、StructuredDocumentTag を直接使用するのではなく、IStructuredDocumentTag に対してプログラミングしてください。
• XmlMapping.SetMapping() は、文書のカスタム XML データストアに既に存在しているカスタム XML パートにバインドします – コントロールをマッピングする前に、XML データを追加またはロードしてください。

一般的な問題

FAQ

DocumentBuilderで直接挿入できるコンテンツコントロールのタイプはどれですか？

PlainText、RichText、Checkbox、DropDownList、ComboBox、Picture、およびDateです。他のSdtTypeの値はInsertStructuredDocumentTag()ではサポートされていません。

特定のタグを持つすべてのコンテンツコントロールをどうやって検索しますか？

Range.StructuredDocumentTags.GetByTag()を使用してください。あるいは、代わりにそれらでマッチさせる場合はGetByTitle() / GetById()を使用します。

コンテンツコントロールを削除し、内容は保持するにはどうすればよいですか？

Remove()ではなくStructuredDocumentTag.RemoveSelfOnly()を呼び出してください。

コンテンツコントロールをカスタムXMLデータにバインドするにはどうすればよいですか？

コントロールで XmlMapping.SetMapping() を呼び出し、既存のカスタム XML パートとその中の XPath 式を指すようにします。

プレーンな StructuredDocumentTag とレンジ付きのものの違いは何ですか？

複数の文書セクションにまたがるコンテンツ コントロールは、単一ノードの代わりに StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd ペアとして表されます。両方の形態は IStructuredDocumentTag を実装しています。

API Reference サマリー

参照

• Aspose.Words for .NET — Enterprise Documentation