Модифікації сторінки XPS на основі подій | .NET

Що таке подійний підхід у програмуванні?

Подійний підхід у програмуванні — це парадигма, яка обертається навколо концепції подій і обробки подій. У цій моделі потік програми визначається подіями, якими можуть бути дії користувача (наприклад, клацання мишею або натискання клавіш), сповіщення, створені системою, або повідомлення від інших програм. Ось деякі ключові аспекти подійного підходу:

• Події: події представляють важливі події в програмі. Це можуть бути взаємодії користувача, зміни в даних або повідомлення з інших частин системи. Наприклад, натискання кнопки або завантаження файлу можуть викликати події.

• Слухачі подій: щоб реагувати на події, програмісти використовують прослуховувачі подій (або обробники). Це функції або методи, які визначено для виконання, коли відбувається певна подія. Наприклад, слухач подій може бути налаштований на виконання функції, коли користувач натискає кнопку.

• Асинхронне виконання: модель, заснована на подіях, часто підтримує асинхронне програмування, що дозволяє програмам залишатися чуйними в очікуванні подій. Наприклад, веб-програма може продовжувати працювати, очікуючи даних із сервера.

• Відокремлення: підхід на основі подій сприяє відокремленню між різними частинами програми. Компоненти можуть спілкуватися за допомогою подій без необхідності знати подробиці реалізації один одного, що робить код більш модульним і простішим в обслуговуванні.

• Поширені випадки використання: програмування, кероване подіями, широко використовується в графічних інтерфейсах користувача (GUI), веб-додатках і системах, які потребують взаємодії в реальному часі. Фреймворки та бібліотеки, такі як Node.js, React та багато інших, використовують шаблони, керовані подіями.

• Керування станом: у системі, керованій подіями, керування станом може бути вирішальним, оскільки програма може перебувати в різних станах залежно від взаємодії користувача або подій. Належні стратегії керування станом часто застосовуються, щоб гарантувати, що програма поводиться належним чином.

Загалом, підхід, заснований на подіях, є потужним способом керування взаємодіями та робочими процесами в програмі, що робить його особливо ефективним для додатків, які вимагають швидкого реагування та взаємодії з користувачем.

Події, які відбуваються під час перетворення документа XPS

Коли вам потрібно внести зміни до певної сторінки документа XPS за допомогою API Aspose.Page, ви зазвичай вибираєте активний документ (якщо у файлі XPS кілька документів), вибираєте активну сторінку, а потім вносите зміни самостійно .

Тепер припустімо, що вам потрібно внести повторювані зміни до всіх сторінок у файлі XPS, а потім перетворити результат у формат PDF або зображення. Деякі приклади таких змін включають розміщення водяного знака на сторінках або додавання навігаційних гіперпосилань. Безпосередній спосіб внесення таких змін передбачає перегляд документів у пакеті XPS, перегляд сторінок у поточному активному документі та, нарешті, застосування змін. Тому код для виконання цього завдання виглядатиме так:

for (int i = 1; i <= document.DocumentCount; i++)
{
    document.SelectActiveDocument(i);
    for (j = 1; j <= document.PageCount; j++)
    {
        document.SelectActivePage(j);
        // Your changes ...
    }
}
document.SaveAsPdf("file-name.pdf", saveOptions);

Якщо вам також потрібно внести деякі нерегулярні зміни перед тими, що повторюються, цей підхід може призвести до певної плутанини або надмірного обходу документів і сторінок, не кажучи вже про те, що ці цикли можуть здаватися трохи громіздкими. Коли ви перетворюєте документ XPS у формат PDF або зображення, процес відбувається сторінка за сторінкою. Коли завдання перетворення готове до обробки наступної сторінки, воно запускає подію «до сторінки». Користувач може визначити обробку таких подій, розширивши клас BeforePageSavingEventHandler, таким чином скориставшись деякими перевагами, викладеними у вступному розділі цієї статті.

Приклад додавання навігаційних гіперпосилань

Тут ми наведемо приклад, пов’язаний із випадком навігаційних гіперпосилань. І щоб зробити завдання трохи складнішим, ми перетворимо лише підмножину всіх сторінок у PDF, як зазначено у властивості PdfSaveOptions.PageNumbers.

Клас обробника подій

Нижче наведено розширення класу BeforePageSavingEventHandler:

/// <summary>
/// The class to handle the before-page event while converting an XPS document.
/// </summary>
public class NavigationInjector : BeforePageSavingEventHandler
{
    // The font in which navigation hyperlinks and page numbers will be displayed.
    private readonly XpsFont _font;
    // The page numbers to convert.
    private readonly SortedList<int, int> _pageNumbers;

    public NavigationInjector(XpsFont font, int[] pageNumbers)
    {
        _font = font;
        if (pageNumbers == null)
            return;

        // Turn the page number array into a sorted collection of unique values.
        _pageNumbers = new SortedList<int, int>();
        foreach (int pn in pageNumbers)
            _pageNumbers[pn] = 0;
    }

