Introduzione
I documenti Word inseriscono immagini, caselle di testo e altri oggetti liberi in un livello di disegno che si trova al di fuori del flusso regolare di paragrafi e tabelle. Aspose.Words FOSS per .NET espone questo livello di disegno attraverso le classi Shape e ShapeBase, fornendo un accesso programmatico allo stesso modello di AutoShape, immagine, casella di testo e oggetto OLE che Word stesso utilizza internamente. Questa guida mostra come la libreria rappresenta e manipola questi oggetti di disegno — posizionamento, formattazione di riempimento e contorno, immagini incorporate e testo disposto all’interno di una forma — nei documenti DOCX, DOCM, DOTX e DOTM.
Ciò è utile per il codice che crea modelli di report o di intestazione con un logo o un’illustrazione posizionata, genera documenti con caselle di testo e callout fluttuanti, o ispeziona forme già presenti in un documento caricato — estraendo i byte di un’immagine incorporata, leggendo il nome del firmatario di una riga di firma, o riposizionando un’immagine esistente.
Aspose.Words FOSS per .NET è rilasciato sotto licenza MIT e mira a .NET Standard 2.0, quindi funziona su .NET Framework 4.6.2+ e .NET 6, 8 e 10 senza dipendenze native. Installalo tramite NuGet, o compila dal sorgente (vedi Avvio rapido di seguito). È lo stesso motore di documenti Aspose.Words usato commercialmente, non una riscrittura o un wrapper, quindi le classi Shape e del livello di disegno descritte qui sono il API di produzione.
Caratteristiche principali
Il modello di oggetti Shape e ShapeBase
Ogni AutoShape, casella di testo, immagine incorporata, oggetto OLE o controllo ActiveX ancorato in un documento Word è rappresentato dalla classe Shape — sigillata e basata sulla classe astratta ShapeBase. Entrambe condividono la stessa superficie di posizionamento e formattazione: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation e Shape.ZOrder per la geometria, oltre ai flag Shape.IsGroup, Shape.IsImage, Shape.IsWordArt e Shape.IsInline che descrivono il tipo di oggetto contenuto dall’istanza. L’enumerazione ShapeType elenca i tipi concreti di forma riconosciuti da Word — Rettangolo, Ellisse, Linea, Freccia, una famiglia di tipi di callout e connettori, TextBox, Immagine e OleObject tra più di ottanta valori — così il codice che attraversa le forme di un documento può ramificare su Shape.ShapeType per decidere come gestire ciascuna. Più forme possono essere combinate in un unico GroupShape, esso stesso una sottoclasse di ShapeBase, che mantiene un insieme di forme posizionate e ridimensionate insieme; DocumentBuilder.InsertGroupShape(shapes) ne crea una da un array esistente di forme.
Caselle di testo e WordArt
Qualsiasi Shape può contenere il proprio testo tramite la classe TextBox, esposta come Shape.TextBox. Le proprietà TextBox controllano come quel testo si posiziona all’interno della forma: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop e TextBox.InternalMarginBottom per il padding, TextBox.FitShapeToText per consentire alla forma di crescere con il contenuto, LayoutFlow per la direzione del testo, TextBoxWrapMode per il modo in cui il testo avvolge all’interno della casella, e TextBox.VerticalAnchor — un valore TextBoxAnchor come Top, Middle, BottomCentered o TopBaseline — per l’allineamento verticale. Le caselle di testo collegate, in cui il testo in eccesso continua in una seconda casella, sono modellate con TextBox.Next e TextBox.Previous. Una classe correlata ma distinta, TextPath, definisce testo in stile WordArt che segue il contorno di una forma invece di trovarsi all’interno, con proprietà come TextPath.Text, TextPath.FontFamily, TextPath.Bold e TextPath.RotateLetters, oltre a un enum TextPathAlignment con valori come Stretch, Center e LetterJustify.
Immagini e immagini incorporate
Quando una forma contiene un’immagine, Shape.HasImage è vero e Shape.ImageData restituisce un oggetto ImageData. ImageData espone i byte grezzi tramite ImageData.ImageBytes, il formato rilevato tramite ImageType (valori includono Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps e WebP), le dimensioni in pixel e la risoluzione tramite ImageSize, e il ritaglio tramite ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft e ImageData.CropRight. Le regolazioni del colore — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel e ImageData.ChromaKey — sono proprietà dello stesso oggetto, e ImageData.IsLink/ImageData.IsLinkOnly distinguono un’immagine incorporata da una che fa solo riferimento a un percorso di file esterno. DocumentBuilder.InsertImage() ha overload che accettano un’immagine, un percorso file, un array di byte o uno stream, includendo varianti che impostano anche larghezza esplicita, altezza, posizione orizzontale e verticale, e WrapType al momento dell’inserimento.
Riempimento, contorno ed effetti della forma
Ogni Shape e GroupShape possiede un oggetto Fill e un oggetto Stroke per il suo interno e il contorno. Fill supporta sei tipi di riempimento tramite FillType, con valori includono Solid, Patterned, Gradient, Textured, Background e Picture, impostati con metodi come Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) o Fill.SetImage(fileName). Stroke controlla il contorno: Stroke.Weight, DashStyle, JoinStyle, EndCap e Stroke.LineStyle (un valore ShapeLineStyle) coprono la linea stessa, mentre Stroke.StartArrowType e Stroke.EndArrowType, associati agli enum ArrowWidth e ArrowLength, configurano le punte delle frecce su forme di connettore e linea. Oltre al riempimento e al contorno, Shape espone quattro ulteriori oggetti effetto — ShadowFormat, ReflectionFormat, GlowFormat e SoftEdgeFormat — ognuno con le proprie proprietà di colore e trasparenza per l’effetto visivo corrispondente.
Posizionamento e avvolgimento del testo
Le forme che fluttuano rispetto alla pagina o al paragrafo utilizzano RelativeHorizontalPosition e RelativeVerticalPosition per ancorarsi — al margine, alla pagina o alla colonna, ad esempio — in combinazione con RelativeHorizontalSize e RelativeVerticalSize per l’ancoraggio delle dimensioni, più HorizontalAlignment e VerticalAlignment per una semplice posizione sinistra/centrata/destra o alto/centrato/basso. Il modo in cui il testo circostante reagisce a una forma è controllato da WrapType, con valori includono Inline, Square, Tight, TopBottom e None; per l’avvolgimento Square e Tight, WrapSide lo restringe ulteriormente a Left, Right, Both o Largest. FlipOrientation specchia una forma orizzontalmente o verticalmente senza modificare le coordinate, e le bandiere Shape.AllowOverlap/Shape.BehindText controllano come una forma interagisce con altri contenuti flottanti e con lo strato di testo sottostante.
Righe di firma e linee orizzontali
Altri due tipi di forma specializzati vivono nello stesso modello di disegno. SignatureLine, configurato al momento dell’inserimento tramite SignatureLineOptions (le proprietà includono SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate e SignatureLineOptions.AllowComments), genera il blocco di firma visuale visualizzato nei documenti stampabili ed espone SignatureLine.IsSigned e SignatureLine.IsValid una volta che una firma è stata applicata — ciò è distinto dalla verifica crittografica della firma digitale trattata altrove, che opera su parti firmate del documento anziché sulla forma stessa. HorizontalRuleFormat riguarda la semplice linea divisoria inserita con DocumentBuilder.InsertHorizontalRule(), con le proprietà HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color e HorizontalRuleFormat.Alignment (l’ultima è un valore HorizontalRuleAlignment).
Avvio rapido
Aspose.Words FOSS per .NET è disponibile tramite NuGet:
dotnet add package Aspose.Words.FOSSPer compilare dal codice sorgente invece:
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
Aggiungi un riferimento al progetto Aspose.Words.csproj dalla tua applicazione. Da lì, lavorare con lo strato di disegno segue lo schema usato in tutto questo post: carica o crea un Document, percorri le sue forme con Document.GetChildNodes(NodeType.Shape, true) o inseriscine una nuova con un metodo DocumentBuilder come DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape() o DocumentBuilder.InsertHorizontalRule(), quindi leggi o imposta le proprietà sul Shape restituito — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType e le altre — prima di chiamare Document.Save().
Formati supportati
| Formato | Estensione | Leggi | Scrivi |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (tutte le varianti) | (vari) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Questa edizione esclude intenzionalmente l’impaginazione e il rendering — nessun PDF, XPS o esportazione di immagini, e nessuna stampa — così il Shape.Bounds di una forma e la geometria dipendente dal layout riflettono i valori memorizzati nel documento piuttosto che un layout di pagina calcolato. I convertitori di formato aggiuntivi (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 e WordML) non vengono letti né scritti; questi sono gli stessi sottosistemi rimossi dal codice commerciale per mantenere questa edizione gratuita.
Open Source & Licenze
Aspose.Words FOSS per .NET è rilasciato sotto licenza MIT, gratuito sia per uso commerciale che personale senza royalty o restrizioni di redistribuzione. Il codice sorgente completo è disponibile su GitHub nel Aspose.Words FOSS per .NET repository.
