Egyéni XML jelölőnyelv használata

Az egyéni XML jelölőnyelv használata

Ez az útmutató bemutatja, hogyan olvasható és kezelhető a Word-dokumentum által a látható tartalom mellett hordozható egyedi XML adat — olyan adat, amelyet a tartalomvezérlők kötésére, alkalmazásspecifikus metaadatok tárolására vagy tetszőleges csomagrészek beágyazására használnak. Document.CustomXmlParts a dokumentumszintű egyedi XML adatot teszi elérhetővé, míg Document.PackageCustomParts a csomagszintű egyedi részeket (amelyek nem kifejezetten egyedi XML) teszi elérhetővé.

Egyedi XML részek

CustomXmlPart egy egyedi XML adat-szigetet képvisel, amely a dokumentumhoz csatolt — ugyanazt a mechanizmust használja a Word, amely a XML-hez rendelt tartalomvezérlőket támogatja. Minden rész rendelkezik egy Id-vel, egy Data bájt tömbbel, amely a nyers XML adatot tartalmazza, egy DataChecksum-val, és egy Schemas tulajdonsággal (egy CustomXmlSchemaCollection), amely felsorolja a hozzá tartozó XML sémákat. Document.CustomXmlParts egy CustomXmlPartCollection-t ad vissza: Add(part) egy meglévő CustomXmlPart-t csatol, Add(id, xml) egyet hoz létre közvetlenül egy azonosítóból és egy XML karakterláncból, GetById(id) egy konkrét részt kér le, és a RemoveAt(index)/Clear() eltávolítja a részeket. Mind a CustomXmlPart, mind a CustomXmlPartCollection Clone()-t biztosítja az egyedi XML adatok duplikálásához, például dokumentumok közötti tartalom másolásakor.

Egyedi XML sémák

CustomXmlSchemaCollection, amelyet a CustomXmlPart.Schemas útján érünk el, felsorolja a egyedi XML részhez tartozó séma URI-kat. Támogatja a Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() és Clone() elemeket, valamint egy Count tulajdonságot — a séma URI-kat egyszerű karakterláncként, nem pedig értelmezett sémaobjektumként követi nyomon.

Egyedi XML tulajdonságok

A CustomXmlPart-tól elkülönítve a CustomXmlProperty egyetlen név/érték XML tulajdonságot képvisel, amelyet a CustomXmlProperty(name, uri, value) segítségével hoznak létre, és amely a Name, Uri és Value elemeket teszi elérhetővé. A CustomXmlPropertyCollection kezeli ezen elemek halmazát: a Add(property) hozzáad egyet, az indexelő (például properties["MyProp"]) név szerint keres egyet, a Contains(name) ellenőrzi, hogy létezik-e, a IndexOfKey(name) visszaadja a pozícióját, és a Remove(name)/RemoveAt(index)/Clear() eltávolítják a bejegyzéseket. A SmartTag.Properties egy CustomXmlPropertyCollection-et ad vissza, amely a régi okos címke strukturált adatainak ábrázolása (lásd alább).

Csomagszintű egyedi részek

Document.PackageCustomParts egy CustomPartCollection-t ad vissza CustomPart objektumokból — tetszőleges részek, amelyek az OOXML csomagban tárolódnak, és nem saját XML adatok, például más alkalmazások által a fájlhoz hozzáadott részek. Minden CustomPart rendelkezik egy Name, ContentType, RelationshipType, egy Data byte tömbbel, és egy IsExternal jelzővel, amely azt jelzi, hogy a rész külső hivatkozás-e a beágyazott tartalom helyett. A gyűjtemény támogatja a Add(part), RemoveAt(index), Clear() és Clone() műveleteket, valamint a Count.

Örökölt okos címkék

SmartTag egy csomópont típus (NodeType.SmartTag), amely egy örökölt Word okos címkét képvisel, amely felismert szöveg köré van csomagolva. Egy SmartTag a SmartTag(doc) segítségével jön létre, és elérhetővé teszi a Element (a felismerő elem neve) és a Uri (a felismerő névtér) elemeket, valamint a Properties — egy CustomXmlPropertyCollection, amely a felismerő által a címkézett szöveghez csatolt strukturált adatot tartalmazza. Mivel a SmartTag csomópont, részt vesz a dokumentumfában, mint a többi csomópont, támogatja a Accept(visitor), AcceptStart(visitor) és AcceptEnd(visitor) műveleteket a DocumentVisitor alapú bejáráshoz.

MarkupLevel

MarkupLevel egy felsorolás — Unknown, Inline, Block, Row, Cell — amely leírja a dokumentumfában a strukturális szintet, ahol egy jelölőelem, például egy strukturált dokumentumcímke előfordulhat.

Tippek és legjobb gyakorlatok

