Trabalhando com Propriedades de Documento

Trabalhando com Propriedades de Documento

Este guia mostra como ler e gerenciar os metadados de um documento Word — as propriedades visíveis no painel de Informações/Propriedades do Word, além de quaisquer valores personalizados definidos pela aplicação. Document.BuiltInDocumentProperties e Document.CustomDocumentProperties expõem essas duas categorias, ambas construídas, em última análise, sobre a mesma representação subjacente DocumentProperty.

Propriedades de Documento Integradas

Document.BuiltInDocumentProperties devolve uma coleção BuiltInDocumentProperties que cobre os metadados padrão que o Word registra para cada documento: campos descritivos como Title, Subject, Author, Manager, Company, Category, Keywords e Comments; carimbos de data/hora como CreatedTime, LastSavedTime e LastPrinted, juntamente com LastSavedBy e RevisionNumber; e estatísticas como Words, Characters, CharactersWithSpaces, Lines, Paragraphs e Pages. Security informa o estado de proteção do documento como um valor DocumentSecurity, e Template, NameOfApplication e TotalEditingTime descrevem o ambiente de autoria. Como BuiltInDocumentProperties é um conjunto fixo e conhecido de propriedades, os valores individuais são lidos e gravados como propriedades ordinárias (BuiltInDocumentProperties.Author = "...") em vez de serem localizados pelo nome.

Propriedades Personalizadas de Documento

Document.CustomDocumentProperties devolve uma coleção CustomDocumentProperties para metadados definidos pela aplicação que não fazem parte do conjunto nativo do Word. Várias sobrecargas de Add(name, value) criam um novo campo a partir de um nome e de um valor tipado (texto, número, booleano ou data, conforme a sobrecarga), e AddLinkToContent(name, linkSource) cria um campo cujo valor está vinculado a e acompanha um intervalo marcado por marcador no documento, em vez de armazenar um valor estático. A indexação por nome (por exemplo, properties[name]) e Contains(name) localizam um campo, IndexOf(name) devolve sua posição, e Remove(name)/RemoveAt(index) removem-no.

O Objeto DocumentProperty e a Base de Coleção Compartilhada

Ambos BuiltInDocumentProperties e CustomDocumentProperties derivam do DocumentPropertyCollection abstrato, que define um indexador por nome, GetEnumerator(), Contains(name), IndexOf(name) e Count — de modo que as duas coleções são inspecionadas da mesma forma, mesmo que as propriedades internas sejam fixas e as propriedades personalizadas sejam de formato aberto. Individualmente, um DocumentProperty possui um Name, um Value sem tipo definido e um Type (um valor enum PropertyType: Boolean, DateTime, Double, Number, String, StringArray, ObjectArray, ByteArray ou Other). IsLinkToContent e LinkSource indicam se a propriedade está vinculada ao conteúdo do documento em vez de conter um valor estático (veja AddLinkToContent acima). Como Value não tem tipo, DocumentProperty oferece acessores tipados — ToInt(), ToDouble(), ToDateTime(), ToBool(), ToByteArray() e ToString() — para lê-lo como um tipo específico sem necessidade de cast explícito.

Segurança do Documento

BuiltInDocumentProperties.Security relata um valor DocumentSecurity que descreve o estado de proteção do documento: None, PasswordProtected, ReadOnlyRecommended, ReadOnlyEnforced ou ReadOnlyExceptAnnotations. Isso reflete os metadados de proteção armazenados no documento, lidos das propriedades do arquivo.

Dicas e Melhores Práticas

• Use os acessores tipados (ToInt(), ToDouble(), ToDateTime(), ToBool()) em DocumentProperty.Value em vez de converter diretamente o valor object sem tipo, pois o tipo de armazenamento subjacente pode variar conforme PropertyType.
• Verifique Contains(name) antes de indexar em qualquer coleção de propriedades por nome (por exemplo, properties[name]) quando uma propriedade pode não existir, a fim de evitar tratar a ausência da propriedade como um caminho de exceção.
• Use CustomDocumentProperties.AddLinkToContent(name, linkSource) quando o valor de um campo personalizado deve refletir sempre uma parte marcada do documento, em vez de sincronizar manualmente um campo estático sempre que esse conteúdo mudar.
• Considere as estatísticas de BuiltInDocumentProperties (Words, Characters, Pages e semelhantes) como os valores armazenados nos metadados do arquivo, em vez de contagens sempre calculadas em tempo real — atualize-as explicitamente se o documento tiver sido alterado desde a última gravação.
• Leia BuiltInDocumentProperties.Security para verificar o estado de proteção declarado de um documento antes de decidir se é necessário um processamento adicional relacionado à proteção.

Problemas comuns

FAQ

Como leio ou defino o autor e o título do documento?

Use Document.BuiltInDocumentProperties.Author e .Title diretamente — são propriedades de string ordinárias na coleção BuiltInDocumentProperties alcançada a partir de Document.BuiltInDocumentProperties.

Como adiciono metadados específicos de aplicativo que não são uma propriedade padrão do Word?

Use Document.CustomDocumentProperties.Add(name, value) com o nome e o valor da propriedade; a sobrecarga apropriada de Add é selecionada com base no tipo do valor.

Qual é a diferença entre BuiltInDocumentProperties e CustomDocumentProperties?

BuiltInDocumentProperties é o conjunto fixo de campos de metadados padrão do Word (autor, título, estatísticas etc.), acessado como propriedades nomeadas. CustomDocumentProperties é uma coleção nomeada e aberta de valores DocumentProperty para metadados definidos pela aplicação, acessada por nome via o indexador (por exemplo, properties[name]) e Contains.

Como leio uma propriedade personalizada sem conhecer previamente o tipo exato armazenado?

Recupere o DocumentProperty indexando a coleção (por exemplo, properties[name]), verifique seu Type (um valor PropertyType) e use o acessador tipado correspondente, como ToInt(), ToDouble(), ToDateTime() ou ToBool(), em seu Value.

Como faço para que uma propriedade personalizada acompanhe um trecho do conteúdo do documento?

Utilize CustomDocumentProperties.AddLinkToContent(name, linkSource), passando o nome de um marcador como linkSource; o valor da propriedade passa a refletir esse conteúdo marcado em vez de um valor estático.

Resumo de API Reference

Ver também

• Aspose.Words for .NET — Enterprise Documentation