Blocos de Construção

Este guia mostra como ler e modificar os blocos de construção de conteúdo reutilizáveis armazenados no documento de glossário de um documento com Aspose.Words FOSS para .NET. A biblioteca expõe entradas AutoText, capas, cabeçalhos, rodapés e conteúdo pré-definido semelhante através de Document.GlossaryDocument e do modelo de objeto BuildingBlock/BuildingBlockCollection.

O Documento de Glossário

Cada Document possui um GlossaryDocument — acessível via Document.GlossaryDocument — que por sua vez é uma subclasse DocumentBase que contém os blocos de construção. Sua propriedade BuildingBlocks devolve um BuildingBlockCollection, com FirstBuildingBlock/LastBuildingBlock proporcionando acesso rápido às extremidades da lista. Procure um bloco de construção específico com GetBuildingBlock(gallery, category, name), correspondendo ao seu BuildingBlockGallery, string de categoria e nome juntos.

Estrutura do Bloco de Construção

BuildingBlock é um CompositeNode, portanto mantém sua própria árvore de conteúdo — Sections (um SectionCollection), FirstSection e LastSection — da mesma forma que um Document contém seções. Suas propriedades de metadados identificam e classificam-no: Name, Guid, Description, Category, Gallery (um BuildingBlockGallery — AutoText, CoverPage, Headers, Footers, Tables, Watermarks e dezenas de outras galerias predefinidas), Type (um BuildingBlockType), e Behavior (um BuildingBlockBehavior de Content, Paragraph ou Page) que controlam como seu conteúdo é mesclado em um documento quando inserido.

Gerenciando a Coleção de Blocos de Construção

BuildingBlockCollection suporta edição completa de coleções: Add(node), Insert(index, node), Remove(node), RemoveAt(index), Clear(), Contains(node) e IndexOf(node), juntamente com ToArray() e GetEnumerator() para leitura. Como é um NodeCollection, blocos de construção podem ser criados, clonados e movidos usando as mesmas APIs de nó que qualquer outra parte da árvore do documento.

Blocos de Construção de Texto de Espaço Reservado

Tags de documento estruturado podem referenciar um bloco de construção como seu conteúdo de espaço reservado: StructuredDocumentTag.Placeholder e StructuredDocumentTagRangeStart.Placeholder retornam ambos o BuildingBlock exibido quando a tag está vazia, via a propriedade compartilhada IStructuredDocumentTag.Placeholder.

Dicas e Melhores Práticas

Combine os três argumentos de GetBuildingBlock(gallery, category, name) com cuidado — o mesmo nome pode existir em diferentes galerias ou categorias.
Use BuildingBlockGallery para filtrar que tipo de conteúdo reutilizável você está procurando (AutoText, CoverPage, Tables, Watermarks, etc.) em vez de examinar cada bloco de construção apenas pelo nome.
BuildingBlockBehavior determina como o conteúdo inserido se funde com o documento circundante (Content, Paragraph ou Page) — verifique isso antes de assumir que um bloco de construção será inserido da maneira que você espera.
Como BuildingBlock é um CompositeNode, trate-o como qualquer outra subárvore de nó ao construir ou editar seu conteúdo — AppendChild, InsertAfter e métodos de nó semelhantes se aplicam.

Problemas Comuns

Problema	Causa	Correção
`GetBuildingBlock()` não retorna nada	Galeria, categoria ou nome não correspondem exatamente a um bloco de construção existente	Enumere `GlossaryDocument.BuildingBlocks` para encontrar a combinação exata de `Gallery`/`Category`/`Name`
O conteúdo do bloco de construção inserido mescla inesperadamente	`Behavior` (`Content`/`Paragraph`/`Page`) não está contabilizado	Verifique `BuildingBlock.Behavior` antes de inserir para entender como ele será mesclado
O placeholder da tag de documento estruturado não exibe o conteúdo esperado	`Placeholder` aponta para um `BuildingBlock` diferente do assumido	Leia `StructuredDocumentTag.Placeholder` para confirmar qual bloco de construção está realmente referenciado

FAQ

Onde os blocos de construção são armazenados em um documento?

No GlossaryDocument do documento, acessível via Document.GlossaryDocument, cuja propriedade BuildingBlocks é um BuildingBlockCollection.

Como encontro um bloco de construção específico, como uma entrada AutoText?

Chame GlossaryDocument.GetBuildingBlock(gallery, category, name) com o BuildingBlockGallery correspondente, categoria e nome.

Posso adicionar novos blocos de construção programaticamente?

Sim — BuildingBlockCollection suporta Add(node) e Insert(index, node) já que é um NodeCollection.

O que BuildingBlockBehavior controla?

Como o conteúdo do bloco de construção é mesclado ao documento quando inserido — como Content, um Paragraph inteiro ou um Page inteiro.

Como um bloco de construção está relacionado ao texto de espaço reservado de uma tag de documento estruturado?

StructuredDocumentTag.Placeholder (e StructuredDocumentTagRangeStart.Placeholder) retornam o BuildingBlock que fornece o conteúdo de espaço reservado de um SDT quando está vazio.

API Reference Resumo

Classe / Método	Descrição
`Document.GlossaryDocument`	O `GlossaryDocument` do documento, contendo todos os blocos de construção
`GlossaryDocument.BuildingBlocks`	`BuildingBlockCollection` de cada bloco de construção
`GlossaryDocument.GetBuildingBlock()`	Localiza um bloco de construção por galeria, categoria e nome
`BuildingBlock`	Um `CompositeNode` com `Name`, `Gallery`, `Category`, `Behavior`, `Type`, `Sections`
`BuildingBlockCollection`	`Add()`, `Insert()`, `Remove()`, `Clear()`, `Contains()`, `IndexOf()`
`BuildingBlockGallery` / `BuildingBlockType` / `BuildingBlockBehavior`	Enums que classificam um bloco de construção
`StructuredDocumentTag.Placeholder`	O `BuildingBlock` usado como conteúdo de placeholder de um SDT

Ver também

Aspose.Words for .NET — Enterprise Documentation