מבוא
מסמכי Word מציבים תמונות, תיבות טקסט ואובייקטים חופשיים אחרים בשכבת ציור שנמצאת בנפרד מהזרם הרגיל של פסקאות וטבלאות. Aspose.Words FOSS עבור .NET חושף את שכבת הציור דרך המחלקות Shape ו-ShapeBase, ומספק גישה תוכניתית לאותו מודל AutoShape, תמונה, תיבת טקסט, ואובייקט OLE שבו Word משתמש פנימית. מדריך זה מראה כיצד הספרייה מייצגת ומנהלת את אובייקטי הציור האלה — מיקום, עיצוב מילוי וקו מתאר, תמונות משובצות, וטקסט המוצג בתוך צורה — במסמכי DOCX, DOCM, DOTX, ו-DOTM.
זה שימושי עבור קוד שבונה תבניות דיווח או נייר מכתבים עם לוגו או גרפיקה ממוקמים, יוצר מסמכים עם תיבות טקסט צפות והסברים, או בודק צורות שכבר קיימות במסמך שהועלה — חילוץ הבייטים של תמונה משובצת, קריאת שם החותם של שורת חתימה, או שינוי מיקום של תמונה קיימת.
Aspose.Words FOSS עבור .NET משוחרר תחת רישיון MIT ומיועד ל-.NET Standard 2.0, ולכן הוא פועל על .NET Framework 4.6.2+ ועל .NET 6, 8, ו-10 ללא תלותיות מקומיות. התקינו אותו דרך NuGet, או בנו אותו ממקור (ראו התחלה מהירה למטה). זהו אותו מנוע מסמכים Aspose.Words המשמש באופן מסחרי, לא שכתוב מחדש או עטיפה, ולכן המחלקות Shape ושכבת הציור המתוארות כאן הן API של הייצור.
תכונות מרכזיות
מודל האובייקט Shape ו-ShapeBase
כל AutoShape, תיבת טקסט, תמונה משובצת, אובייקט OLE, או פקד ActiveX שמעוגן במסמך Word מיוצג על ידי המחלקה Shape — סגורה, ונבנית על המחלקה הבסיסית האבסטרקטית ShapeBase. שתיהן חולקות את אותה משטח מיקום ועיצוב: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation ו-Shape.ZOrder עבור גאומטריה, בנוסף לדגלים Shape.IsGroup, Shape.IsImage, Shape.IsWordArt ו-Shape.IsInline המתארים את סוג האובייקט שהאינסטנס מכילה. ה-enum ShapeType מונה את סוגי הצורות הקונקרטיים ש-Word מכיר — Rectangle, Ellipse, Line, Arrow, משפחה של סוגי קריאות וקונקטורים, TextBox, Image, ו-OleObject מבין יותר משמונים ערכים — כך שקוד העובר על הצורות במסמך יכול להתפצל על פי Shape.ShapeType כדי להחליט כיצד לטפל בכל אחת. ניתן לשלב כמה צורות לתוך GroupShape יחיד, שהוא עצמו תת-מחלקה של ShapeBase, השומרת על קבוצה של צורות ממוקמות ומשוכתבות יחד; DocumentBuilder.InsertGroupShape(shapes) בונה אחת ממערך קיים של צורות.
תיבות טקסט ו-WordArt
כל Shape יכול לשאת טקסט משלו דרך המחלקה TextBox, המוצגת כ-Shape.TextBox. תכונות TextBox שולטות באופן שבו הטקסט נמצא בתוך הצורה: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop ו-TextBox.InternalMarginBottom למרווח פנימי, TextBox.FitShapeToText כדי לאפשר לצורה לגדול עם התוכן שלה, LayoutFlow לכיוון הטקסט, TextBoxWrapMode לאופן שבו הטקסט מעוגל בתוך התיבה, ו-TextBox.VerticalAnchor — ערך TextBoxAnchor כגון Top, Middle, BottomCentered או TopBaseline — ליישור אנכי. תיבות טקסט מקושרות, שבהן טקסט שעולה מעבר ממשיך לתיבה שנייה, מודליות באמצעות TextBox.Next ו-TextBox.Previous. מחלקה קשורה אך נפרדת, TextPath, מגדירה טקסט בסגנון WordArt העוקב אחרי קו המתאר של הצורה במקום לשבת בתוכה, עם תכונות כגון TextPath.Text, TextPath.FontFamily, TextPath.Bold ו-TextPath.RotateLetters, בנוסף למניין TextPathAlignment עם ערכים כגון Stretch, Center ו-LetterJustify.
תמונות ותמונות מוטמעות
כאשר צורה מכילה תמונה, Shape.HasImage הוא אמת ו-Shape.ImageData מחזיר אובייקט ImageData. ImageData חושף את הבייטים הגולמיים דרך ImageData.ImageBytes, את הפורמט שהתגלה דרך ImageType (ערכים כולל Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps, ו-WebP), ממדי פיקסלים ורזולוציה דרך ImageSize, וחתך באמצעות ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft ו-ImageData.CropRight. התאמות צבע — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel ו-ImageData.ChromaKey — הן תכונות באותו האובייקט, ו-ImageData.IsLink/ImageData.IsLinkOnly מבחינים בין תמונה משובצת לזו שמפנה רק לנתיב קובץ חיצוני. ל-DocumentBuilder.InsertImage() יש עומסים שמקבלים תמונה, נתיב קובץ, מערך בייטים או זרם, כולל גרסאות שמגדירות גם רוחב, גובה, מיקום אופקי ואנכי, ו-WrapType בזמן ההכנסה.
מילוי, קו ואפקטים של צורה
כל Shape ו-GroupShape נושאים אובייקט Fill ואובייקט Stroke עבור הפנים והקצה שלהם. Fill תומך בשישה סוגי מילוי דרך FillType, עם ערכים כולל Solid, Patterned, Gradient, Textured, Background ו-Picture, שנקבעים באמצעות שיטות כגון Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) או Fill.SetImage(fileName). Stroke שולט בקצה: Stroke.Weight, DashStyle, JoinStyle, EndCap ו-Stroke.LineStyle (ערך ShapeLineStyle) מכסים את הקו עצמו, בעוד Stroke.StartArrowType ו-Stroke.EndArrowType, משויכים למנויים ArrowWidth ו-ArrowLength, מגדירים ראשי חץ על צורות מקשר וקו. מעבר למילוי וקו, Shape חושף ארבעה אובייקטים נוספים של אפקט — ShadowFormat, ReflectionFormat, GlowFormat ו-SoftEdgeFormat — שכל אחד נושא צבע ושקיפות משלו עבור האפקט החזותי הרלוונטי.
מיקום ועיטוף טקסט
צורות הצפות יחסית לדף או לפסקה משתמשות ב-RelativeHorizontalPosition וב-RelativeVerticalPosition כדי לעגון את עצמן — לשוליים, לדף או לעמוד, למשל — יחד עם RelativeHorizontalSize ו-RelativeVerticalSize לעיגון גודל, ועוד HorizontalAlignment ו-VerticalAlignment למיקום פשוט שמאל/מרכז/ימין או עליון/אמצעי/תחתון. האופן שבו הטקסט סביב מגיב לצורה נשלט על ידי WrapType, עם ערכים כולל Inline, Square, Tight, TopBottom ו-None; עבור עיטוף Square ו-Tight, WrapSide מצמצם זאת עוד ל-Left, Right, Both או Largest. FlipOrientation משקף צורה אופקית או אנכית מבלי לשנות את הקואורדינטות שלה, והדגלים Shape.AllowOverlap/Shape.BehindText שולטנים איך הצורה מתקשרת עם תוכן צף אחר ועם שכבת הטקסט מתחתיה.
קווי חתימה וקווים אופקיים
שני סוגי צורה מתמחים נוספים קיימים באותו מודל ציור. SignatureLine, המוגדר בזמן ההוספה דרך SignatureLineOptions (המאפיינים כוללים את SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate ו-SignatureLineOptions.AllowComments), מציג את בלוק החתימה החזותית שנראה במסמכים שניתנים להדפסה וחושף את SignatureLine.IsSigned ו-SignatureLine.IsValid לאחר שהחתימה יושמה עליו — זה שונה מאימות החתימה הדיגיטלית הקריפטוגרפית שמכוסה במקום אחר, הפועל עם חלקי מסמך חתומים ולא עם הצורה עצמה. HorizontalRuleFormat מתאר את קו ההפרדה הפשוט המוכנס עם DocumentBuilder.InsertHorizontalRule(), עם המאפיינים HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color ו-HorizontalRuleFormat.Alignment (האחרון הוא ערך HorizontalRuleAlignment).
התחלה מהירה
Aspose.Words FOSS עבור .NET זמין דרך NuGet:
dotnet add package Aspose.Words.FOSSלבנות מהמקור במקום זאת:
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
הוסף הפנייה לפרויקט ל-Aspose.Words.csproj מהיישום שלך. משם, עבודה עם שכבת הציור פועלת לפי הדפוס המשמש לאורך כל הפוסט הזה: טען או צור Document, עבור על הצורות שלו באמצעות Document.GetChildNodes(NodeType.Shape, true) או הוסף חדשה באמצעות שיטת DocumentBuilder כגון DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape() או DocumentBuilder.InsertHorizontalRule(), ואז קרא או הגדר מאפיינים על Shape שהוחזר — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType ועוד — לפני קריאה ל-Document.Save().
פורמטים נתמכים
| פורמט | סיומת | קריאה | כתיבה |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| OPC שטוח (כל הווריאנטים) | (שונות) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
הגרסה הזו מודעת משייכת בכוונה את פריסת העמוד והעיבוד — ללא PDF, XPS, או ייצוא תמונה, וללא הדפסה — ולכן Shape.Bounds של הצורה וגאומטריה תלויה בפריסה משקפת את הערכים השמורים במסמך במקום פריסת עמוד מחושבת. ממירי הפורמט הנוספים (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, ו-WordML) אינם נקראים או נכתבים; אלה הם אותם תתי-מערכות שהוסרו מהקוד המסחרי כדי לשמור על גרסה זו חינמית.
קוד פתוח ורישוי
Aspose.Words FOSS עבור .NET משוחרר תחת רישיון MIT, חינמי לשימוש מסחרי ואישי ללא תמלוגים או מגבלות הפצה. הקוד המלא זמין ב-GitHub ב-Aspose.Words FOSS עבור .NET repository.
