Перейти до основного вмісту

Фірмовий бланк і логотип

Форма друку з рамкою Letterhead показує блок компанії над своїм заголовком: назву, реквізити, контакти та логотип. Жодна форма друку сама не тримає цих даних. Конфігурація постачає їх один раз, з констант компанії, і кожна форма з фірмовою рамкою читає їх станом на дату документа.

Є три частини: точка розширення провайдера рамки в рушії, провайдер конфігурації, який її заповнює, і константи компанії, які він читає. Редагує їх користувач через обробник даних CompanySettings.

Використовуйте вбудовану навичку

create-print-form (у .claude/skills/ вашого репозиторію) охоплює ту саму тематику для нової конфігурації. Використовуйте create-constant і create-data-processor, коли додаєте або змінюєте самі константи компанії.

Що показує фірмовий бланк​

ЧастинаДжерелоПриклад
Назва, жирнимКонстанта CompanyNameТОВ «Нутріша»
Рядок реквізитівCompanyTaxCode і CompanyVatNumber, з'єднані середньою крапкоюкод ЄДРПОУ 32123155
Рядок контактівCompanyAddress, CompanyPhone і CompanyWebsite, з'єднані середньою крапкою01001, м. Київ, вул. Хрещатик, 22, оф. 5 · +380 44 123 45 67 · nutrisha.example.ua
ЛоготипКонстанта CompanyLogo, посилання на завантажене зображенняЛоготип, якщо його встановлено

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

Проведена видаткова накладна: фірмовий бланк компанії з назвою, реквізитами й контактами стоїть над заголовком

Звідки він береться​

Рушій володіє лише точкою розширення. IPrintFrameProvider повертає фірмовий бланк, чинний на дату, або null:

public interface IPrintFrameProvider
{
    ValueTask<PrintLetterhead?> GetLetterheadAsync(DateTime asOf, CancellationToken cancellationToken);
}

Типовий провайдер рушія повертає null, тобто бланка не малюється, тож Kandra.Printing працює автономно. Конфігурація реєструє власний провайдер один раз, після реєстрацій рушія:

services.AddScoped<IPrintFrameProvider, WmsPrintFrameProvider>();   // остання реєстрація перемагає

WmsPrintFrameProvider еталонної конфігурації читає константи компанії станом на дату документа і повертає PrintLetterhead(назва, рядок реквізитів, рядок контактів, байти логотипа):

  • Логотип кешується за посиланням на blob. Вміст посилання ніколи не змінюється, бо новий логотип — це нове посилання. Тож кеш не потребує скидання.
  • Відсутній або нечитабельний логотип означає відсутність логотипа і запис у журнал. Друк ніколи не падає через оформлення.

RenderAsync отримує бланк через цей провайдер. Синхронний Render цього не робить, тож форма з фірмовою рамкою, відрендерена через Render, вийде без блоку компанії. Див. Форми друку документів.

Датовані константи: повторний друк показує те, що було чинним тоді​

Реквізити компанії — це константи, а в константи є історія. Кожне значення діє з певної дати. Кожен читач запитує значення станом на дату документа, а не станом на сьогодні. Тож:

  • Повторний друк старого рахунку показує назву, реквізити й логотип, які компанія мала в той день.
  • Зміна компанії не переписує вже надруковані документи.

Саме тому старі логотипи лишаються прикріпленими. Значення CompanyLogo — це посилання на blob. Старіше датоване значення все ще вказує на свій blob, тож повторний друк старішого документа знаходить свій логотип. Видалення цього blob втратило б логотип на кожному документі, датованому, поки він був чинним. Опис константи це прямо каже: blob має лишатися прикріпленим.

Редагування компанії: обробник даних CompanySettings​

Редагуйте компанію через обробник даних CompanySettings, а не сторінку констант. Це форма над константами компанії, яка читається як документ з одним записом:

  • Новий заповнює кожне поле значеннями, чинними зараз. EffectiveFrom за замовчуванням дорівнює сьогодні.
  • Виконати записує лише ті значення, що відрізняються від чинних на дату набрання чинності. Кожна змінена величина стає новим датованим значенням відповідної константи. Незмінені зберігають свою історію.
  • EffectiveFrom може бути майбутньою датою, щоб запланувати зміну, або минулою, щоб виправити документи, датовані відтоді. Константи читаються станом на дату документа, тож виправлення діє на ці документи.
  • Логотип — це PNG або JPEG розміром не більше 1 МБ. Обробник завантажує його, зберігає всі попередні логотипи прикріпленими та записує константу CompanyLogo з новим посиланням.

Обробник записує константи, які читає друк:

КонстантаДрукується як
CompanyNameНазва у фірмовому бланку й назва сторони-компанії
CompanyTaxCode, CompanyVatNumberРядок реквізитів і коди сторони-компанії
CompanyAddress, CompanyPhone, CompanyWebsiteРядок контактів, адреса й телефон сторони-компанії
CompanyLogoЛоготип у фірмовому бланку
CompanyBankAccountБанківські реквізити сторони-компанії: її IBAN, банк і МФО. Константа зберігає код обраного банківського рахунку. Порожнє значення не друкує банківського рядка.
HomeCurrency, VatRateВалюта сум і ПДВ, який показують документи

Назва й реквізити сторони-компанії присутні на сторінці двічі: раз у фірмовому бланку і раз як сторона-постачальник. Так і задумано. Бланк — це блок рамки. Сторона — це власний запис документа про те, хто постачальник.

Перевизначення теми друку​

Вигляд кожного PDF задає один об'єкт, PrintTheme: шкала шрифтів, кольори, товщина ліній і внутрішні відступи клітинок. Типові значення — це розміри еталонної накладної. Конфігурація перевизначає будь-яке з них під час реєстрації:

services.AddKandraPrinting(theme =>
{
    theme.Ink = "#000000";
    theme.TableHeaderFill = "#E8EEF4";
    theme.BodySize = 10;
});

Кольори — це рядки "#RRGGBB". Розміри та товщини — у пунктах. Шкала шрифтів: TitleSize, BodySize, SecondarySize і FooterSize. Кольори: Ink, Muted, Rule і TableHeaderFill.

AddKandraApplication() уже викликає AddKandraPrinting() без зворотного виклику. Щоб перевизначити тему, викличте AddKandraPrinting ще раз із зворотним викликом після AddKandraApplication(). Остання реєстрація перемагає. Еталонна конфігурація сьогодні тему не перевизначає, тож її PDF використовують типові значення рушія.

Застереження​

  • Провайдер є частиною конфігурації, і його відсутність непомітна. Типовий провайдер рушія не друкує бланка, і жодна помилка не виникає. Якщо ваші форми з фірмовою рамкою не мають блоку компанії, перевірте, що провайдер зареєстровано після AddKandraPrinting() рушія.
  • Не розміщуйте назву компанії, код платника податків чи логотип у формі. Єдині дані компанії у формі — це сторона-постачальник, і вона береться з тих самих констант.
  • Повторний друк правильний лише настільки, наскільки правильні його датовані значення. Константа з неправильним EffectiveFrom показує неправильні реквізити на документах, датованих між ними. Установлюйте дату на день, коли зміна справді діє.
  • Не редагуйте константу CompanyLogo вручну. Її значення — це посилання на blob, а сторінка констант показує його як сирий JSON. Використовуйте CompanySettings, який тримає попередні логотипи прикріпленими.

Дивіться також​