Giới thiệu
Các tài liệu Word đặt hình ảnh, hộp văn bản và các đối tượng tự do khác vào một lớp vẽ nằm riêng biệt so với luồng thông thường của các đoạn văn và bảng. Aspose.Words FOSS cho .NET mở rộng lớp vẽ này thông qua các lớp Shape và ShapeBase, cung cấp quyền truy cập lập trình vào cùng một mô hình AutoShape, hình ảnh, hộp văn bản và đối tượng OLE mà Word tự sử dụng nội bộ. Hướng dẫn này cho thấy cách thư viện biểu diễn và thao tác các đối tượng vẽ — vị trí, định dạng tô và viền, hình ảnh nhúng, và văn bản được bố trí bên trong một hình dạng — trên các tài liệu DOCX, DOCM, DOTX và DOTM.
Điều này hữu ích cho mã xây dựng các mẫu báo cáo hoặc tiêu đề thư có logo hoặc đồ họa được định vị, tạo tài liệu với các hộp văn bản và chú thích nổi, hoặc kiểm tra các hình dạng đã có trong tài liệu đã tải lên — trích xuất byte của hình ảnh nhúng, đọc tên người ký trên dòng chữ ký, hoặc thay đổi vị trí của hình ảnh hiện có.
Aspose.Words FOSS cho .NET được phát hành dưới giấy phép MIT và nhắm tới .NET Standard 2.0, vì vậy nó chạy trên .NET Framework 4.6.2+ và .NET 6, 8, và 10 mà không có phụ thuộc gốc. Cài đặt nó qua NuGet, hoặc xây dựng từ mã nguồn (xem Bắt Đầu Nhanh bên dưới). Đây là cùng một động cơ tài liệu Aspose.Words được sử dụng thương mại, không phải một bản viết lại hay một lớp bao, vì vậy các lớp Shape và lớp lớp vẽ được mô tả ở đây là API sản xuất.
Các tính năng chính
Mô hình Đối tượng Hình dạng và ShapeBase
Mỗi AutoShape, hộp văn bản, hình ảnh nhúng, đối tượng OLE, hoặc điều khiển ActiveX được neo trong một tài liệu Word đều được biểu diễn bởi lớp Shape — sealed, và được xây dựng trên lớp cơ sở trừu tượng ShapeBase. Cả hai chia sẻ cùng một bề mặt vị trí và định dạng: Shape.Left, Shape.Top, Shape.Width, Shape.Height, Shape.Rotation, và Shape.ZOrder cho hình học, cộng với các cờ Shape.IsGroup, Shape.IsImage, Shape.IsWordArt, và Shape.IsInline mô tả loại đối tượng mà một thể hiện cụ thể chứa. Enum ShapeType liệt kê các loại hình dạng cụ thể mà Word nhận ra — Rectangle, Ellipse, Line, Arrow, một họ các loại callout và connector, TextBox, Image, và OleObject trong hơn tám mươi giá trị — vì vậy mã duyệt các hình dạng của tài liệu có thể nhánh dựa trên Shape.ShapeType để quyết định cách xử lý mỗi hình. Nhiều hình dạng có thể được kết hợp thành một GroupShape duy nhất, tự nó là một lớp con ShapeBase, giữ một tập hợp các hình dạng được định vị và thay đổi kích thước cùng nhau; DocumentBuilder.InsertGroupShape(shapes) tạo một từ một mảng hình dạng hiện có.
Hộp Văn bản và WordArt
Bất kỳ Shape nào có thể mang văn bản riêng của nó thông qua lớp TextBox, được hiển thị dưới dạng Shape.TextBox. Các thuộc tính TextBox kiểm soát cách văn bản đó nằm bên trong hình: TextBox.InternalMarginLeft, TextBox.InternalMarginRight, TextBox.InternalMarginTop và TextBox.InternalMarginBottom cho khoảng đệm, TextBox.FitShapeToText để cho phép hình tăng kích thước cùng nội dung, LayoutFlow cho hướng văn bản, TextBoxWrapMode cho cách văn bản cuộn bên trong hộp, và TextBox.VerticalAnchor — một giá trị TextBoxAnchor như Top, Middle, BottomCentered hoặc TopBaseline — cho căn chỉnh dọc. Các hộp văn bản liên kết, nơi văn bản tràn tiếp tục vào hộp thứ hai, được mô hình hoá bằng TextBox.Next và TextBox.Previous. Một lớp liên quan nhưng riêng biệt, TextPath, định nghĩa văn bản kiểu WordArt theo đường viền của hình thay vì nằm bên trong, với các thuộc tính như TextPath.Text, TextPath.FontFamily, TextPath.Bold và TextPath.RotateLetters, cộng với một enum TextPathAlignment có các giá trị như Stretch, Center và LetterJustify.
Hình ảnh và Ảnh Nhúng
Khi một hình chứa một ảnh, Shape.HasImage là true và Shape.ImageData trả về một đối tượng ImageData. ImageData cung cấp các byte thô qua ImageData.ImageBytes, định dạng được phát hiện qua ImageType (các giá trị bao gồm Jpeg, Png, Bmp, Gif, Emf, Wmf, Pict, Eps và WebP), kích thước pixel và độ phân giải qua ImageSize, và cắt ảnh qua ImageData.CropTop, ImageData.CropBottom, ImageData.CropLeft và ImageData.CropRight. Các điều chỉnh màu — ImageData.Brightness, ImageData.Contrast, ImageData.GrayScale, ImageData.BiLevel và ImageData.ChromaKey — là các thuộc tính trên cùng một đối tượng, và ImageData.IsLink/ImageData.IsLinkOnly phân biệt ảnh nhúng với ảnh chỉ tham chiếu tới đường dẫn tệp bên ngoài. DocumentBuilder.InsertImage() có các overload cho phép nhận một ảnh, một đường dẫn tệp, một mảng byte, hoặc một stream, bao gồm các biến thể cũng đặt chiều rộng, chiều cao, vị trí ngang và dọc một cách rõ ràng, và WrapType tại thời điểm chèn.
Đổ màu, Đường viền và Hiệu ứng Hình dạng
Mỗi Shape và GroupShape đều chứa một đối tượng Fill và một đối tượng Stroke cho phần bên trong và viền. Fill hỗ trợ sáu loại đổ màu thông qua FillType, với các giá trị bao gồm Solid, Patterned, Gradient, Textured, Background và Picture, được thiết lập bằng các phương thức như Fill.Solid(color), Fill.OneColorGradient(style, variant, degree), Fill.TwoColorGradient(color1, color2, style, variant), Fill.Patterned(patternType) hoặc Fill.SetImage(fileName). Stroke điều khiển viền: Stroke.Weight, DashStyle, JoinStyle, EndCap và Stroke.LineStyle (một giá trị ShapeLineStyle) bao phủ đường nét, trong khi Stroke.StartArrowType và Stroke.EndArrowType, kết hợp với các enum ArrowWidth và ArrowLength, cấu hình đầu mũi tên trên các hình kết nối và đường thẳng. Ngoài đổ màu và viền, Shape cung cấp bốn đối tượng hiệu ứng bổ sung — ShadowFormat, ReflectionFormat, GlowFormat và SoftEdgeFormat — mỗi đối tượng mang màu và thuộc tính độ trong suốt riêng cho hiệu ứng trực quan tương ứng.
Định vị và Bao quanh Văn bản
Các hình dạng trôi nổi so với trang hoặc đoạn văn sử dụng RelativeHorizontalPosition và RelativeVerticalPosition để neo mình — ví dụ vào lề, trang hoặc cột — kết hợp với RelativeHorizontalSize và RelativeVerticalSize để neo kích thước, cộng thêm HorizontalAlignment và VerticalAlignment cho việc đặt đơn giản trái/giữa/phải hoặc trên/giữa/dưới. Cách văn bản xung quanh phản hồi với một hình dạng được điều khiển bởi WrapType, với các giá trị bao gồm Inline, Square, Tight, TopBottom và None; đối với bao quanh Square và Tight, WrapSide thu hẹp hơn nữa thành Left, Right, Both hoặc Largest. FlipOrientation phản chiếu một hình dạng theo chiều ngang hoặc chiều dọc mà không thay đổi tọa độ của nó, và các cờ Shape.AllowOverlap/Shape.BehindText kiểm soát cách một hình dạng tương tác với nội dung trôi nổi khác và lớp văn bản phía dưới.
Dòng Chữ Ký và Đường Ngang
Hai loại hình dạng chuyên biệt khác tồn tại trong cùng mô hình vẽ. SignatureLine, được cấu hình tại thời điểm chèn qua SignatureLineOptions (các thuộc tính bao gồm SignatureLineOptions.Signer, SignatureLineOptions.SignerTitle, SignatureLineOptions.Email, SignatureLineOptions.Instructions, SignatureLineOptions.ShowDate và SignatureLineOptions.AllowComments), hiển thị khối chữ ký trực quan xuất hiện trong tài liệu có thể in và cung cấp SignatureLine.IsSigned và SignatureLine.IsValid sau khi một chữ ký đã được áp dụng — điều này khác với việc xác thực chữ ký số mật mã được đề cập ở nơi khác, vốn làm việc với các phần tài liệu đã ký thay vì với chính hình dạng. HorizontalRuleFormat bao gồm đường ngăn cách đơn giản được chèn bằng DocumentBuilder.InsertHorizontalRule(), với các thuộc tính HorizontalRuleFormat.WidthPercent, HorizontalRuleFormat.Height, HorizontalRuleFormat.NoShade, HorizontalRuleFormat.Color và HorizontalRuleFormat.Alignment (cuối cùng là một giá trị HorizontalRuleAlignment).
Bắt Đầu Nhanh
Aspose.Words FOSS cho .NET có sẵn qua NuGet:
dotnet add package Aspose.Words.FOSSĐể biên dịch từ mã nguồn thay thế:
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
Thêm một tham chiếu dự án tới Aspose.Words.csproj từ ứng dụng của bạn. Từ đó, làm việc với lớp vẽ tuân theo mẫu được sử dụng xuyên suốt bài viết này: tải hoặc tạo một Document, duyệt các hình dạng của nó bằng Document.GetChildNodes(NodeType.Shape, true) hoặc chèn một hình mới bằng phương thức DocumentBuilder như DocumentBuilder.InsertImage(), DocumentBuilder.InsertGroupShape(), hoặc DocumentBuilder.InsertHorizontalRule(), sau đó đọc hoặc đặt các thuộc tính trên Shape trả về — Shape.ImageData, Shape.TextBox, Shape.Fill, Shape.Stroke, Shape.WrapType, và các thuộc tính còn lại — trước khi gọi Document.Save().
Định Dạng Được Hỗ Trợ
| Định dạng | Phần mở rộng | Đọc | Ghi |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (tất cả các biến thể) | (đa dạng) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Phiên bản này cố ý loại bỏ bố cục trang và việc hiển thị — không có PDF, XPS, hoặc xuất ảnh, và không có in — vì vậy Shape.Bounds của hình dạng và hình học phụ thuộc vào bố cục phản ánh các giá trị được lưu trong tài liệu thay vì một bố cục trang được tính toán. Các bộ chuyển đổi định dạng bổ sung (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3, và WordML) không được đọc hoặc ghi; chúng là các hệ thống con đã bị loại bỏ khỏi mã nguồn thương mại để giữ phiên bản này miễn phí.
Mã nguồn mở & Giấy phép
Aspose.Words FOSS cho .NET được phát hành dưới giấy phép MIT, miễn phí cho cả sử dụng thương mại và cá nhân mà không có phí bản quyền hoặc hạn chế phân phối lại. Mã nguồn đầy đủ có sẵn trên GitHub trong Aspose.Words FOSS cho kho .NET.
