Praca z niestandardowym XML Markup

Praca z niestandardowym XML Markup

Ten przewodnik pokazuje, jak odczytywać i zarządzać niestandardowymi danymi XML, które dokument Word może zawierać obok swojej widocznej treści — danych używanych do powiązania kontrolek treści, przechowywania metadanych specyficznych dla aplikacji lub osadzania dowolnych części pakietu. Document.CustomXmlParts udostępnia dane niestandardowe XML na poziomie dokumentu, a Document.PackageCustomParts udostępnia niestandardowe części na poziomie pakietu, które nie są specyficznie XML.

Niestandardowe części XML

CustomXmlPart reprezentuje jedną niestandardową wyspę danych XML dołączoną do dokumentu — ten sam mechanizm, którego Word używa do obsługi kontrolek treści mapowanych na XML. Każda część ma Id, tablicę bajtów Data zawierającą surowe XML, DataChecksum oraz własność Schemas (CustomXmlSchemaCollection) wymieniającą schematy XML z nią powiązane. Document.CustomXmlParts zwraca CustomXmlPartCollection: Add(part) dołącza istniejący CustomXmlPart, Add(id, xml) tworzy go bezpośrednio z identyfikatora i ciągu XML, GetById(id) pobiera określoną część, a RemoveAt(index)/Clear() usuwają części. Zarówno CustomXmlPart, jak i CustomXmlPartCollection udostępniają Clone() do duplikowania niestandardowych danych XML, na przykład przy kopiowaniu treści między dokumentami.

Niestandardowe schematy XML

CustomXmlSchemaCollection, osiągnięty przez CustomXmlPart.Schemas, wymienia URI schematów powiązane z niestandardową częścią XML. Obsługuje Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() i Clone(), wraz z własnością Count — URI schematów są przechowywane jako zwykłe łańcuchy znaków, a nie jako zparsowane obiekty schematu.

Niestandardowe właściwości XML

Oddzielnie od CustomXmlPart, CustomXmlProperty reprezentuje pojedynczą właściwość XML typu nazwa/wartość, skonstruowaną przy użyciu CustomXmlProperty(name, uri, value) i udostępniającą Name, Uri oraz Value. CustomXmlPropertyCollection zarządza zestawem tych elementów: Add(property) dodaje jeden, indeksator (np. properties["MyProp"]) wyszukuje go po nazwie, a Contains(name) sprawdza, czy jest obecny, IndexOfKey(name) zwraca jego pozycję, a Remove(name)/RemoveAt(index)/Clear() usuwają wpisy. SmartTag.Properties zwraca CustomXmlPropertyCollection, co jest sposobem reprezentacji danych strukturalnych starszego smart tagu (patrz poniżej).

Części niestandardowe na poziomie pakietu

Document.PackageCustomParts zwraca CustomPartCollection CustomPart obiektów — dowolne części przechowywane w pakiecie OOXML, które nie są niestandardowymi danymi XML, takie jak części dodane przez inne aplikacje, które modyfikowały plik. Każdy CustomPart posiada Name, ContentType, RelationshipType, tablicę bajtów Data oraz flagę IsExternal wskazującą, czy część jest zewnętrznym odwołaniem, a nie osadzoną zawartością. Kolekcja obsługuje Add(part), RemoveAt(index), Clear() i Clone(), wraz z Count.

Starsze tagi inteligentne

SmartTag jest typem węzła (NodeType.SmartTag) reprezentującym starszy tag inteligentny Word otaczający rozpoznany tekst. SmartTag jest konstruowany przy użyciu SmartTag(doc) i udostępnia Element (nazwę elementu rozpoznawacza) oraz Uri (przestrzeń nazw rozpoznawacza), wraz z Properties — CustomXmlPropertyCollection przechowującym dane strukturalne, które rozpoznawacz dołączył do otagowanego tekstu. Ponieważ SmartTag jest węzłem, uczestniczy także w drzewie dokumentu jak inne węzły, obsługując Accept(visitor), AcceptStart(visitor) i AcceptEnd(visitor) dla przeglądania opartego na DocumentVisitor.

MarkupLevel

MarkupLevel jest wyliczeniem — Unknown, Inline, Block, Row, Cell — opisującym poziom strukturalny w drzewie dokumentu, na którym może wystąpić element znacznikowy, taki jak strukturalny tag dokumentu.

Wskazówki i najlepsze praktyki

• Użyj CustomXmlPartCollection.GetById(id) zamiast ręcznego iterowania po kolekcji, gdy znasz identyfikator potrzebnej części.
• Odczytaj CustomXmlPart.DataChecksum, aby wykryć, czy podstawowe dane XML uległy zmianie, bez przeprowadzania pełnego porównania bajtów.
• Rozróżnij Document.CustomXmlParts (niestandardowe dane XML, często powiązane z kontrolkami treści) od Document.PackageCustomParts (dowolne części pakietu nie-XML) — służą różnym celom i są przechowywane oddzielnie.
• Podczas pracy z starszymi dokumentami wykorzystującymi inteligentne znaczniki, sprawdź SmartTag.Element i Uri razem, aby zidentyfikować, który rozpoznawacz utworzył znacznik, zanim polegasz na jego Properties.
• Klonuj niestandardowe części XML przy użyciu CustomXmlPart.Clone() (lub Clone() kolekcji) podczas kopiowania danych między dokumentami, zamiast ponownie odczytywać i dodawać surowe XML.

Typowe problemy

FAQ

Jaka jest różnica między CustomXmlPart a CustomXmlProperty?

CustomXmlPart jest całym wyspą danych XML (z ładunkiem w postaci tablicy bajtów i powiązanymi schematami), dostępny przez Document.CustomXmlParts. CustomXmlProperty jest pojedynczą parą nazwa/wartość, zazwyczaj dostępny przez SmartTag.Properties zamiast bezpośrednio z dokumentu.

Jak dodać niestandardowe dane XML do dokumentu?

Wywołaj Document.CustomXmlParts.Add(id, xml) z ciągiem identyfikatora i zawartością XML, lub utwórz CustomXmlPart osobno i przekaż go do Add(part).

Czym są niestandardowe części pakietu i czym różnią się od niestandardowych części XML?

Document.PackageCustomParts (a CustomPartCollection CustomPart obiektów) przechowuje dowolne części pakietu OOXML, które nie są niestandardowymi XML — każda z ContentType, RelationshipType i surowym Data. Document.CustomXmlParts jest przeznaczony specjalnie dla niestandardowych wysp danych XML.

Czym jest SmartTag?

SmartTag jest starszą funkcją Worda reprezentującą tekst rozpoznany i otoczony przez rozpoznawacz smart-tagów. To węzeł dokumentu (NodeType.SmartTag) z Element i Uri identyfikującymi rozpoznawacz oraz kolekcją Properties wartości CustomXmlProperty dołączonych przez rozpoznawacz.

Jak skopiować niestandardowe dane XML między dokumentami?

Użyj CustomXmlPart.Clone() w części źródłowej, a następnie dodaj klon do Document.CustomXmlParts dokumentu docelowego z Add(part).

API Reference Podsumowanie

Zobacz także

• Aspose.Words for .NET — Enterprise Documentation