カスタム XML マークアップの使用

カスタム XML マークアップの操作

このガイドでは、Word 文書が可視コンテンツと共に保持できるカスタム XML データの読み取りと管理方法を示します — コンテンツ コントロールのバインド、アプリケーション固有のメタデータの保存、または任意のパッケージ パーツの埋め込みに使用されるデータです。Document.CustomXmlParts はドキュメント レベルのカスタム XML データを公開し、Document.PackageCustomParts はカスタム XML ではないパッケージ レベルのカスタム パーツを公開します。

カスタム XML パーツ

CustomXmlPart は、ドキュメントに添付されたカスタム XML データ アイランドを 1 つ表します — これは Word が XML にマップされたコンテンツ コントロールをサポートするために使用するのと同じメカニズムです。各パーツは Id と、生の XML を保持する Data バイト配列、 DataChecksum、およびそれに関連付けられた XML スキーマを列挙する Schemas プロパティ（CustomXmlSchemaCollection）を持ちます。Document.CustomXmlParts は CustomXmlPartCollection を返します：Add(part) は既存の CustomXmlPart を添付し、Add(id, xml) は ID と XML 文字列から直接作成し、GetById(id) は特定のパーツを取得し、RemoveAt(index)/Clear() はパーツを削除します。CustomXmlPart と CustomXmlPartCollection の両方は、たとえばドキュメント間でコンテンツをコピーする際にカスタム XML データを複製するための Clone() を公開します。

カスタム XML スキーマ

CustomXmlSchemaCollection は、CustomXmlPart.Schemas を通じて取得でき、カスタム XML パーツに関連付けられたスキーマ URI を一覧表示します。Add(value)、Remove(name)、RemoveAt(index)、IndexOf(value)、Clear()、および Clone() をサポートし、さらに Count プロパティを備えています — スキーマ URI は解析されたスキーマ オブジェクトではなく、単なる文字列として追跡されます。

カスタム XML プロパティ

CustomXmlPart とは別に、CustomXmlProperty は単一の名前/値 XML プロパティを表し、CustomXmlProperty(name, uri, value) によって構築され、Name、Uri、および Value を公開します。CustomXmlPropertyCollection はこれらのセットを管理します：Add(property) は追加し、インデクサー（例：properties["MyProp"]）は名前で検索し、Contains(name) は存在するかテストし、IndexOfKey(name) はその位置を返し、Remove(name)/RemoveAt(index)/Clear() はエントリを削除します。SmartTag.Properties は CustomXmlPropertyCollection を返し、これはレガシー スマートタグの構造化データが表現される方法です（以下参照）。

パッケージレベルのカスタム パーツ

Document.PackageCustomParts は CustomPart オブジェクトの CustomPartCollection を返します — カスタム XML データではない、OOXML パッケージに保存された任意のパーツで、ファイルに触れた他のアプリケーションが追加したパーツなどです。各 CustomPart は Name、ContentType、RelationshipType、Data バイト配列、およびパーツが埋め込みコンテンツではなく外部参照であるかを示す IsExternal フラグを持ちます。コレクションは Add(part)、RemoveAt(index)、Clear()、Clone() をサポートし、Count も併せて利用できます。

レガシー スマートタグ

SmartTag は（NodeType.SmartTag）というノードタイプで、認識されたテキストを囲むレガシー Word スマートタグを表します。SmartTag は SmartTag(doc) で構築され、Element（レコグナイザ要素名）と Uri（レコグナイザの名前空間）を公開し、さらに Properties も提供します — これはレコグナイザがタグ付けされたテキストに付加した構造化データを保持する CustomXmlPropertyCollection です。SmartTag がノードであるため、他のノードと同様に文書ツリーに参加し、DocumentVisitor ベースのトラバーサルのために Accept(visitor)、AcceptStart(visitor)、AcceptEnd(visitor) をサポートします。

MarkupLevel

MarkupLevel は列挙型であり — Unknown、Inline、Block、Row、Cell — は、構造化文書タグのようなマークアップ要素が文書ツリー内で出現し得る構造レベルを表します。

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

• 必要なパーツのIDが分かっている場合は、コレクションを手動で反復処理するよりもCustomXmlPartCollection.GetById(id)を使用してください。
• 完全なバイト比較を行わずに、基になるXMLデータが変更されたかどうかを検出するには、CustomXmlPart.DataChecksumを読み取ります。
• カスタムXMLデータであり、しばしばコンテンツコントロールにバインドされるDocument.CustomXmlPartsと、任意の非XMLパッケージパーツであるDocument.PackageCustomPartsを区別してください — それらは異なる目的で使用され、別々に保存されます。
• スマートタグを使用するレガシードキュメントを扱う場合、SmartTag.ElementとUriを併せて確認し、タグを作成した認識子がどれかを特定してから、そのPropertiesに依存してください。
• ドキュメント間でデータをコピーする際、元のXMLを再読込して再追加するのではなく、CustomXmlPart.Clone()（またはコレクションのClone()）を使用してカスタムXMLパーツをクローンしてください。

一般的な問題

FAQ

CustomXmlPart と CustomXmlProperty の違いは何ですか？

CustomXmlPart は、XML データアイランド全体（バイト配列ペイロードと関連スキーマを含む）で、Document.CustomXmlParts を介してアクセスされます。CustomXmlProperty は単一の名前/値ペアで、通常はドキュメントから直接ではなく SmartTag.Properties を介して取得されます。

カスタム XML データをドキュメントに追加するにはどうすればよいですか？

id 文字列と XML コンテンツを指定して Document.CustomXmlParts.Add(id, xml) を呼び出すか、CustomXmlPart を別途作成して Add(part) に渡します。

パッケージ カスタム パーツとは何ですか、そしてそれらはカスタム XML パーツとどう違うのですか？

Document.PackageCustomParts（CustomPart オブジェクトの CustomPartCollection）は、カスタム XML ではない任意の OOXML パッケージ パーツを保持します — 各パーツは ContentType、RelationshipType、および生の Data を持ちます。Document.CustomXmlParts は特にカスタム XML データアイランド用です。

SmartTag とは何ですか？

SmartTag は、スマートタグ認識子によって認識されラップされたテキストを表すレガシーな Word 機能です。これは、認識子を特定する Element と Uri を持つドキュメントノード（NodeType.SmartTag）で、認識子が付与した CustomXmlProperty 値の Properties コレクションです。

カスタム XML データをドキュメント間でコピーするにはどうすればよいですか？

ソース部分に CustomXmlPart.Clone() を使用し、クローンをターゲット文書の Document.CustomXmlParts に Add(part) で追加します。

API Reference の概要

参照

• Aspose.Words for .NET — Enterprise Documentation