Informações do Documento

Informações do Documento

Este guia mostra como ler e escrever metadados de documento com Aspose.Words FOSS para .NET. Cada Document carregado ou recém-criado contém dois tipos de metadados ao lado de seu conteúdo: um conjunto fixo de propriedades internas (autor, título, contagem de palavras e similares) e um conjunto aberto de propriedades personalizadas que você define. Aspose.Words FOSS para .NET também implementa os campos do Word que expõem esses metadados dentro do corpo do documento — AUTHOR, COMMENTS e DOCPROPERTY — de modo que os valores das propriedades podem aparecer como texto ao vivo, atualizável.

Propriedades de Documento Internas

Document.BuiltInDocumentProperties devolve uma coleção BuiltInDocumentProperties com uma propriedade para cada campo padrão de metadados do Word: Author, Title, Subject, Comments, Category, Company, Manager, Keywords, CreatedTime, LastSavedTime, LastSavedBy, LastPrinted, RevisionNumber, TotalEditingTime e estatísticas como Pages, Words, Characters, CharactersWithSpaces, Paragraphs e Lines. Como BuiltInDocumentProperties deriva de DocumentPropertyCollection, ele também oferece pesquisa por nome através de seu indexador, Contains(), IndexOf(), e enumeração por GetEnumerator(). A mesma coleção é exposta em PlainTextDocument.BuiltInDocumentProperties ao trabalhar com entrada de texto simples.

Propriedades de Documento Personalizadas

Document.CustomDocumentProperties devolve uma coleção CustomDocumentProperties para propriedades que uma aplicação define — pares arbitrários nome/valor que o Word armazena ao lado do conjunto interno. Adicione uma propriedade com Add(name, value), que está sobrecarregado em CustomDocumentProperties para os tipos de valor que uma propriedade pode conter; recupere uma por nome com o indexador, por exemplo properties[name]; e remova entradas com Remove(name), RemoveAt(index) ou Clear(). AddLinkToContent(name, linkSource) cria uma propriedade cujo valor está vinculado a um marcador ou intervalo dentro do documento, em vez de ser armazenado como um valor fixo.

Cada entrada em qualquer das coleções — interna ou personalizada — é um DocumentProperty, que expõe Name, Value e Type (um valor PropertyType: String, Number, Double, Boolean, DateTime, StringArray, ObjectArray, ByteArray ou Other), além de IsLinkToContent e LinkSource para propriedades vinculadas. DocumentProperty fornece auxiliares de conversão como ToString(), ToInt(), ToDouble(), ToDateTime(), ToBool() e ToByteArray() para obter o valor subjacente no tipo .NET desejado.

Campos de Informação de Documento

Três subclasses de Field expõem metadados do documento como campos dentro do próprio corpo do documento: FieldAuthor (o campo AUTHOR, com uma propriedade AuthorName), FieldComments (o campo COMMENTS, com uma propriedade Text), e FieldDocProperty (o campo DOCPROPERTY, que lê uma propriedade de documento nomeada — incorporada ou personalizada — no documento). Como todo Field, esses três compartilham o ciclo de vida base de Field: GetFieldCode() para ler o código do campo subjacente, Result / DisplayResult para ler o último valor calculado, Update() para recalcular o valor, Unlink() para substituir o campo pelo seu resultado estático, e Remove() para excluí-lo. Insira um campo de informação de documento com DocumentBuilder.InsertField(fieldCode) — por exemplo, um código de campo AUTHOR ou DOCPROPERTY "Company" — ou com a sobrecarga InsertField(fieldType, updateField) usando um valor FieldType como FieldType.FieldAuthor, FieldType.FieldComments ou FieldType.FieldDocProperty.

Como FieldDocProperty lê qualquer propriedade do documento à qual está vinculada, alterar o valor subjacente de BuiltInDocumentProperties ou CustomDocumentProperties e então chamar Update() — ou Document.UpdateFields() para atualizar todos os campos no documento de uma vez — propaga o novo valor para o resultado exibido do campo.

Dicas e Melhores Práticas

• Defina propriedades internas como Title, Author e Subject antes de salvar — Word e outros consumidores leem essas propriedades de BuiltInDocumentProperties para listagens de documentos e indexação de busca.
• Use DocumentProperty.Type para verificar o PropertyType de uma propriedade antes de chamar um ajudante de conversão específico (ToInt(), ToDateTime(), etc.) para evitar incompatibilidade de conversão em uma propriedade que você não criou.
• AddLinkToContent() mantém uma propriedade personalizada sincronizada com o conteúdo do documento (como um intervalo marcado) em vez de um valor fixo — use-o quando a propriedade deve refletir sempre o que está atualmente no documento.
• Chame Document.UpdateFields() após alterar as propriedades do documento para que quaisquer campos FieldDocProperty, FieldAuthor ou FieldComments já presentes no corpo do documento adotem os novos valores.
• BuiltInDocumentProperties e CustomDocumentProperties estão ambos disponíveis em PlainTextDocument assim como em Document, portanto os metadados são mantidos mesmo quando o conteúdo carregado é texto simples.

Problemas comuns

FAQ

Qual é a diferença entre propriedades de documento incorporadas e personalizadas?

Propriedades incorporadas (Document.BuiltInDocumentProperties) são um conjunto fixo definido pelo formato OOXML — Author, Title, Pages, e similares. Propriedades personalizadas (Document.CustomDocumentProperties) são um conjunto aberto, definido pela aplicação, de pares nome/valor adicionados com Add().

Como faço para que uma propriedade personalizada rastreie o conteúdo do documento em vez de um valor fixo?

Use CustomDocumentProperties.AddLinkToContent(name, linkSource), que vincula o valor da propriedade a um marcador ou intervalo no documento em vez de armazenar um valor estático.

A atualização de uma propriedade de documento atualiza automaticamente os campos que a exibem?

Não — chame Update() no campo específico ou Document.UpdateFields() para recalcular todos os campos no documento, incluindo instâncias de FieldDocProperty, FieldAuthor e FieldComments.

Posso ler propriedades do documento a partir de um documento de texto simples?

Sim. PlainTextDocument expõe as mesmas propriedades BuiltInDocumentProperties e CustomDocumentProperties que Document.

API Reference Resumo

Ver também

• Aspose.Words for .NET — Enterprise Documentation