Введение
Aspose.Words FOSS для .NET включает ту же объектную модель форматирования текста, что и коммерческий движок Aspose.Words: Font для атрибутов уровня запуска, ParagraphFormat для атрибутов уровня абзаца, ListFormat для нумерованных и маркированных списков, FrameFormat для позиционных текстовых фреймов и Range.Replace для поиска-замены. Это руководство рассматривает именно этот уровень — форматирование и переписывание текста, уже существующего в документе, — а не построение структуры документа с нуля (см. вводный пост для обзора релиза).
Библиотека имеет MIT-лицензию, не требует нативных зависимостей и ориентирована на .NET Standard 2.0, поэтому работает на .NET Framework 4.6.2+ и .NET 6, 8 и 10. Установите её через NuGet или соберите из исходного кода (см. Быстрый старт ниже). Всё описанное здесь работает с .docx, .docm, .dotx, .dotm и файлами Flat OPC, загруженными через new Document(fileName), либо с документами, построенными в памяти с помощью DocumentBuilder.
Поскольку Aspose.Words FOSS для .NET представляет собой подлинную кодовую базу Aspose.Words, сокращённую до бесплатного ядра, а не переписанную, объектная модель Font, ParagraphFormat, ListFormat и FrameFormat напрямую переносится в коммерческий Aspose.Words для .NET, если проект позже потребует макетирование страниц, рендеринг или дополнительные конвертеры форматов, которые исключены в этом издании.
Ключевые возможности
Форматирование уровня запуска с шрифтом
Каждый Run раскрывает свойство Font, а DocumentBuilder.Font задаёт шрифт, который будет применён к следующему записанному тексту. Помимо очевидных Bold, Italic и Underline (перечисление Underline со значениями, включая Single, Double, Dotted, Dash, Wavy и их варианты *Heavy), Font охватывает StrikeThrough, DoubleStrikeThrough, Superscript, Subscript, SmallCaps, AllCaps, Hidden, Shadow, Outline, Emboss, Engrave, Color, HighlightColor, Spacing, Position, Kerning, Scaling и EmphasisMark. Font.Style, Font.StyleName и Font.StyleIdentifier связывают пробег с символьным стилем, а Font.ClearFormatting() сбрасывает прямое форматирование пробега к значениям стиля по умолчанию. DocumentBuilder также напрямую предоставляет Bold, Italic и Underline в виде быстрых клавиш, плюс PushFont() и PopFont() для сохранения и восстановления текущего состояния шрифта построителя вокруг временного изменения форматирования.
Форматирование абзаца с ParagraphFormat
ParagraphFormat (доступный через Paragraph.ParagraphFormat или DocumentBuilder.ParagraphFormat) управляет выравниванием через перечисление ParagraphAlignment (Left, Center, Right, Justify, Distributed, плюс варианты с арабским кашидой и тайским распределением), отступом через LeftIndent, RightIndent и FirstLineIndent (с эквивалентами CharacterUnit* для восточноазиатских макетов), и интервалом через SpaceBefore, SpaceAfter и LineSpacingRule/LineSpacing. Поведение пагинации регулируется с помощью KeepTogether, KeepWithNext, PageBreakBefore и WidowControl, а Bidi помечает абзац как написанный справа налево. Пользовательские табуляции находятся в ParagraphFormat.TabStops, TabStopCollection из TabStop объектов, каждый имеет Position, TabAlignment (Left, Center, Right, Decimal, Bar) и TabLeader (None, Dots, Dashes, Line, Heavy, MiddleDot). Как и в случае с Font, ParagraphFormat.Style и StyleName связывают абзац с именованным Style, а ClearFormatting() очищает прямое форматирование абзаца.
Списки с ListFormat
ListFormat (на Paragraph.ListFormat или DocumentBuilder.ListFormat) применяет форматирование списка к абзацу: ApplyBulletDefault() и ApplyNumberDefault() переключают его в стандартный маркированный или нумерованный список, RemoveNumbers() полностью удаляет форматирование списка, а ListIndent()/ListOutdent() перемещают его между уровнями списка. ListFormat.List возвращает базовое определение List, а ListFormat.ListLevel возвращает ListLevel, действующее для данного абзаца, которое содержит настройки для каждого уровня, такие как NumberStyle, NumberFormat, Alignment (ListLevelAlignment из Left, Center или Right), StartAt, RestartAfterLevel, специфичный для уровня Font, и TrailingCharacter (ListTrailingCharacter из Tab, Space или Nothing) управляющие зазором между меткой списка и текстом абзаца. Новые определения списков создаются через ListCollection.Add(listTemplate) с использованием одного из встроенных предустановок ListTemplate (BulletDefault, NumberArabicDot, NumberUppercaseRomanDot и аналогичных), или AddSingleLevelList для одноуровневого списка; списки документа перечисляются через Document.Lists.
Текстовые рамки с FrameFormat
Paragraph.FrameFormat является объектом только для чтения, предоставляющим отчёт: каждое свойство в нём отражает параграфа текущий состояние кадра, а не позволяя устанавливать его напрямую. IsFrame сообщает, является ли параграф в данный момент кадром; Width, Height, и HeightRule сообщает его размер; HorizontalPosition и VerticalPosition, вместе с RelativeHorizontalPosition и RelativeVerticalPosition, сообщите, где он привязан относительно страницы, поля, колонки или абзаца; и HorizontalDistanceFromText/VerticalDistanceFromText сообщите о зазоре между рамкой и окружающим основным текстом. HorizontalAlignment и VerticalAlignment сообщите, как содержимое выравнивается внутри рамки.
Поиск и замена с диапазоном и IReplacingCallback
Range.Replace — доступен в Document.Range для обработки всего документа, или в Range любого узла — имеет перегрузки для простой пары шаблон/замена и для пары шаблон/замена, объединённой с экземпляром FindReplaceOptions, поддерживая сопоставление на основе регулярных выражений. FindReplaceOptions.MatchCase и FindWholeWordsOnly уточняют, что считается совпадением; Direction (FindReplaceDirection.Forward или Backward) задаёт порядок сканирования; ApplyFont и ApplyParagraphFormat позволяют передавать форматирование заменяемому тексту; а набор флагов Ignore* (IgnoreDeleted, IgnoreInserted, IgnoreFields, IgnoreFieldCodes, IgnoreFootnotes, IgnoreStructuredDocumentTags, IgnoreShapes, IgnoreOfficeMath) исключает определённые категории контента из совпадения. Для логики замены, которую нельзя выразить фиксированной строкой, реализуйте IReplacingCallback.Replacing(args) и установите её как FindReplaceOptions.ReplacingCallback (или передайте её в один из конструкторов FindReplaceOptions, принимающих обратный вызов напрямую); параметр args представляет собой ReplacingArgs, раскрывающий Match, MatchNode, MatchOffset и настраиваемую строку Replacement, чтобы обратный вызов мог вычислять значение для каждого совпадения. Связанный перечисление ReplaceAction (Replace, Skip, Stop) описывает возможные результаты для отдельного совпадения во время операции.
Быстрый старт
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. Чтобы форматировать текст по мере его написания, установите свойства DocumentBuilder.Font (Bold, Italic, Underline), свойства DocumentBuilder.ParagraphFormat (Alignment, отступы, интервал), и DocumentBuilder.ListFormat (ApplyBulletDefault(), ApplyNumberDefault()) перед вызовом Write(), Writeln() или InsertParagraph() — билдер применяет текущее состояние форматирования ко всему записанному, пока вы не измените его снова, либо оберните временное изменение в PushFont()/PopFont(). Чтобы переоформить или переписать текст, уже находящийся в документе, откройте его с помощью new Document(fileName) и вызовите Range.Replace() на doc.Range — либо простую перегрузку pattern/replacement, либо перегрузку, принимающую FindReplaceOptions с MatchCase, FindWholeWordsOnly или пользовательским IReplacingCallback — затем Save() результат.
Поддерживаемые форматы
| Формат | Расширение | Чтение | Запись |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (все варианты) | (различные) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Классы форматирования выше применяются одинаково независимо от того, из какого из этих форматов загружен документ или в какой формат сохраняется. Эта версия не поддерживает DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 или WordML для чтения или записи, а также не поддерживает PDF, XPS или экспорт изображений, поскольку макет страниц и рендеринг находятся за пределами её области.
Открытый исходный код и лицензирование
Aspose.Words FOSS для .NET выпускается под лицензией MIT, свободно для коммерческого и личного использования без роялти и ограничений на распространение. Полный исходный код, включая реализации Font, ParagraphFormat, ListFormat, FrameFormat и Range, описанные выше, доступен на GitHub в Aspose.Words FOSS для .NET репозитории.
