Desenhando Formas e Marcas d'água

Desenhando Formas e Marcas d’água

Os documentos Word mantêm AutoShapes, imagens, caixas de texto e objetos OLE em uma camada de desenho separada, distinta do fluxo de texto de parágrafos/execuções. Aspose.Words FOSS para .NET modela essa camada com a classe Shape (objetos de desenho concretos) e sua base abstrata ShapeBase, ambas parte do namespace Aspose.Words.Drawing. Este guia aborda o modelo de forma, inserção de imagens e AutoShapes, posicionamento e ajuste, preenchimentos e efeitos, agrupamento e marcas d’água.

A Forma e o Modelo ShapeBase

Shape — selado, e o tipo com o qual você trabalha diretamente — representa um AutoShape, caixa de texto, forma livre, objeto OLE, controle ActiveX ou imagem na camada de desenho. Ele deriva da classe abstrata ShapeBase, que fornece as propriedades compartilhadas por todos os objetos de desenho: posição (Left, Top, Width, Height, Rotation), o valor enum ShapeType, e sub-objetos de formatação como Fill, Stroke, ShadowFormat, Glow e Reflection. GroupShape (também um ShapeBase) representa um grupo de formas tratado como uma única unidade. Construa uma forma independente diretamente com new Shape(doc, shapeType), onde shapeType é um valor ShapeType como Rectangle, Ellipse, Star ou TextBox, então insira-a na árvore com DocumentBuilder.InsertNode(node).

Inserindo Imagens e AutoShapes com DocumentBuilder

Para imagens especificamente, DocumentBuilder.InsertImage é a rota mais direta: as sobrecargas aceitam um Image, um caminho de arquivo, um Stream ou um array de bytes bruto, com outras sobrecargas que definem width/height explícitos ou posicionamento completo (horzPos, left, vertPos, top, width, height, wrapType). O Shape resultante expõe seus dados de imagem através da propriedade ImageData — ImageData.SetImage(...) para substituir a imagem, além de CropTop/CropBottom/CropLeft/CropRight, Brightness, Contrast e GrayScale para ajustes básicos. Instâncias de GroupShape são criadas com DocumentBuilder.InsertGroupShape(shapes).

Posicionamento e Ajuste de Texto

O posicionamento de uma forma em relação à página é controlado por RelativeHorizontalPosition e RelativeVerticalPosition (cada um relativo a Page, Margin, Column, ou âncoras semelhantes), juntamente com as propriedades de deslocamento Left/Top. HorizontalAlignment e VerticalAlignment tratam do alinhamento relativo simples. Como o texto ao redor flui ao redor da forma é definido com WrapType e, para quebra de linha específica de lado, WrapSide. IsInline indica se a forma flui com o texto (inline) ou flutua independentemente.

Preenchimentos, Contornos e Efeitos

Shape.Fill (um objeto Fill) controla como o interior da forma é pintado: Fill.Solid(color) para uma cor sólida, Fill.OneColorGradient(...) / Fill.TwoColorGradient(...) para gradientes, Fill.Patterned(patternType) para um padrão e Fill.SetImage(...) para preenchimento de imagem; FillType indica qual destes está ativo. O contorno é controlado através da propriedade Stroke, e os efeitos visuais são expostos como objetos de formatação separados — ShadowFormat, Glow (GlowFormat), Reflection (ReflectionFormat) e SoftEdge (SoftEdgeFormat) — cada um com seu próprio método Remove() para limpar o efeito.

Agrupando Formas e Caixas de Texto

Múltiplas formas podem ser combinadas em um GroupShape, que por sua vez se comporta como um único ShapeBase com seus próprios Fill, ShadowFormat, Glow e Reflection. Para uma forma que contém texto, Shape.TextBox (um objeto TextBox) expõe o layout específico de texto: InternalMarginLeft/Right/Top/Bottom para preenchimento interno, FitShapeToText para ajustar automaticamente o tamanho da forma, LayoutFlow para a direção do texto e VerticalAnchor para o alinhamento vertical do texto dentro da forma.

Watermarks

Document.Watermark (um objeto Watermark) gerencia uma marca d’água de todo o documento, independente de qualquer forma única. Chame Watermark.SetText(text) ou SetText(text, options) para uma marca d’água de texto, ou SetImage(...) para uma marca d’água de imagem, e Watermark.Remove() para removê-la. Watermark.Type indica a WatermarkType atual (Text, Image ou None). TextWatermarkOptions controla FontFamily, FontSize, Color e Layout (WatermarkLayout.Horizontal ou Diagonal); ImageWatermarkOptions controla Scale e IsWashout.

Dicas e Melhores Práticas

• Use ShapeBase ao escrever código que deve funcionar tanto em instâncias únicas de Shape quanto de GroupShape; use Shape diretamente quando precisar de membros específicos de imagem ou AutoShape, como ImageData ou Chart.
• Defina RelativeHorizontalPosition / RelativeVerticalPosition junto com WrapType ao flutuar uma forma — uma forma em linha (o padrão para InsertImage) ignora propriedades de posicionamento até que você a torne flutuante.
• Prefira Document.Watermark para uma marca d’água única em todo o documento, em vez de inserir e posicionar manualmente um Shape atrás do texto.
• Limpe um efeito usando o método Remove() do objeto (ShadowFormat.Remove(), ReflectionFormat.Remove()) em vez de definir propriedades individuais como zero.
• Verifique Shape.HasImage, Shape.HasChart ou Shape.IsGroup antes de acessar ImageData, Chart ou membros específicos de grupo, pois um Shape pode representar qualquer um de vários tipos de objeto de desenho.

Problemas comuns

FAQ

Qual é a diferença entre Shape e ShapeBase?

ShapeBase é a classe base abstrata compartilhada por Shape e GroupShape. Use ShapeBase no código que deve lidar com qualquer um dos tipos de forma uniforme; use Shape quando precisar de membros específicos de um único objeto de desenho, como ImageData ou Chart.

Como adiciono uma imagem a um documento?

Use uma das sobrecargas de DocumentBuilder.InsertImage — passe um Image, um caminho de arquivo, um Stream ou um array de bytes, opcionalmente com width/height ou argumentos de posicionamento completos.

Como faço para que uma forma flutue em vez de ficar em linha com o texto?

Defina seu WrapType para um valor não em linha e ajuste RelativeHorizontalPosition / RelativeVerticalPosition para que os deslocamentos Left/Top da forma sejam interpretados em relação à página, margem ou coluna.

Posso adicionar uma marca d’água de texto e uma de imagem?

Document.Watermark.Type reflete o tipo de marca d’água atual; definir uma nova marca d’água com SetText ou SetImage substitui o que estava anteriormente, de modo que um documento tem no máximo uma marca d’água ativa por vez.

Como removo uma sombra ou reflexão de uma forma?

Chame Remove() no objeto de formatação correspondente — Shape.ShadowFormat.Remove() ou Shape.Reflection.Remove().

API Reference Resumo

Ver também

• Aspose.Words for .NET — Enterprise Documentation