Introducción

Los documentos de Word colocan imágenes, cuadros de texto y otros objetos flotantes en una capa de dibujo que está separada del flujo normal de párrafos y tablas. Aspose.Words FOSS para .NET expone esta capa de dibujo a través de las clases Shape y ShapeBase, proporcionando acceso programático al mismo modelo de AutoShape, imagen, cuadro de texto y objeto OLE que Word utiliza internamente. Esta guía muestra cómo la biblioteca representa y manipula estos objetos de dibujo — posicionamiento, formato de relleno y contorno, imágenes incrustadas y texto dispuesto dentro de una forma — en documentos DOCX, DOCM, DOTX y DOTM.

Esto es útil para código que crea plantillas de informes o membretes con un logotipo o gráfico posicionado, genera documentos con cuadros de texto flotantes y notas emergentes, o inspecciona formas ya presentes en un documento cargado — extrayendo los bytes de una imagen incrustada, leyendo el nombre del firmante de una línea de firma, o reposicionando una imagen existente.

Aspose.Words FOSS para .NET se publica bajo la licencia MIT y se dirige a .NET Standard 2.0, por lo que funciona en .NET Framework 4.6.2+ y .NET 6, 8 y 10 sin dependencias nativas. Instálalo vía NuGet, o compílalo desde el código fuente (ver Inicio rápido a continuación). Es el mismo motor de documentos Aspose.Words usado comercialmente, no una reescritura ni un contenedor, por lo que las clases Shape y de capa de dibujo descritas aquí son la API de producción.

Características clave

El modelo de objeto Shape y ShapeBase

Cada AutoShape, cuadro de texto, imagen incrustada, objeto OLE o control ActiveX anclado en un documento de Word está representado por la clase Shape, que es sellada y se construye sobre la clase base abstracta ShapeBase. Ambas comparten la misma superficie de posicionamiento y formato: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation y Shape.ZOrder para la geometría, además de las banderas Shape.IsGroup, Shape.IsImage, Shape.IsWordArt y Shape.IsInline que describen qué tipo de objeto contiene una instancia dada. El enumerado ShapeType enumera los tipos concretos de forma que Word reconoce — Rectángulo, Elipse, Línea, Flecha, una familia de tipos de llamada y conector, TextBox, Imagen y OleObject entre más de ochenta valores — de modo que el código que recorre las formas de un documento pueda ramificarse en Shape.ShapeType para decidir cómo manejar cada una. Múltiples formas pueden combinarse en un solo GroupShape, que a su vez es una subclase de ShapeBase, la cual mantiene un conjunto de formas posicionadas y redimensionadas juntas; DocumentBuilder.InsertGroupShape(shapes) crea una a partir de una matriz existente de formas.

Cuadros de texto y WordArt

Cualquier Shape puede contener su propio texto a través de la clase TextBox, expuesta como Shape.TextBox. Las propiedades TextBox controlan cómo se sitúa ese texto dentro de la forma: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop y TextBox.InternalMarginBottom para el relleno, TextBox.FitShapeToText para permitir que la forma crezca con su contenido, LayoutFlow para la dirección del texto, TextBoxWrapMode para cómo el texto se ajusta dentro del cuadro, y TextBox.VerticalAnchor — un valor TextBoxAnchor como Top, Middle, BottomCentered o TopBaseline — para la alineación vertical. Los cuadros de texto enlazados, donde el texto desbordado continúa en un segundo cuadro, se modelan con TextBox.Next y TextBox.Previous. Una clase relacionada pero distinta, TextPath, define texto estilo WordArt que sigue el contorno de una forma en lugar de situarse dentro de ella, con propiedades como TextPath.Text, TextPath.FontFamily, TextPath.Bold y TextPath.RotateLetters, más un enum TextPathAlignment con valores como Stretch, Center y LetterJustify.

Imágenes y gráficos incrustados

Cuando una forma contiene una imagen, Shape.HasImage es verdadero y Shape.ImageData devuelve un objeto ImageData. ImageData expone los bytes sin procesar a través de ImageData.ImageBytes, el formato detectado a través de ImageType (valores que incluyen Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps y WebP), las dimensiones de píxel y la resolución a través de ImageSize, y el recorte mediante ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft y ImageData.CropRight. Los ajustes de color — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel y ImageData.ChromaKey — son propiedades del mismo objeto, y ImageData.IsLink/ImageData.IsLinkOnly distinguen una imagen incrustada de una que solo referencia una ruta de archivo externa. DocumentBuilder.InsertImage() tiene sobrecargas que aceptan una imagen, una ruta de archivo, un array de bytes o un flujo, incluyendo variantes que también establecen ancho, alto, posición horizontal y vertical, y WrapType en el momento de la inserción.

