Informazioni sul documento

Informazioni sul documento

Questa guida mostra come leggere e scrivere i metadati del documento con Aspose.Words FOSS per .NET. Ogni Document caricato o appena creato contiene due tipi di metadati accanto al suo contenuto: un set fisso di proprietà incorporate (autore, titolo, conteggio parole e simili) e un insieme aperto di proprietà personalizzate che definisci tu stesso. Aspose.Words FOSS per .NET implementa anche i campi Word che espongono questi metadati all’interno del corpo del documento — AUTHOR, COMMENTS e DOCPROPERTY — in modo che i valori delle proprietà possano apparire come testo live e aggiornabile.

Proprietà incorporate del documento

Document.BuiltInDocumentProperties restituisce una collezione BuiltInDocumentProperties con una proprietà per ciascun campo standard dei metadati di Word: Author, Title, Subject, Comments, Category, Company, Manager, Keywords, CreatedTime, LastSavedTime, LastSavedBy, LastPrinted, RevisionNumber, TotalEditingTime e statistiche come Pages, Words, Characters, CharactersWithSpaces, Paragraphs e Lines. Poiché BuiltInDocumentProperties deriva da DocumentPropertyCollection, supporta anche la ricerca per nome tramite il suo indicizzatore, Contains(), IndexOf(), e l’enumerazione tramite GetEnumerator(). La stessa collezione è esposta su PlainTextDocument.BuiltInDocumentProperties quando si lavora con input di testo semplice.

Proprietà personalizzate del documento

Document.CustomDocumentProperties restituisce una collezione CustomDocumentProperties per le proprietà che un’applicazione definisce autonomamente — coppie nome/valore arbitrarie che Word memorizza accanto al set incorporato. Aggiungi una proprietà con Add(name, value), che è sovraccaricato su CustomDocumentProperties per i tipi di valore che una proprietà può contenere; recuperane una per nome con l’indicizzatore, ad es. properties[name]; e rimuovi le voci con Remove(name), RemoveAt(index) o Clear(). AddLinkToContent(name, linkSource) crea una proprietà il cui valore è collegato a un segnalibro o a un intervallo all’interno del documento piuttosto che memorizzato come valore fisso.

Ogni voce in entrambe le collezioni — incorporate o personalizzate — è un DocumentProperty, che espone Name, Value e Type (un valore PropertyType: String, Number, Double, Boolean, DateTime, StringArray, ObjectArray, ByteArray o Other), più IsLinkToContent e LinkSource per le proprietà collegate. DocumentProperty fornisce helper di conversione come ToString(), ToInt(), ToDouble(), ToDateTime(), ToBool() e ToByteArray() per recuperare il valore sottostante nel tipo .NET desiderato.

Campi di Informazione del Documento

Tre sottoclassi Field espongono i metadati del documento come campi all’interno del corpo del documento stesso: FieldAuthor (il campo AUTHOR, con una proprietà AuthorName), FieldComments (il campo COMMENTS, con una proprietà Text), e FieldDocProperty (il campo DOCPROPERTY, che legge una proprietà del documento denominata — integrata o personalizzata — nel documento). Come ogni Field, questi tre condividono il ciclo di vita di base Field: GetFieldCode() per leggere il codice del campo sottostante, Result / DisplayResult per leggere l’ultimo valore calcolato, Update() per ricalcolare il valore, Unlink() per sostituire il campo con il suo risultato statico, e Remove() per eliminarlo. Inserisci un campo di informazioni sul documento con DocumentBuilder.InsertField(fieldCode) — ad esempio un codice campo di AUTHOR o DOCPROPERTY "Company" — o con il sovraccarico InsertField(fieldType, updateField) usando un valore FieldType come FieldType.FieldAuthor, FieldType.FieldComments, o FieldType.FieldDocProperty.

Poiché FieldDocProperty legge qualsiasi proprietà del documento a cui è associato, modificare il valore sottostante di BuiltInDocumentProperties o CustomDocumentProperties e poi chiamare Update() — o Document.UpdateFields() per aggiornare tutti i campi nel documento contemporaneamente — propaga il nuovo valore nel risultato visualizzato del campo.

Suggerimenti e Buone Pratiche

• Imposta le proprietà integrate come Title, Author e Subject prima di salvare — Word e altri consumatori le leggono da BuiltInDocumentProperties per gli elenchi dei documenti e l’indicizzazione della ricerca.
• Usa DocumentProperty.Type per verificare il PropertyType di una proprietà prima di chiamare un helper di conversione specifico (ToInt(), ToDateTime(), ecc.) per evitare una discrepanza di conversione su una proprietà che non hai creato tu.
• AddLinkToContent() mantiene una proprietà personalizzata sincronizzata con il contenuto del documento (come un intervallo contrassegnato) invece di un valore fisso — usala quando la proprietà dovrebbe sempre riflettere ciò che è attualmente nel documento.
• Chiama Document.UpdateFields() dopo aver modificato le proprietà del documento affinché eventuali campi FieldDocProperty, FieldAuthor o FieldComments già presenti nel corpo del documento acquisiscano i nuovi valori.
• BuiltInDocumentProperties e CustomDocumentProperties sono entrambi disponibili su PlainTextDocument così come su Document, quindi i metadati vengono trasferiti anche quando il contenuto caricato è testo semplice.

Problemi comuni

FAQ

Qual è la differenza tra le proprietà di documento integrate e quelle personalizzate?

Le proprietà integrate (Document.BuiltInDocumentProperties) sono un insieme fisso definito dal formato OOXML — Author, Title, Pages e simili. Le proprietà personalizzate (Document.CustomDocumentProperties) sono un insieme aperto, definito dall’applicazione, di coppie nome/valore aggiunte con Add().

Come faccio a far sì che una proprietà personalizzata tracci il contenuto del documento anziché un valore fisso?

Usa CustomDocumentProperties.AddLinkToContent(name, linkSource), che collega il valore della proprietà a un segnalibro o a un intervallo nel documento anziché memorizzare un valore statico.

L’aggiornamento di una proprietà del documento aggiorna automaticamente i campi che la visualizzano?

No — chiama Update() sul campo specifico o Document.UpdateFields() per ricalcolare ogni campo nel documento, inclusi FieldDocProperty, FieldAuthor e FieldComments istanze.

Posso leggere le proprietà del documento da un documento di testo semplice?

Sì. PlainTextDocument espone le stesse proprietà BuiltInDocumentProperties e CustomDocumentProperties di Document.

API Reference Riepilogo

Vedi anche

• Aspose.Words for .NET — Enterprise Documentation