Informations sur le document

Informations du document

Ce guide montre comment lire et écrire les métadonnées d’un document avec Aspose.Words FOSS pour .NET. Chaque Document chargé ou nouvellement créé comporte deux types de métadonnées en plus de son contenu : un ensemble fixe de propriétés intégrées (auteur, titre, nombre de mots, etc.) et un ensemble ouvert de propriétés personnalisées que vous définissez vous-même. Aspose.Words FOSS pour .NET implémente également les champs Word qui exposent ces métadonnées dans le corps du document — AUTHOR, COMMENTS et DOCPROPERTY — de sorte que les valeurs des propriétés puissent apparaître comme du texte dynamique et mise à jour.

Propriétés de document intégrées

Document.BuiltInDocumentProperties renvoie une collection BuiltInDocumentProperties contenant une propriété pour chaque champ de métadonnées Word standard : Author, Title, Subject, Comments, Category, Company, Manager, Keywords, CreatedTime, LastSavedTime, LastSavedBy, LastPrinted, RevisionNumber, TotalEditingTime, et des statistiques telles que Pages, Words, Characters, CharactersWithSpaces, Paragraphs et Lines. Étant donné que BuiltInDocumentProperties dérive de DocumentPropertyCollection, il prend également en charge la recherche par nom via son indexeur, Contains(), IndexOf(), et l’énumération via GetEnumerator(). La même collection est exposée sur PlainTextDocument.BuiltInDocumentProperties lors du traitement d’une entrée en texte brut.

Propriétés de document personnalisées

Document.CustomDocumentProperties renvoie une collection CustomDocumentProperties pour les propriétés qu’une application définit elle-même — des paires nom/valeur arbitraires que Word stocke à côté de l’ensemble intégré. Ajoutez une propriété avec Add(name, value), qui est surchargé à travers CustomDocumentProperties pour les types de valeurs qu’une propriété peut contenir ; récupérez-en une par son nom avec l’indexeur, par ex. properties[name] ; et supprimez des entrées avec Remove(name), RemoveAt(index) ou Clear(). AddLinkToContent(name, linkSource) crée une propriété dont la valeur est liée à un signet ou à une plage dans le document plutôt qu’à une valeur fixe.

Chaque entrée dans l’une ou l’autre collection — intégrée ou personnalisée — est un DocumentProperty, qui expose Name, Value et Type (une valeur PropertyType : String, Number, Double, Boolean, DateTime, StringArray, ObjectArray, ByteArray ou Other), ainsi que IsLinkToContent et LinkSource pour les propriétés liées. DocumentProperty fournit des assistants de conversion tels que ToString(), ToInt(), ToDouble(), ToDateTime(), ToBool() et ToByteArray() pour récupérer la valeur sous-jacente dans le type .NET souhaité.

Champs d’information du document

Trois sous-classes Field exposent les métadonnées du document sous forme de champs à l’intérieur même du corps du document : FieldAuthor (le champ AUTHOR, avec une propriété AuthorName), FieldComments (le champ COMMENTS, avec une propriété Text), et FieldDocProperty (le champ DOCPROPERTY, qui lit une propriété de document nommée — intégrée ou personnalisée — dans le document). Comme tout Field, ces trois partagent le cycle de vie de base Field : GetFieldCode() pour lire le code du champ sous-jacent, Result / DisplayResult pour lire la dernière valeur calculée, Update() pour recalculer la valeur, Unlink() pour remplacer le champ par son résultat statique, et Remove() pour le supprimer. Insérez un champ d’information de document avec DocumentBuilder.InsertField(fieldCode) — par exemple un code de champ AUTHOR ou DOCPROPERTY "Company" — ou avec la surcharge InsertField(fieldType, updateField) en utilisant une valeur FieldType telle que FieldType.FieldAuthor, FieldType.FieldComments ou FieldType.FieldDocProperty.

Parce que FieldDocProperty lit n’importe quelle propriété du document à laquelle il est lié, modifier la valeur sous-jacente de BuiltInDocumentProperties ou CustomDocumentProperties puis appeler Update() — ou Document.UpdateFields() pour actualiser tous les champs du document en une fois — propagera la nouvelle valeur dans le résultat affiché du champ.

Conseils et meilleures pratiques

• Définissez les propriétés intégrées telles que Title, Author et Subject avant d’enregistrer — Word et les autres consommateurs lisent celles-ci à partir de BuiltInDocumentProperties pour les listes de documents et l’indexation de recherche.
• Utilisez DocumentProperty.Type pour vérifier le PropertyType d’une propriété avant d’appeler un assistant de conversion spécifique (ToInt(), ToDateTime(), etc.) afin d’éviter une incompatibilité de conversion sur une propriété que vous n’avez pas créée vous-même.
• AddLinkToContent() maintient une propriété personnalisée synchronisée avec le contenu du document (comme une plage marquée) au lieu d’une valeur fixe — utilisez-le lorsque la propriété doit toujours refléter ce qui se trouve actuellement dans le document.
• Appelez Document.UpdateFields() après avoir modifié les propriétés du document afin que les champs FieldDocProperty, FieldAuthor ou FieldComments déjà présents dans le corps du document récupèrent les nouvelles valeurs.
• BuiltInDocumentProperties et CustomDocumentProperties sont tous deux disponibles sur PlainTextDocument ainsi que sur Document, de sorte que les métadonnées circulent même lorsque le contenu chargé est du texte brut.

Problèmes courants

FAQ

Quelle est la différence entre les propriétés de document intégrées et personnalisées?

Les propriétés intégrées (Document.BuiltInDocumentProperties) sont un ensemble fixe défini par le format OOXML — Author, Title, Pages, et similaires. Les propriétés personnalisées (Document.CustomDocumentProperties) sont un ensemble ouvert, défini par l’application, de paires nom/valeur ajoutées avec Add().

Comment faire en sorte qu’une propriété personnalisée suive le contenu du document plutôt qu’une valeur fixe?

Utilisez CustomDocumentProperties.AddLinkToContent(name, linkSource), qui lie la valeur de la propriété à un signet ou à une plage dans le document plutôt que de stocker une valeur statique.

La mise à jour d’une propriété de document met-elle automatiquement à jour les champs qui l’affichent?

Non — appelez Update() sur le champ spécifique ou Document.UpdateFields() pour recomputer chaque champ du document, y compris les instances FieldDocProperty, FieldAuthor et FieldComments.

Puis-je lire les propriétés du document à partir d’un document texte brut?

Oui. PlainTextDocument expose les mêmes propriétés BuiltInDocumentProperties et CustomDocumentProperties que Document.

API Reference Résumé

Voir aussi

• Aspose.Words for .NET — Enterprise Documentation