Вступ
Документи 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, що описують, який тип об’єкта містить даний екземпляр. Перерахування ShapeType перераховує конкретні типи форм, які розпізнає Word — Rectangle, Ellipse, Line, Arrow, сімейство типів callout і connector, 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 дорівнює true, і 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 | ✓ | ✓ |
| Flat 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.
