Dibujando Formas y Marcas de Agua

Dibujar formas y marcas de agua

Los documentos de Word mantienen AutoShapes, imágenes, cuadros de texto y objetos OLE en una capa de dibujo separada, distinta del flujo de texto de párrafo/segmento. Aspose.Words FOSS para .NET modela esta capa con la clase Shape (objetos de dibujo concretos) y su base abstracta ShapeBase, ambas parte del espacio de nombres Aspose.Words.Drawing. Esta guía cubre el modelo de forma, la inserción de imágenes y AutoShapes, el posicionamiento y el ajuste de texto, los rellenos y efectos, la agrupación y las marcas de agua.

El modelo Shape y ShapeBase

Shape — sellado, y el tipo con el que trabajas directamente — representa un AutoShape, cuadro de texto, forma libre, objeto OLE, control ActiveX o imagen en la capa de dibujo. Deriva de la clase abstracta ShapeBase, que proporciona las propiedades compartidas por cada objeto de dibujo: posición (Left, Top, Width, Height, Rotation), el valor del enumerado ShapeType, y sub-objetos de formato como Fill, Stroke, ShadowFormat, Glow y Reflection. GroupShape (también un ShapeBase) representa un grupo de formas tratado como una sola unidad. Construye una forma independiente directamente con new Shape(doc, shapeType), donde shapeType es un valor ShapeType como Rectangle, Ellipse, Star o TextBox, y luego insértala en el árbol con DocumentBuilder.InsertNode(node).

Insertar imágenes y AutoShapes con DocumentBuilder

Para imágenes específicamente, DocumentBuilder.InsertImage es la vía más directa: las sobrecargas aceptan un Image, una ruta de archivo, un Stream o una matriz de bytes cruda, con sobrecargas adicionales que establecen width/height explícitos o un posicionamiento completo (horzPos, left, vertPos, top, width, height, wrapType). El Shape resultante expone sus datos de imagen a través de la propiedad ImageData — ImageData.SetImage(...) para reemplazar la imagen, además de CropTop/CropBottom/CropLeft/CropRight, Brightness, Contrast y GrayScale para ajustes básicos. Las instancias de GroupShape se crean con DocumentBuilder.InsertGroupShape(shapes).

Posicionamiento y ajuste de texto

La colocación de una forma respecto a la página se controla mediante RelativeHorizontalPosition y RelativeVerticalPosition (cada una relativa a Page, Margin, Column, o anclas similares), junto con las propiedades de desplazamiento Left/Top. HorizontalAlignment y VerticalAlignment manejan la alineación relativa simple. Cómo el texto circundante fluye alrededor de la forma se establece con WrapType y, para el ajuste específico de cada lado, WrapSide. IsInline indica si la forma fluye con el texto (en línea) o flota de forma independiente.

Rellenos, Contornos y Efectos

Shape.Fill (un objeto Fill) controla cómo se pinta el interior de la forma: Fill.Solid(color) para un color sólido, Fill.OneColorGradient(...) / Fill.TwoColorGradient(...) para degradados, Fill.Patterned(patternType) para un patrón, y Fill.SetImage(...) para un relleno de imagen; FillType indica cuál de estos está activo. El contorno se controla mediante la propiedad Stroke, y los efectos visuales se exponen como objetos de formato separados — ShadowFormat, Glow (GlowFormat), Reflection (ReflectionFormat), y SoftEdge (SoftEdgeFormat) — cada uno con su propio método Remove() para eliminar el efecto.

Agrupar Formas y Cuadros de Texto

Se pueden combinar múltiples formas en un GroupShape, que a su vez se comporta como un único ShapeBase con sus propios Fill, ShadowFormat, Glow y Reflection. Para una forma que contiene texto, Shape.TextBox (un objeto TextBox) expone el diseño específico del texto: InternalMarginLeft/Right/Top/Bottom para el relleno interno, FitShapeToText para dimensionar automáticamente la forma, LayoutFlow para la dirección del texto, y VerticalAnchor para la alineación vertical del texto dentro de la forma.

Watermarks

Document.Watermark (un objeto Watermark) gestiona una marca de agua a nivel de documento independiente de cualquier forma individual. Llame a Watermark.SetText(text) o SetText(text, options) para una marca de agua de texto, o a SetImage(...) para una marca de agua de imagen, y a Watermark.Remove() para eliminarla. Watermark.Type indica la WatermarkType actual (Text, Image o None). TextWatermarkOptions controla FontFamily, FontSize, Color y Layout (WatermarkLayout.Horizontal o Diagonal); ImageWatermarkOptions controla Scale y IsWashout.

Consejos y Mejores Prácticas

• Utilice ShapeBase al escribir código que debe funcionar tanto en instancias únicas de Shape como de GroupShape; use Shape directamente cuando necesite miembros específicos de imagen o de AutoShape, como ImageData o Chart.
• Establezca RelativeHorizontalPosition / RelativeVerticalPosition junto con WrapType al flotar una forma — una forma en línea (el valor predeterminado para InsertImage) ignora las propiedades de posicionamiento hasta que la haga flotar.
• Prefiera Document.Watermark para una marca de agua única en todo el documento en lugar de insertar y posicionar manualmente un Shape detrás del texto.
• Elimine un efecto con el método Remove() de su objeto (ShadowFormat.Remove(), ReflectionFormat.Remove()) en lugar de establecer propiedades individuales a cero.
• Verifique Shape.HasImage, Shape.HasChart o Shape.IsGroup antes de acceder a ImageData, Chart o miembros específicos de grupo, ya que un Shape puede representar cualquiera de varios tipos de objetos de dibujo.

Problemas comunes

FAQ

¿Cuál es la diferencia entre Shape y ShapeBase?

ShapeBase es la clase base abstracta compartida por Shape y GroupShape. Use ShapeBase en código que deba manejar ambos tipos de forma uniforme; use Shape cuando necesite miembros específicos de un único objeto de dibujo, como ImageData o Chart.

¿Cómo añado una imagen a un documento?

Utilice una de las sobrecargas de DocumentBuilder.InsertImage — pase un Image, una ruta de archivo, un Stream o una matriz de bytes, opcionalmente con width/height o con argumentos de posicionamiento completos.

¿Cómo hago que una forma flote en lugar de estar en línea con el texto?

Establezca su WrapType a un valor que no sea en línea y configure RelativeHorizontalPosition / RelativeVerticalPosition para que los desplazamientos Left/Top de la forma se interpreten en relación con la página, el margen o la columna.

¿Puedo añadir tanto una marca de agua de texto como una de imagen?

Document.Watermark.Type refleja el tipo de marca de agua actual; establecer una nueva marca de agua con SetText o SetImage reemplaza lo que había antes, de modo que un documento tiene como máximo una marca de agua activa a la vez.

¿Cómo elimino una sombra o reflexión de una forma?

Llame Remove() al objeto de formato correspondiente — Shape.ShadowFormat.Remove() o Shape.Reflection.Remove().

Resumen de API Reference

Ver también

• Aspose.Words for .NET — Enterprise Documentation