Travailler avec les propriétés du document

Ce guide montre comment lire et gérer les métadonnées d’un document Word — les propriétés visibles dans le panneau Informations/Propriétés de Word, ainsi que toutes les valeurs personnalisées définies par l’application. Document.BuiltInDocumentProperties et Document.CustomDocumentProperties exposent ces deux catégories, toutes deux finalement construites sur la même représentation DocumentProperty sous-jacente.

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

Document.BuiltInDocumentProperties renvoie une collection BuiltInDocumentProperties couvrant les métadonnées standard que Word suit pour chaque document : champs descriptifs tels que Title, Subject, Author, Manager, Company, Category, Keywords et Comments ; horodatages tels que CreatedTime, LastSavedTime et LastPrinted, ainsi que LastSavedBy et RevisionNumber ; et statistiques telles que Words, Characters, CharactersWithSpaces, Lines, Paragraphs et Pages. Security indique l’état de protection du document sous forme de valeur DocumentSecurity, et Template, NameOfApplication et TotalEditingTime décrivent l’environnement d’édition. Parce que BuiltInDocumentProperties constitue un ensemble fixe et connu de propriétés, les valeurs individuelles sont lues et écrites comme des propriétés ordinaires (BuiltInDocumentProperties.Author = "...") plutôt que recherchées par nom.

Propriétés de document personnalisées

Document.CustomDocumentProperties renvoie une collection CustomDocumentProperties pour les métadonnées définies par l’application qui ne font pas partie de l’ensemble intégré de Word. Plusieurs surcharges Add(name, value) créent une nouvelle propriété à partir d’un nom et d’une valeur typée (chaîne, nombre, booléen ou date, selon la surcharge), et AddLinkToContent(name, linkSource) crée une propriété dont la valeur est liée à et suit une plage de contenu marquée dans le document plutôt que de contenir une valeur statique. L’indexation par nom (par ex. properties[name]) et Contains(name) recherchent une propriété, IndexOf(name) renvoie sa position, et Remove(name)/RemoveAt(index) en suppriment une.

L’objet DocumentProperty et la base de collection partagée

À la fois BuiltInDocumentProperties et CustomDocumentProperties dérivent de lDocumentPropertyCollection abstrait, qui définit un indexeur par nom, GetEnumerator(), Contains(name), IndexOf(name) et Count — de sorte que les deux collections sont inspectées de la même manière même si les propriétés intégrées sont fixes et les propriétés personnalisées sont ouvertes. Individuellement, un DocumentProperty possède un Name, un Value non typé, et un Type (une valeur d’énumération PropertyType: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray ou Other). IsLinkToContent et LinkSource indiquent si la propriété est liée au contenu du document plutôt que de contenir une valeur statique (voir AddLinkToContent ci-dessus). Comme Value n’est pas typé, DocumentProperty fournit des accesseurs typés — ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() et ToString() — pour le lire comme un type spécifique sans un cast explicite.

Sécurité du document

BuiltInDocumentProperties.Security rapporte une valeur DocumentSecurity décrivant l’état de protection du document: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced ou ReadOnlyExceptAnnotations. Cela reflète les métadonnées de protection stockées du document telles que lues depuis les propriétés du fichier.

Conseils et meilleures pratiques

Utilisez les accesseurs typés (ToInt(), ToDouble(), ToDateTime(), ToBool()) sur DocumentProperty.Value plutôt que de convertir directement la valeur object non typée, car le type de stockage sous-jacent peut varier selon PropertyType.
Vérifiez Contains(name) avant d’indexer l’une ou l’autre des collections de propriétés par nom (par ex. properties[name]) lorsqu’une propriété peut ne pas exister, afin d’éviter de gérer un cas de propriété manquante comme un chemin d’exception.
Utilisez CustomDocumentProperties.AddLinkToContent(name, linkSource) lorsqu’une valeur de propriété personnalisée doit toujours refléter une partie marquée du document, plutôt que de resynchroniser manuellement une propriété personnalisée statique chaque fois que ce contenu change.
Considérez les statistiques BuiltInDocumentProperties (Words, Characters, Pages et similaires) comme les valeurs stockées dans les métadonnées du fichier plutôt que comme des comptes toujours calculés en temps réel — rafraîchissez-les explicitement si le document a changé depuis leur dernière écriture.
Lisez BuiltInDocumentProperties.Security pour vérifier l’état de protection déclaré d’un document avant de décider si un traitement supplémentaire lié à la protection est nécessaire.

