Введение
Документы 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, семейство типов выноски и соединителя, 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 репозитории.
