Bloques de Construcción
Bloques de construcción
Esta guía muestra cómo leer y modificar los bloques de contenido reutilizables almacenados en el documento de glosario de un documento con Aspose.Words FOSS para .NET. La biblioteca expone entradas AutoText, páginas de portada, encabezados, pies de página y contenido predefinido similar a través de Document.GlossaryDocument y el modelo de objetos BuildingBlock/BuildingBlockCollection.
El documento de glosario
Cada Document lleva un GlossaryDocument — accesible a través de Document.GlossaryDocument — que es a su vez una subclase DocumentBase que contiene los bloques de construcción. Su propiedad BuildingBlocks devuelve un BuildingBlockCollection, con FirstBuildingBlock/LastBuildingBlock proporcionando acceso rápido a los extremos de la lista. Busca un bloque de construcción específico con GetBuildingBlock(gallery, category, name), coincidiendo su BuildingBlockGallery, cadena de categoría y nombre juntos.
Estructura del bloque de construcción
BuildingBlock es un CompositeNode, por lo que contiene su propio árbol de contenido — Sections (un SectionCollection), FirstSection y LastSection — de la misma manera que un Document contiene secciones. Sus propiedades de metadatos lo identifican y clasifican: Name, Guid, Description, Category, Gallery (un BuildingBlockGallery — AutoText, CoverPage, Headers, Footers, Tables, Watermarks, y decenas de galerías predefinidas más), Type (un BuildingBlockType), y Behavior (un BuildingBlockBehavior de Content, Paragraph o Page) que controla cómo se fusionan sus contenidos en un documento cuando se inserta.
Gestión de la colección de bloques de construcción
BuildingBlockCollection admite la edición completa de colecciones: Add(node), Insert(index, node), Remove(node), RemoveAt(index), Clear(), Contains(node) y IndexOf(node), junto con ToArray() y GetEnumerator() para la lectura. Debido a que es un NodeCollection, los bloques de construcción pueden ser creados, clonados y movidos usando las mismas APIs de nodo que cualquier otra parte del árbol del documento.
Bloques de Construcción de Texto de Marcador
Las etiquetas de documento estructurado pueden referenciar un bloque de construcción como su contenido de marcador: StructuredDocumentTag.Placeholder y StructuredDocumentTagRangeStart.Placeholder devuelven ambos el BuildingBlock que se muestra cuando la etiqueta está vacía, a través de la propiedad compartida IStructuredDocumentTag.Placeholder.
Consejos y Mejores Prácticas
- Coincida los tres argumentos de
GetBuildingBlock(gallery, category, name)cuidadosamente — el mismo nombre puede existir en diferentes galerías o categorías. - Utilice
BuildingBlockGallerypara filtrar el tipo de contenido reutilizable que busca (AutoText,CoverPage,Tables,Watermarks, etc.) en lugar de escanear cada bloque de construcción solo por su nombre. BuildingBlockBehaviordetermina cómo se fusiona el contenido insertado con el documento circundante (Content,ParagraphoPage) — verifíquelo antes de asumir que un bloque de construcción se insertará de la manera que espera.- Dado que
BuildingBlockes unCompositeNode, trátelo como cualquier otro subárbol de nodos al crear o editar su contenido —AppendChild,InsertAftery métodos de nodo similares se aplican.
Problemas comunes
| Problema | Causa | Solución |
|---|---|---|
GetBuildingBlock() no devuelve nada | La galería, la categoría o el nombre no coinciden exactamente con un bloque de construcción existente | Enumere GlossaryDocument.BuildingBlocks para encontrar la combinación exacta Gallery/Category/Name |
| El contenido del bloque de construcción insertado se fusiona inesperadamente | Behavior (Content/Paragraph/Page) no está contabilizado | Compruebe BuildingBlock.Behavior antes de insertarlo para entender cómo se fusionará |
| El marcador de posición de la etiqueta de documento estructurado no muestra el contenido esperado | Placeholder apunta a un BuildingBlock diferente al supuesto | Lea StructuredDocumentTag.Placeholder para confirmar cuál bloque de construcción está realmente referenciado |
FAQ
¿Dónde se almacenan los bloques de construcción en un documento?
En el GlossaryDocument del documento, accesible a través de Document.GlossaryDocument, cuya propiedad BuildingBlocks es un BuildingBlockCollection.
¿Cómo encuentro un bloque de construcción específico, como una entrada AutoText?
Llame a GlossaryDocument.GetBuildingBlock(gallery, category, name) con el BuildingBlockGallery coincidente, la categoría y el nombre.
¿Puedo agregar nuevos bloques de construcción programáticamente?
Sí — BuildingBlockCollection admite Add(node) y Insert(index, node) ya que es un NodeCollection.
¿Qué controla BuildingBlockBehavior?
Cómo se fusiona el contenido del bloque de construcción en el documento cuando se inserta — como Content, un Paragraph completo, o un Page completo.
¿Cómo se relaciona un bloque de construcción con el texto del marcador de posición de una etiqueta de documento estructurado?
StructuredDocumentTag.Placeholder (y StructuredDocumentTagRangeStart.Placeholder) devuelven el BuildingBlock que proporciona el contenido del marcador de posición de un SDT cuando está vacío.
Resumen de API Reference
| Clase / Método | Descripción |
|---|---|
Document.GlossaryDocument | El GlossaryDocument del documento, que contiene todos los bloques de construcción |
GlossaryDocument.BuildingBlocks | BuildingBlockCollection de cada bloque de construcción |
GlossaryDocument.GetBuildingBlock() | Busca un bloque de construcción por galería, categoría y nombre |
BuildingBlock | Un CompositeNode con Name, Gallery, Category, Behavior, Type, Sections |
BuildingBlockCollection | Add(), Insert(), Remove(), Clear(), Contains(), IndexOf() |
BuildingBlockGallery / BuildingBlockType / BuildingBlockBehavior | Enums que clasifican un bloque de construcción |
StructuredDocumentTag.Placeholder | El BuildingBlock utilizado como contenido de marcador de posición de un SDT |