Problèmes courants

Problème	Cause	Correction
L’indexation d’une collection `CustomDocumentProperties` par nom ne renvoie rien d’utile	La propriété n’existe pas dans ce document	Appelez `Contains(name)` d’abord, ou ajoutez la propriété avec la surcharge `Add(name, value)` appropriée
Lire la valeur d’une propriété personnalisée renvoie le mauvais type	`DocumentProperty.Value` est untyped `object` ; l’appelant a supposé un type qui ne correspond pas à `Type`	Utilisez l’accesseur typé correspondant (`ToInt()`, `ToDouble()`, `ToDateTime()`, `ToBool()`, `ToByteArray()`) en fonction de `DocumentProperty.Type`
La valeur d’une propriété personnalisée liée semble obsolète	La propriété est liée via `AddLinkToContent`, et le contenu lié a changé sans que le document ne soit mis à jour correctement	Vérifiez que la plage `linkSource` marquée reflète toujours le contenu prévu
Les statistiques de mots (`Words`, `Pages`, etc.) ne correspondent pas au contenu réel actuel du document	Les statistiques intégrées reflètent les métadonnées stockées, pas un recomptage en temps réel	Recalculez et mettez à jour les valeurs `BuiltInDocumentProperties` pertinentes si un décompte à jour est requis

FAQ

Comment lire ou définir l’auteur et le titre du document?

Utilisez directement Document.BuiltInDocumentProperties.Author et .Title — ce sont des propriétés de chaîne ordinaires de la collection BuiltInDocumentProperties accessible depuis Document.BuiltInDocumentProperties.

Comment ajouter des métadonnées spécifiques à l’application qui ne sont pas une propriété Word standard?

Utilisez Document.CustomDocumentProperties.Add(name, value) avec le nom et la valeur de la propriété; la surcharge appropriée de Add est sélectionnée en fonction du type de la valeur.

Quelle est la différence entre `BuiltInDocumentProperties` et `CustomDocumentProperties`?

BuiltInDocumentProperties est l’ensemble fixe de champs de métadonnées standard de Word (auteur, titre, statistiques, etc.), accessibles en tant que propriétés nommées. CustomDocumentProperties est une collection nommée ouverte de valeurs DocumentProperty pour des métadonnées définies par l’application, accessibles par nom via l’indexeur (par ex. properties[name]) et Contains.

Comment lire une propriété personnalisée sans connaître à l’avance son type stocké exact?

Récupérez le DocumentProperty en indexant la collection (par ex. properties[name]), vérifiez son Type (une valeur PropertyType), et utilisez l’accesseur typé correspondant tel que ToInt(), ToDouble(), ToDateTime() ou ToBool() sur son Value.

Comment faire en sorte qu’une propriété personnalisée suive une partie du contenu du document?

Utilisez CustomDocumentProperties.AddLinkToContent(name, linkSource), en passant un nom de signet comme linkSource; la valeur de la propriété reflète alors ce contenu marqué plutôt qu’une valeur statique.

API Reference Résumé

Classe/Méthode	Description
`Document.BuiltInDocumentProperties`	Champs de métadonnées standard de Word (auteur, titre, statistiques, sécurité, etc.)
`Document.CustomDocumentProperties`	Propriétés de métadonnées nommées définies par l’application
`CustomDocumentProperties.Add(name, value)`	Ajouter une propriété personnalisée à partir d’un nom et d’une valeur typée
`CustomDocumentProperties.AddLinkToContent(name, linkSource)`	Ajouter une propriété personnalisée liée au contenu du document mis en signet
`DocumentPropertyCollection`	Base abstraite partagée pour les deux collections de propriétés
`DocumentProperty`	Le nom d’une propriété, sa valeur non typée et `PropertyType`
`DocumentProperty.ToInt()` / `ToDouble()` / `ToDateTime()` / `ToBool()`	Accesseurs typés pour la valeur d’une propriété
`PropertyType`	Enum décrivant le type de valeur d’un `DocumentProperty`
`DocumentSecurity`	Enum décrivant l’état de protection d’un document, via `BuiltInDocumentProperties.Security`

Voir aussi

Aspose.Words for .NET — Enterprise Documentation

Travailler avec les propriétés du document