Használja a CustomXmlPartCollection.GetById(id) elemet a gyűjtemény kézi bejárása helyett, ha ismeri a szükséges rész azonosítóját.
Olvassa a CustomXmlPart.DataChecksum értékét annak megállapításához, hogy az alatta lévő XML adat megváltozott-e, anélkül hogy teljes bájtos összehasonlítást végezne.
Megkülönböztetni a Document.CustomXmlParts elemet (egyedi XML adat, gyakran tartalomvezérlőkhöz kötve) a Document.PackageCustomParts elemtől (tetszőleges, nem XML csomagrész) — különböző célokat szolgálnak, és külön tárolódnak.
Régi, okos címkéket használó dokumentumok esetén ellenőrizze a SmartTag.Element és a Uri értékeket együtt, hogy meghatározza, melyik felismerő hozta létre a címkét, mielőtt a Properties értékére támaszkodna.
Klónozza az egyedi XML részeket a CustomXmlPart.Clone() (vagy a gyűjtemény Clone()) segítségével, amikor dokumentumok között másolja az adatokat, ahelyett, hogy újra beolvasná és újra hozzáadná a nyers XML elemet.

Gyakori problémák

Probléma	Ok	Javítás
`CustomXmlPartCollection.GetById(id)` nem ad vissza semmit felhasználható	Az azonosító nem egyezik semelyik jelenleg `Document.CustomXmlParts`-ben lévő résszel	Enumerálja a gyűjteményt az azonosító megerősítéséhez, vagy először adja hozzá a részt a `Add(id, xml)` segítségével
Az egyedi XML adatok látszólag nem kapcsolódnak a látható tartalomvezérlőkhöz	A tartalomvezérlők az egyedi XML-hez saját adatkötési beállításukon keresztül kapcsolódnak, nem automatikusan minden `CustomXmlPart`-hez	Erősítse meg, hogy a megadott tartalomvezérlő mely részhez van kötve, ahelyett, hogy `Document.CustomXmlParts` esetén 1:1 kapcsolatot feltételezne.
Egy másik alkalmazás által hozzáadott csomagrész nem található a(z) `CustomXmlParts`-ban.	A nem-XML csomagrészek a(z) `Document.PackageCustomParts` útján érhetők el, nem a(z) `CustomXmlParts`-n keresztül.	Ellenőrizze inkább a(z) `PackageCustomParts` (a(z) `CustomPartCollection`) elemet.
A(z) `SmartTag.Properties` üres.	Nem minden intelligens címke-felismerő csatol strukturált tulajdonságokat.	Ellenőrizze a(z) `SmartTag.Element`/`Uri` elemet, hogy megerősítse, melyik felismerő hozta létre a címkét, mielőtt konkrét tulajdonságokat várna.

FAQ

Mi a különbség a `CustomXmlPart` és a `CustomXmlProperty` között?

CustomXmlPart egy teljes XML adat-sziget (byte-array terheléssel és kapcsolódó sémákkal), amely a Document.CustomXmlParts útján érhető el. CustomXmlProperty egyetlen név/érték pár, általában a SmartTag.Properties útján érhető el, nem közvetlenül a dokumentumból.

Hogyan adhatok egyedi XML adatot egy dokumentumhoz?

Hívja meg a(z) Document.CustomXmlParts.Add(id, xml) függvényt egy azonosító karakterlánccal és a XML tartalommal, vagy készítsen külön egy CustomXmlPart objektumot, és adja át a(z) Add(part) számára.

Mi a csomag egyedi részek, és hogyan különböznek az egyedi XML részektől?

Document.PackageCustomParts (a CustomPartCollection of CustomPart objects) tetszőleges OOXML csomagrészeket tárol, amelyek nem egyedi XML — mindegyikhez tartozik egy ContentType, egy RelationshipType, és egy nyers Data. Document.CustomXmlParts kifejezetten az egyedi XML adat-szigetekhez készült.

Mi az a `SmartTag`?

SmartTag egy régi Word funkció, amely a okos-címke felismerő által felismert és becsomagolt szöveget jelöli. Ez egy dokumentumcsomópont (NodeType.SmartTag), amely Element és Uri a felismerőt azonosítja, és egy Properties gyűjtemény a CustomXmlProperty értékekből, amelyeket a felismerő csatolt.

Hogyan másolhatok egyedi XML adatot dokumentumok között?

Használja a CustomXmlPart.Clone() a forrás részen, majd adja hozzá a klónt a cél dokumentum Document.CustomXmlParts részéhez Add(part).

API Reference összefoglaló

Osztály/Módszer	Leírás
`CustomXmlPart`	Egyetlen egyéni XML adat-sziget, amely egy dokumentumhoz van csatolva
`Document.CustomXmlParts`	A `CustomXmlPartCollection` az összes egyéni XML részre egy dokumentumban
`CustomXmlPartCollection.Add(id, xml)` / `GetById(id)`	Adj hozzá vagy kérj le egy egyéni XML részt azonosító alapján
`CustomXmlSchemaCollection`	A `CustomXmlPart`hoz kapcsolódó séma URI-k
`CustomXmlProperty`	Egyetlen név/érték XML tulajdonság
`CustomXmlPropertyCollection`	A `CustomXmlProperty` értékek gyűjteménye, például a `SmartTag.Properties` esetén
`Document.PackageCustomParts`	Az `CustomPartCollection` tetszőleges nem-XML OOXML csomagrészek
`CustomPart`	Egy csomagszintű egyéni rész `Name`, `ContentType` és nyers `Data` elemmel
`SmartTag`	Örökölt csomóponttípus, amely szöveget csomagol, és amelyet egy okoscímke-felismerő ismer fel
`MarkupLevel`	Az enum leírja, hogy egy jelölőelem hol fordulhat elő a dokumentumfában

Lásd még:

Aspose.Words for .NET — Enterprise Documentation