Lucrul cu proprietățile documentului

Lucrul cu proprietățile documentului

Acest ghid arată cum să citiți și să gestionați metadatele unui document Word — proprietățile vizibile în panoul Info/Properties al Word, plus orice valori personalizate definite de aplicație. Document.BuiltInDocumentProperties și Document.CustomDocumentProperties expun aceste două categorii, ambele construite în final pe aceeași reprezentare DocumentProperty de bază.

Proprietăți încorporate ale documentului

Document.BuiltInDocumentProperties returnează o colecție BuiltInDocumentProperties care acoperă metadatele standard pe care Word le urmărește pentru fiecare document: câmpuri descriptive precum Title, Subject, Author, Manager, Company, Category, Keywords și Comments; marcaje de timp precum CreatedTime, LastSavedTime și LastPrinted, alături de LastSavedBy și RevisionNumber; și statistici precum Words, Characters, CharactersWithSpaces, Lines, Paragraphs și Pages. Security raportează starea de protecție a documentului ca o valoare DocumentSecurity, iar Template, NameOfApplication și TotalEditingTime descriu mediul de creare. Deoarece BuiltInDocumentProperties este un set fix, cunoscut de proprietăți, valorile individuale sunt citite și scrise ca proprietăți obișnuite (BuiltInDocumentProperties.Author = "...") în loc să fie căutate după nume.

Proprietăți personalizate ale documentului

Document.CustomDocumentProperties returnează o colecție CustomDocumentProperties pentru metadatele definite de aplicație care nu fac parte din setul încorporat al Word. Mai multe suprasarcini Add(name, value) creează o proprietate nouă dintr-un nume și o valoare tipizată (șir, număr, boolean sau dată, în funcție de suprasarcină), iar AddLinkToContent(name, linkSource) creează o proprietate a cărei valoare este legată de și urmărește un interval de conținut marcat în document, în loc să dețină o valoare statică. Indexarea după nume (de ex. properties[name]) și Contains(name) caută o proprietate, IndexOf(name) returnează poziția acesteia, iar Remove(name)/RemoveAt(index) șterg una.

Obiectul DocumentProperty și baza colecției partajate

Atât BuiltInDocumentProperties, cât și CustomDocumentProperties derivă din abstractul DocumentPropertyCollection, care definește un indexer prin nume, GetEnumerator(), Contains(name), IndexOf(name) și Count — astfel încât cele două colecții sunt inspectate în același mod, chiar dacă proprietățile încorporate sunt fixe și proprietățile personalizate sunt deschise. Individual, un DocumentProperty are un Name, un Value netipizat și un Type (o valoare enum PropertyType: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray sau Other). IsLinkToContent și LinkSource raportează dacă proprietatea este legată de conținutul documentului în loc să dețină o valoare statică (vezi AddLinkToContent mai sus). Deoarece Value este netipizat, DocumentProperty furnizează accesori tipizați — ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() și ToString() — pentru a-l citi ca un tip specific fără o conversie explicită.

Securitatea documentului

BuiltInDocumentProperties.Security raportează o valoare DocumentSecurity care descrie starea de protecție a documentului: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced sau ReadOnlyExceptAnnotations. Aceasta reflectă metadatele de protecție stocate ale documentului, așa cum sunt citite din proprietățile fișierului.

Sfaturi și cele mai bune practici

• Utilizați accesoriile tipizate (ToInt(), ToDouble(), ToDateTime(), ToBool()) pe DocumentProperty.Value în loc să convertiți direct valoarea netipizată object, deoarece tipul de stocare de bază poate varia în funcție de PropertyType.
• Verificați Contains(name) înainte de a indexa în oricare dintre colecțiile de proprietăți prin nume (de exemplu properties[name]) atunci când o proprietate poate să nu existe, pentru a evita tratarea unui caz de proprietate lipsă ca o cale de excepție.
• Utilizați CustomDocumentProperties.AddLinkToContent(name, linkSource) atunci când valoarea unei proprietăți personalizate ar trebui să reflecte întotdeauna o parte marcată a documentului, în loc să sincronizați manual o proprietate personalizată statică de fiecare dată când acel conținut se modifică.
• Tratați statisticile BuiltInDocumentProperties (Words, Characters, Pages și altele similare) ca pe valorile stocate în metadatele fișierului, în loc de a le considera numărări calculate în timp real — reîmprospătați-le explicit dacă documentul s-a modificat de la ultima scriere.
• Citește BuiltInDocumentProperties.Security pentru a verifica starea declarată de protecție a documentului înainte de a decide dacă este necesară o procesare suplimentară legată de protecție.

Probleme comune

FAQ

Cum pot citi sau seta autorul și titlul documentului?

Folosește Document.BuiltInDocumentProperties.Author și .Title direct — sunt proprietăți obișnuite de tip șir în colecția BuiltInDocumentProperties accesată din Document.BuiltInDocumentProperties.

Cum pot adăuga metadate specifice aplicației care nu sunt o proprietate standard Word?

Folosește Document.CustomDocumentProperties.Add(name, value) cu numele și valoarea proprietății; suprasarcina Add potrivită este selectată în funcție de tipul valorii.

Care este diferența dintre BuiltInDocumentProperties și CustomDocumentProperties?

BuiltInDocumentProperties este setul fix de câmpuri standard de metadate din Word (autor, titlu, statistici etc.), accesate ca proprietăți numite. CustomDocumentProperties este o colecție deschisă, numită, de valori DocumentProperty pentru metadate definite de aplicație, accesată prin nume prin indexator (de ex. properties[name]) și Contains.

Cum pot citi o proprietate personalizată fără să cunosc în prealabil tipul său exact stocat?

Recuperați DocumentProperty prin indexarea colecției (de ex. properties[name]), verificați Type al său (o valoare PropertyType), și utilizați accesoriul tipic corespunzător, cum ar fi ToInt(), ToDouble(), ToDateTime() sau ToBool() pe Value.

Cum pot face ca o proprietate personalizată să urmărească o parte din conținutul documentului?

Utilizați CustomDocumentProperties.AddLinkToContent(name, linkSource), trecând un nume de semn de carte ca linkSource; valoarea proprietății va reflecta apoi conținutul marcat respectiv, în loc de o valoare statică.

API Reference Rezumat

Vezi și:

• Aspose.Words for .NET — Enterprise Documentation