Disegnare forme e filigrane

Disegnare forme e filigrane

I documenti Word conservano AutoShapes, immagini, caselle di testo e oggetti OLE in un livello di disegno separato, distinto dal flusso di testo dei paragrafi/righe. Aspose.Words FOSS per .NET modella questo livello con la classe Shape (oggetti di disegno concreti) e la sua base astratta ShapeBase, entrambi parte dello spazio dei nomi Aspose.Words.Drawing. Questa guida copre il modello di forma, l’inserimento di immagini e AutoShapes, il posizionamento e l’avvolgimento, riempimenti ed effetti, raggruppamento e filigrane.

Il modello Shape e ShapeBase

Shape — sealed, e il tipo con cui si lavora direttamente — rappresenta un AutoShape, casella di testo, forma libera, oggetto OLE, controllo ActiveX o immagine nel livello di disegno. Deriva dall’astratta ShapeBase, che fornisce le proprietà condivise da ogni oggetto di disegno: posizione (Left, Top, Width, Height, Rotation), il valore enum ShapeType, e sotto-oggetti di formattazione come Fill, Stroke, ShadowFormat, Glow e Reflection. GroupShape (anche un ShapeBase) rappresenta un gruppo di forme trattate come un’unica unità. Crea una forma autonoma direttamente con new Shape(doc, shapeType), dove shapeType è un valore ShapeType come Rectangle, Ellipse, Star o TextBox, quindi inseriscila nell’albero con DocumentBuilder.InsertNode(node).

Inserimento di immagini e AutoShapes con DocumentBuilder

Per le immagini in particolare, DocumentBuilder.InsertImage è il percorso più diretto: le overload accettano un Image, un percorso file, un Stream o un array di byte grezzo, con ulteriori overload che impostano width/height espliciti o un posizionamento completo (horzPos, left, vertPos, top, width, height, wrapType). L’oggetto Shape risultante espone i dati dell’immagine tramite la proprietà ImageData — ImageData.SetImage(...) per sostituire l’immagine, più CropTop/CropBottom/CropLeft/CropRight, Brightness, Contrast e GrayScale per regolazioni di base. Le istanze GroupShape sono create con DocumentBuilder.InsertGroupShape(shapes).

Posizionamento e avvolgimento del testo

Il posizionamento di una forma rispetto alla pagina è controllato da RelativeHorizontalPosition e RelativeVerticalPosition (ciascuno relativo a Page, Margin, Column o ancoraggi simili), insieme alle proprietà di offset Left/Top. HorizontalAlignment e VerticalAlignment gestiscono l’allineamento relativo semplice. Il modo in cui il testo circostante scorre attorno alla forma è impostato con WrapType e, per l’avvolgimento su lati specifici, WrapSide. IsInline indica se la forma scorre con il testo (inline) o galleggia in modo indipendente.

Riempimenti, Tratti ed Effetti

Shape.Fill (un oggetto Fill) controlla come viene dipinto l’interno della forma: Fill.Solid(color) per un colore uniforme, Fill.OneColorGradient(...) / Fill.TwoColorGradient(...) per i gradienti, Fill.Patterned(patternType) per un motivo e Fill.SetImage(...) per un riempimento immagine; FillType indica quale di questi è attivo. Il contorno è controllato tramite la proprietà Stroke, e gli effetti visivi sono esposti come oggetti di formattazione separati — ShadowFormat, Glow (GlowFormat), Reflection (ReflectionFormat) e SoftEdge (SoftEdgeFormat) — ognuno con il proprio metodo Remove() per rimuovere l’effetto.

Raggruppamento di forme e caselle di testo

Più forme possono essere combinate in un GroupShape, che si comporta come un unico ShapeBase con i propri Fill, ShadowFormat, Glow e Reflection. Per una forma che contiene testo, Shape.TextBox (un oggetto TextBox) espone la disposizione specifica del testo: InternalMarginLeft/Right/Top/Bottom per il riempimento interno, FitShapeToText per dimensionare automaticamente la forma, LayoutFlow per la direzione del testo e VerticalAnchor per l’allineamento verticale del testo all’interno della forma.

Watermarks

Document.Watermark (un oggetto Watermark) gestisce una filigrana a livello di documento indipendente da qualsiasi forma singola. Utilizza Watermark.SetText(text) o SetText(text, options) per una filigrana testuale, oppure SetImage(...) per una filigrana immagine, e Watermark.Remove() per rimuoverla. Watermark.Type indica la WatermarkType corrente (Text, Image o None). TextWatermarkOptions controlla FontFamily, FontSize, Color e Layout (WatermarkLayout.Horizontal o Diagonal); ImageWatermarkOptions controlla Scale e IsWashout.

Suggerimenti e migliori pratiche

• Usa ShapeBase quando scrivi codice che deve funzionare sia su istanze singole di Shape che di GroupShape; usa Shape direttamente quando ti servono membri specifici per immagini o AutoShape, come ImageData o Chart.
• Imposta RelativeHorizontalPosition / RelativeVerticalPosition insieme a WrapType quando flotti una forma — una forma in linea (predefinita per InsertImage) ignora le proprietà di posizionamento finché non la trasformi in forma fluttuante.
• Preferisci Document.Watermark per una singola filigrana a livello di documento invece di inserire manualmente e posizionare un Shape dietro al testo.
• Rimuovi un effetto usando il metodo Remove() dell’oggetto (ShadowFormat.Remove(), ReflectionFormat.Remove()) invece di impostare singole proprietà a zero.
• Verifica Shape.HasImage, Shape.HasChart o Shape.IsGroup prima di accedere a ImageData, Chart o a membri specifici di gruppo, poiché un Shape può rappresentare uno qualsiasi di diversi tipi di oggetti di disegno.

Problemi comuni

FAQ

Qual è la differenza tra Shape e ShapeBase?

ShapeBase è la classe base astratta condivisa da Shape e GroupShape. Usa ShapeBase nel codice che deve gestire entrambi i tipi in modo uniforme; usa Shape quando hai bisogno di membri specifici di un singolo oggetto di disegno, come ImageData o Chart.

Come aggiungo un’immagine a un documento?

Usa una delle overload di DocumentBuilder.InsertImage — passa un Image, un percorso file, un Stream o un array di byte, opzionalmente con width/height o con argomenti di posizionamento completi.

Come faccio a far galleggiare una forma invece di farla rimanere in linea con il testo?

Imposta il suo WrapType su un valore non in linea e imposta RelativeHorizontalPosition/RelativeVerticalPosition affinché gli offset Left/Top della forma vengano interpretati rispetto alla pagina, al margine o alla colonna.

Posso aggiungere sia una filigrana testuale sia una filigrana immagine?

Document.Watermark.Type riflette il tipo di filigrana corrente; impostare una nuova filigrana con SetText o SetImage sostituisce quella precedente, così un documento ha al massimo una filigrana attiva alla volta.

Come rimuovo un’ombra o un riflesso da una forma?

Chiama Remove() sull’oggetto di formattazione corrispondente — Shape.ShadowFormat.Remove() o Shape.Reflection.Remove().

API Reference Riepilogo

Vedi anche

• Aspose.Words for .NET — Enterprise Documentation