    public override void Handle(BeforeSavingEventArgs<PageAPI> args)
    {
        PageAPI api = args.ElementAPI;

        XpsGlyphs glyphs;
        // For all pages in the output PDF except the first one...
        if (args.OutputPageNumber > 1)
        {
            // ...insert a hyperlink to the first page...
            glyphs = api.CreateGlyphs(_font, 15f, 5f, api.Height - 10f, "[First]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(_pageNumbers == null ? 1 : _pageNumbers.Keys[0]);
            api.Add(glyphs);

            // ...and to the previous page.
            glyphs = api.CreateGlyphs(_font, 15f, 60f, api.Height - 10f, "[Prev]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(
                _pageNumbers == null ? args.AbsolutePageNumber - 1 : _pageNumbers.Keys[args.OutputPageNumber - 2]);
            api.Add(glyphs);
        }

        // For all pages in the output PDF except the last one...
        if ((_pageNumbers != null && args.OutputPageNumber < _pageNumbers.Count) ||
            (_pageNumbers == null && args.OutputPageNumber < api.TotalPageCount))
        {
            // ...insert a hyperlink to the next page...
            glyphs = api.CreateGlyphs(_font, 15f, 110f, api.Height - 10f, "[Next]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(
                _pageNumbers == null ? args.AbsolutePageNumber + 1 : _pageNumbers.Keys[args.OutputPageNumber]);
            api.Add(glyphs);

            // ...and to the last page.
            glyphs = api.CreateGlyphs(_font, 15f, 160f, api.Height - 10f, "[Last]");
            glyphs.Fill = api.CreateSolidColorBrush(Color.Blue);
            glyphs.HyperlinkTarget = new XpsPageLinkTarget(
                _pageNumbers == null ? api.TotalPageCount : _pageNumbers.Keys[_pageNumbers.Keys.Count - 1]);
            api.Add(glyphs);
        }

        // Insert a page number in the bottom-right corner.
        glyphs = api.CreateGlyphs(_font, 15f, api.Width - 20f, api.Height - 10f, args.OutputPageNumber.ToString());
        glyphs.Fill = api.CreateSolidColorBrush(Color.Black);
        api.Add(glyphs);

        // Add an outline entry to display the links to the converted pages in the navigation pane of a PDF viewer.
        api.AddOutlineEntry(string.Format("Page {0}", args.OutputPageNumber), 1, args.AbsolutePageNumber);
    }
}

Клас обробника повинен знати про сторінки, які ми хочемо зберегти як PDF, щоб створити правильні цільові гіперпосилання. Таким чином, конструктор повинен приймати властивість масиву опцій як аргумент. Якщо вказано масив номерів сторінок, ми створюємо їх відсортовану колекцію, водночас уникаючи дублікатів. (До речі, це рішення не зовсім точне. Чи можете ви зрозуміти, що може спричинити неузгодженість у виводі?) Нам також знадобиться об’єкт XpsFont, який містить дані шрифту для тексту гіперпосилання.

Все це відбувається в перевизначеному методі Handle(). Аргумент методу — це об’єкт, який містить API модифікації для поточної сторінки, номер документа в пакеті XPS, абсолютний номер сторінки в усіх документах, відносний номер сторінки в поточному документі (який дорівнює попередній номер, якщо в пакеті лише один документ), і номер вихідної сторінки (який дорівнює абсолютному номеру сторінки, коли ми конвертуємо весь пакет).

Логіка наступних двох блоків if досить проста. Він базується на аналізі аргументу події OutputPageNumber, щоб опустити деякі посилання, де це доречно: посилання [First] і [Prev] буде додано до всіх сторінок виводу, крім першої, тоді як Посилання [Далі] та [Останнє] відображатимуться на всіх сторінках, крім останньої. Логіка також адаптована для обох випадків, незалежно від того, чи вказано номери сторінок чи ні.

Після блоків if у нижньому правому куті сторінки є код для додавання номера сторінки.

Останній рядок додає структурний запис сторінки, елемент, який відображатиметься на панелі навігації програми перегляду PDF (якщо підтримується).

Код перетворення

Тепер, коли визначено обробник події «до сторінки», ми можемо написати код, який перетворює документ:

// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_WorkingWithPages();
// Open an XPS document
using (XpsDocument doc = new XpsDocument(dataDir + "Sample3.xps"))
// Create a font
using (Stream fontStream = File.OpenRead(dataDir + "arialbd.ttf"))
{
    // Create options for conversion to PDF
    PdfSaveOptions options = new PdfSaveOptions();
    // Set the filter for the pages that need conversion
    options.PageNumbers = new int[] { 2, 6, 7, 13 };
    // Add the event handler that will execute right before the conversion of each page
    options.BeforePageSavingEventHandlers.Add(new NavigationInjector(doc.CreateFont(fontStream), options.PageNumbers));
    // Save resultant XPS document
    doc.SaveAsPdf(dataDir + "ModifyPageOnConversion_out.pdf", options);
}

Ми відкриваємо файл XPS, а потім створюємо об’єкт потоку з файлом даних шрифту. Далі ми створюємо екземпляр класу PdfSaveOptions і вказуємо кількість сторінок, які потрібно конвертувати. У наступному рядку обробник події «до сторінки» «підключається» до завдання перетворення за допомогою параметра колекції «BeforePageSavingEventHandlers».

Все, що залишилося зробити, це запустити перетворення в PDF за допомогою методу SaveAsPdf() документа.

Висновок

У цій статті ми дослідили ключові моменти подієвого підходу в програмуванні, розглянули прямий метод зміни сторінок документа XPS і навчилися більш досконалої та витонченої техніки для внесення повторюваних змін до всіх вихідних сторінок під час процес перетворення, використовуючи вставку навігаційних гіперпосилань як приклад.

Щоб отримати повні приклади, перегляньте наш Приклад проекту.