Introdução
Os documentos do Word colocam imagens, caixas de texto e outros objetos flutuantes em uma camada de desenho que fica separada do fluxo regular de parágrafos e tabelas. Aspose.Words FOSS para .NET expõe essa camada de desenho por meio das classes Shape e ShapeBase, oferecendo acesso programático ao mesmo modelo de AutoShape, imagem, caixa de texto e objeto OLE que o próprio Word usa internamente. Este guia mostra como a biblioteca representa e manipula esses objetos de desenho — posicionamento, preenchimento e formatação de contorno, imagens incorporadas e texto disposto dentro de uma forma — em documentos DOCX, DOCM, DOTX e DOTM.
Isto é útil para código que cria modelos de relatório ou papel timbrado com um logotipo ou gráfico posicionado, gera documentos com caixas de texto e balões flutuantes, ou inspeciona formas já presentes em um documento enviado — extraindo os bytes de uma imagem incorporada, lendo o nome do assinante de uma linha de assinatura, ou reposicionando uma imagem existente.
Aspose.Words FOSS para .NET é lançado sob a licença MIT e tem como alvo o .NET Standard 2.0, portanto funciona no .NET Framework 4.6.2+ e no .NET 6, 8 e 10 sem dependências nativas. Instale-o via NuGet, ou compile a partir do código-fonte (veja o Início Rápido abaixo). É o mesmo motor de documentos Aspose.Words usado comercialmente, não uma reescrita ou um wrapper, portanto as classes Shape e de camada de desenho descritas aqui são a API de produção.
Principais Recursos
O Modelo de Objeto Shape e ShapeBase
Todo AutoShape, caixa de texto, imagem incorporada, objeto OLE ou controle ActiveX ancorado em um documento Word é representado pela classe Shape — selada e construída sobre a classe base abstrata ShapeBase. Ambas compartilham a mesma superfície de posicionamento e formatação: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation e Shape.ZOrder para geometria, além das flags Shape.IsGroup, Shape.IsImage, Shape.IsWordArt e Shape.IsInline que descrevem que tipo de objeto a instância contém. O enum ShapeType enumera os tipos concretos de forma que o Word reconhece — Retângulo, Elipse, Linha, Seta, uma família de tipos de balão e conector, TextBox, Imagem e OleObject entre mais de oitenta valores — de modo que o código que percorre as formas de um documento pode ramificar em Shape.ShapeType para decidir como tratar cada uma. Várias formas podem ser combinadas em um único GroupShape, que é uma subclasse de ShapeBase, mantendo um conjunto de formas posicionadas e redimensionadas juntas; DocumentBuilder.InsertGroupShape(shapes) cria uma a partir de um array existente de formas.
Caixas de Texto e WordArt
Qualquer Shape pode conter seu próprio texto através da classe TextBox, exposta como Shape.TextBox. As propriedades TextBox controlam como esse texto se posiciona dentro da forma: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop e TextBox.InternalMarginBottom para preenchimento, TextBox.FitShapeToText para permitir que a forma cresça com seu conteúdo, LayoutFlow para a direção do texto, TextBoxWrapMode para como o texto é envolvido dentro da caixa, e TextBox.VerticalAnchor — um valor TextBoxAnchor como Top, Middle, BottomCentered ou TopBaseline — para alinhamento vertical. Caixas de texto vinculadas, onde o texto excedente continua em uma segunda caixa, são modeladas com TextBox.Next e TextBox.Previous. Uma classe relacionada, porém distinta, TextPath, define texto no estilo WordArt que segue o contorno de uma forma em vez de ficar dentro dela, com propriedades como TextPath.Text, TextPath.FontFamily, TextPath.Bold e TextPath.RotateLetters, além de um enum TextPathAlignment com valores como Stretch, Center e LetterJustify.
Imagens e Imagens Incorporadas
Quando uma forma contém uma imagem, Shape.HasImage é verdadeiro e Shape.ImageData retorna um objeto ImageData. ImageData expõe os bytes brutos através de ImageData.ImageBytes, o formato detectado através de ImageType (valores incluindo Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps e WebP), as dimensões em pixels e a resolução através de ImageSize, e o recorte via ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft e ImageData.CropRight. Ajustes de cor — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel e ImageData.ChromaKey — são propriedades no mesmo objeto, e ImageData.IsLink/ImageData.IsLinkOnly distinguem uma imagem incorporada de uma que apenas referencia um caminho de arquivo externo. DocumentBuilder.InsertImage() possui sobrecargas que aceitam uma imagem, um caminho de arquivo, um array de bytes ou um stream, incluindo variantes que também definem largura, altura, posição horizontal e vertical explícitas, e WrapType no momento da inserção.
Preenchimento, Contorno e Efeitos de Forma
Cada Shape e GroupShape possui um objeto Fill e um objeto Stroke para seu interior e contorno. Fill oferece seis tipos de preenchimento através de FillType, com valores incluindo Solid, Patterned, Gradient, Textured, Background e Picture, definidos com métodos como Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) ou Fill.SetImage(fileName). Stroke controla o contorno: Stroke.Weight, DashStyle, JoinStyle, EndCap e Stroke.LineStyle (um valor ShapeLineStyle) abrangem a própria linha, enquanto Stroke.StartArrowType e Stroke.EndArrowType, combinados com os enums ArrowWidth e ArrowLength, configuram pontas de seta em formas de conector e linha. Além de preenchimento e contorno, Shape expõe quatro objetos de efeito adicionais — ShadowFormat, ReflectionFormat, GlowFormat e SoftEdgeFormat — cada um contendo suas próprias propriedades de cor e transparência para o efeito visual correspondente.
Posicionamento e Quebra de Texto
Formas que flutuam em relação à página ou ao parágrafo usam RelativeHorizontalPosition e RelativeVerticalPosition para ancorar-se — à margem, página ou coluna, por exemplo — combinados com RelativeHorizontalSize e RelativeVerticalSize para ancoragem de tamanho, além de HorizontalAlignment e VerticalAlignment para posicionamento simples esquerda/centro/direita ou superior/meio/inferior. Como o texto ao redor reage a uma forma é controlado por WrapType, com valores incluindo Inline, Square, Tight, TopBottom e None; para o envolvimento Square e Tight, WrapSide o restringe ainda mais a Left, Right, Both ou Largest. FlipOrientation espelha uma forma horizontal ou verticalmente sem mudar suas coordenadas, e as bandeiras Shape.AllowOverlap/Shape.BehindText controlam como uma forma interage com outro conteúdo flutuante e a camada de texto abaixo dela.
Linhas de Assinatura e Regras Horizontais
Mais dois tipos especializados de forma vivem no mesmo modelo de desenho. SignatureLine, configurado no momento da inserção através de SignatureLineOptions (as propriedades incluem SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate e SignatureLineOptions.AllowComments), renderiza o bloco visual de assinatura visto em documentos imprimíveis e expõe SignatureLine.IsSigned e SignatureLine.IsValid assim que uma assinatura é aplicada a ele — isso é distinto da verificação criptográfica de assinatura digital abordada em outra parte, que trabalha com partes assinadas do documento em vez da própria forma. HorizontalRuleFormat cobre a linha divisória simples inserida com DocumentBuilder.InsertHorizontalRule(), com as propriedades HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color e HorizontalRuleFormat.Alignment (sendo a última um valor HorizontalRuleAlignment).
Início Rápido
Aspose.Words FOSS para .NET está disponível via NuGet:
dotnet add package Aspose.Words.FOSSPara compilar a partir do código-fonte:
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
Adicione uma referência de projeto ao Aspose.Words.csproj a partir da sua aplicação. A partir daí, trabalhar com a camada de desenho segue o padrão usado ao longo deste post: carregue ou crie um Document, percorra suas formas com Document.GetChildNodes(NodeType.Shape, true) ou insira uma nova usando um método DocumentBuilder como DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape() ou DocumentBuilder.InsertHorizontalRule(), então leia ou defina propriedades no Shape retornado — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType e o restante — antes de chamar Document.Save().
Formatos Suportados
| Formato | Extensão | Ler | Escrever |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (todas as variantes) | (vários) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Esta edição exclui intencionalmente o layout e a renderização de página — sem exportação para PDF, XPS ou imagem, e sem impressão — de modo que o Shape.Bounds de uma forma e a geometria dependente do layout reflitam os valores armazenados no documento em vez de um layout de página calculado. Os conversores de formato adicionais (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 e WordML) não são lidos nem gravados; esses são os mesmos subsistemas removidos da base de código comercial para manter esta edição gratuita.
Código Aberto & Licenciamento
Aspose.Words FOSS para .NET é lançado sob a licença MIT, gratuito tanto para uso comercial quanto pessoal, sem royalties ou restrições de redistribuição. O código-fonte completo está disponível em GitHub no Aspose.Words FOSS para .NET repositório.