Relleno, trazo y efectos de forma

Cada Shape y GroupShape lleva un objeto Fill y un objeto Stroke para su interior y contorno. Fill admite seis tipos de relleno a través de FillType, con valores que incluyen Solid, Patterned, Gradient, Textured, Background y Picture, configurados con métodos como Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) o Fill.SetImage(fileName). Stroke controla el contorno: Stroke.Weight, DashStyle, JoinStyle, EndCap y Stroke.LineStyle (un valor ShapeLineStyle) cubren la propia línea, mientras que Stroke.StartArrowType y Stroke.EndArrowType, junto con los enums ArrowWidth y ArrowLength, configuran las puntas de flecha en formas de conector y línea. Más allá del relleno y el trazo, Shape expone cuatro objetos de efecto adicionales — ShadowFormat, ReflectionFormat, GlowFormat y SoftEdgeFormat — cada uno con sus propias propiedades de color y transparencia para el efecto visual correspondiente.

Posicionamiento y ajuste de texto

Las formas que flotan en relación con la página o el párrafo utilizan RelativeHorizontalPosition y RelativeVerticalPosition para anclarse —por ejemplo, al margen, página o columna— combinados con RelativeHorizontalSize y RelativeVerticalSize para el anclaje de tamaño, más HorizontalAlignment y VerticalAlignment para una colocación simple izquierda/centrada/derecha o arriba/medio/abajo. Cómo el texto circundante reacciona a una forma está controlado por WrapType, con valores que incluyen Inline, Square, Tight, TopBottom y None; para el ajuste Square y Tight, WrapSide lo restringe aún más a Left, Right, Both o Largest. FlipOrientation refleja una forma horizontal o verticalmente sin cambiar sus coordenadas, y las banderas Shape.AllowOverlap/Shape.BehindText controlan cómo una forma interactúa con otro contenido flotante y la capa de texto debajo de ella.

Líneas de firma y reglas horizontales

Dos tipos de forma más especializados viven en el mismo modelo de dibujo. SignatureLine, configurado en el momento de inserción a través de SignatureLineOptions (las propiedades incluyen SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate y SignatureLineOptions.AllowComments), genera el bloque visual de firma que se ve en los documentos imprimibles y expone SignatureLine.IsSigned y SignatureLine.IsValid una vez que se ha aplicado una firma — esto es distinto de la verificación criptográfica de firma digital tratada en otro lugar, que funciona con partes firmadas del documento en lugar de con la forma misma. HorizontalRuleFormat cubre la línea divisoria simple insertada con DocumentBuilder.InsertHorizontalRule(), con propiedades HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color y HorizontalRuleFormat.Alignment (la última un valor HorizontalRuleAlignment).

Inicio rápido

Aspose.Words FOSS para .NET está disponible a través de NuGet:

dotnet add package Aspose.Words.FOSS

Para compilar desde el código fuente en su lugar:

git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release

Agregue una referencia de proyecto a Aspose.Words.csproj desde su aplicación. A partir de ahí, trabajar con la capa de dibujo sigue el patrón usado a lo largo de este artículo: cargue o cree un Document, recorra sus formas con Document.GetChildNodes(NodeType.Shape, true) o inserte una nueva con un método DocumentBuilder como DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape() o DocumentBuilder.InsertHorizontalRule(), luego lea o establezca propiedades en el Shape devuelto — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType y el resto — antes de llamar a Document.Save().

Formatos compatibles

FormatoExtensiónLeerEscribir
DOCX.docx✓✓
DOCM.docm✓✓
DOTX.dotx✓✓
DOTM.dotm✓✓
OPC plano (todas las variantes)(varios)✓✓
Markdown.md✓✓
Text.txt✓✓

Esta edición excluye intencionalmente el diseño y renderizado de páginas — sin PDF, XPS, ni exportación de imágenes, y sin impresión — de modo que el Shape.Bounds de una forma y la geometría dependiente del diseño reflejen los valores almacenados en el documento en lugar de un diseño de página calculado. Los convertidores de formato adicionales (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, y WordML) no se leen ni se escriben; estos son los mismos subsistemas eliminados del código comercial para mantener esta edición gratuita.

Código abierto y licencias

Aspose.Words FOSS para .NET se publica bajo la licencia MIT, libre tanto para uso comercial como personal sin regalías ni restricciones de redistribución. El código fuente completo está disponible en GitHub en el Aspose.Words FOSS para .NET repository.

Primeros pasos

Recursos relacionados