Aller au contenu

Impression et export (Pro)

Un calendrier finit sur du papier, dans un tableur, ou dans l’application d’agenda de quelqu’un d’autre. Le Pro (@dzcalendar/pro) sait faire les trois sans aucune dépendance : il imprime de vraies feuilles, écrit un PDF, des images PNG, une feuille Excel, un fichier CSV et un fichier iCalendar, et chacun garde le fuseau horaire de chaque événement ainsi que la vraie durée d’un jour de changement d’heure. L’impression et les exports sont deux entrées à part, @dzcalendar/pro/print et @dzcalendar/pro/export : importez-les là où ils servent (ou avec import()), et le reste de l’application ne les embarque pas. Les paquets des frameworks, plus bas, les chargent d’eux-mêmes à la première utilisation.

Sans le Pro, l’impression du navigateur fonctionne déjà, avec un bémol : un calendrier ne dessine pas ce qui est hors de l’écran et cache les jours chargés derrière « +N ». Demandez-lui de tout dessiner d’abord, puis de remettre les choses en place :

const restore = calendar.preparePrint();
window.print();
restore();

Avec autoPrint à true à la création du calendrier, il le fait seul autour des événements beforeprint et afterprint du navigateur : la commande Imprimer (Ctrl+P) suffit. Ce qui sort est le calendrier tel qu’il est à l’écran, sans les boutons de la barre d’outils et avec ce qui défile imprimé en entier, dans la page telle que le navigateur la met en forme.

Avec @dzcalendar/theme, les couleurs s’impriment comme à l’écran (le thème demande au navigateur de ne pas éclaircir les fonds). Les règles du calendrier sont dans des couches de cascade : une règle d’impression de votre page hors couche l’emporte sur elles ; voyez cssLayers quand ce n’est pas le cas.

Quand le calendrier doit sortir en vraies feuilles, une semaine par feuille, utilisez printPages :

import { printPages } from '@dzcalendar/pro/print';
const job = await printPages(calendar); // la période affichée, A4 en paysage

Elle construit, hors de l’écran, une copie du calendrier pour chaque période de la vue (un jour, une semaine, un mois), ajustée à la feuille, avec le titre de la période en haut et « 1 / 3 » en pied ; puis elle appelle window.print(). Les copies partagent le magasin du calendrier : rien n’est chargé de nouveau. Elles gardent son apparence et ses options, mais aucun de ses gestionnaires, ni son animation, ni son menu contextuel. Le papier est toujours clair, quel que soit le thème à l’écran.

Ce que montrent les feuilles :

  • Une grille horaire voit ses heures étirées pour remplir la hauteur de la feuille.
  • Un mois voit ses semaines étirées aussi, chaque jour montrant autant d’événements qu’il a de place (un lien « +N » au-delà, comme à l’écran).
  • Une liste s’étend sur autant de feuilles qu’il faut, en portrait par défaut.
  • Une frise voit ses créneaux étirés sur la largeur. Une frise de ressources est répartie entre les feuilles par ressources de premier niveau entières (un parent reste avec ses enfants) ; rowsPerPage fixe le nombre de lignes d’une feuille.
  • Une vue multi-mois s’imprime à raison d’un mois par feuille.
  • Il n’y a pas de ligne « maintenant » sur le papier.

Le navigateur dessine le texte : tous les alphabets s’impriment, et « Enregistrer au format PDF » dans la boîte d’impression le garde sélectionnable. Il n’existe qu’une impression à la fois par document : rappeler printPages, ou détruire le calendrier, ferme la première. Les feuilles sont retirées d’elles-mêmes après l’impression.

Pour construire les feuilles sans les imprimer (les vérifier dans un test, ou imprimer plus tard vous-même), demandez print: false : la tâche d’impression les tient dans job.pages, hors de l’écran, avec ses problems, et rien ne les retire avant votre appel à job.close().

L’impression et les exports en images (PDF et PNG) prennent les mêmes options :

import { Temporal } from '@dzcalendar/core';
import { printPages } from '@dzcalendar/pro/print';
await printPages(calendar, {
view: 'dayGridMonth',
from: Temporal.PlainDate.from('2026-10-01'),
to: Temporal.PlainDate.from('2026-12-01'), // exclue : octobre et novembre
paper: 'letter',
orientation: 'portrait',
});
Option Effet
view La vue à mettre sur papier ; celle qui est affichée par défaut. Ce n’est pas forcément celle de l’écran : imprimez le mois depuis une vue en semaine
from, to [from, to), des dates dans le fuseau du calendrier ; par défaut une période de la vue autour de la date affichée (from seul : une période à partir de lui)
paper 'a4' (par défaut), 'letter' ou 'a3'
orientation 'landscape' (paysage), ou 'portrait' pour une liste, par défaut

printPages en prend trois de plus : rowsPerPage (plus haut), print (plus bas) et messages (voir Les mots des fichiers).

Les dates sont découpées selon les périodes propres à la vue : trois mois d’une vue mensuelle font trois feuilles. Au plus 60 périodes sortent, et un export PDF ou PNG s’arrête à 300 feuilles ; au-delà, un avertissement cut:60 ou cut:300 le dit.

Chaque export prend le calendrier et rend un fichier en mémoire, un Blob (exportPNG : une liste, blobs), avec les problèmes rencontrés en chemin :

Fonction Fichier Sur
exportPDF PDF, une feuille par page une vue et ses dates, comme l’impression
exportPNG images PNG, une par feuille une vue et ses dates, comme l’impression
exportXLSX feuille Excel une plage de dates
exportCSV CSV, séparé par virgule, point-virgule ou tabulation une plage de dates
exportICS iCalendar (.ics) une plage de dates, ou tout

Les trois qui listent des événements prennent aussi from et to ([from, to), des dates dans le fuseau du calendrier) et reprennent par défaut ce que la vue montre. Ils chargent d’abord la plage, par vos sources, et une plage qui n’a pu être chargée est un avertissement : le fichier est fait sans elle, et les problems du résultat le disent.

import { exportCSV, exportXLSX } from '@dzcalendar/pro/export';
const { blob, problems } = await exportXLSX(calendar, { from, to });
const csv = await exportCSV(calendar, { separator: ';' }); // un Excel français

Les deux écrivent le même tableau, une ligne par occurrence, dans l’ordre des débuts : un événement récurrent est déroulé en ses occurrences, chacune une fois ; les événements d’arrière-plan sont laissés de côté. Les colonnes sont le titre ; le début et son fuseau ; la fin et son propre fuseau ; le début et la fin dans le timeZone du calendrier ; la durée en minutes ; la journée entière ; les ressources par leur titre ; le statut.

C’est ainsi que les fuseaux survivent à un tableur, qui n’en a pas :

  • Le début est écrit dans le fuseau de l’événement, avec ce fuseau à côté. La fin a le sien : un vol Paris-Tokyo se termine à 07:00 en Asia/Tokyo.
  • Les mêmes instants sont écrits de nouveau dans le fuseau du calendrier, pour qui veut une seule horloge.
  • La durée est le temps réellement écoulé : de 00:00 à 06:00 la nuit où les pendules reculent, elle dit 420 minutes, pas 360.
  • Un événement sur la journée a des dates, ni fuseau ni durée ; sa fin est le lendemain de son dernier jour (exclue), comme dans le calendrier.

Dans le XLSX, les dates sont de vraies dates Excel (ce que dit la cellule est ce que disait l’horloge de ce fuseau), la ligne d’en-tête est figée et filtrée, et la feuille se lit de droite à gauche quand le calendrier se lit ainsi (arabe, hébreu). Excel ne connaît aucune date avant 1900 : une telle heure est écrite en texte. Le CSV écrit les heures 2026-10-25 06:00 et les dates 2026-10-25, en UTF-8 avec une marque d’ordre des octets et des fins de ligne CRLF, qu’Excel ouvre correctement ; une cellule qui commence par =, +, - ou @ est écrite comme du texte, pour qu’un tableur ne l’exécute jamais comme une formule.

import { exportPDF, exportPNG } from '@dzcalendar/pro/export';
const { blob } = await exportPDF(calendar, { from, to, paper: 'a4', title: 'Octobre' });
const { blobs } = await exportPNG(calendar, { scale: 2 }); // une image par feuille

Contrairement à l’impression, ces exports dessinent la vue sur un canevas à partir du modèle du calendrier, sans boîte d’impression : une grille horaire avec ses ressources, un mois, une liste sur autant de feuilles qu’il faut (l’en-tête d’un jour répété sur chacune), une frise dont les en-têtes sont répétés. Un jour de 23 ou 25 heures est dessiné tel qu’il est : l’heure répétée est hachurée, et un jour de frise fait 25 heures de large. Un calendrier de droite à gauche est dessiné de droite à gauche. Le fuseau du calendrier est écrit dans le coin supérieur de chaque feuille, à côté du titre de la période.

Deux choses à savoir. Le PDF contient les feuilles sous forme d’images (un JPEG par page) : son texte n’est pas sélectionnable (pour un texte sélectionnable, passez par l’impression et « Enregistrer au format PDF »), et le fichier grossit avec chaque feuille et avec scale. Et les couleurs sont celles de la palette claire, quel que soit le thème à l’écran.

scale est le nombre de pixels de l’appareil par pixel CSS, 2 par défaut (192 ppp), jusqu’à 4. title nomme le PDF ; par défaut c’est la période.

import { exportICS } from '@dzcalendar/pro/export';
const { blob } = await exportICS(calendar, { from, to, name: 'Cabinet' });
const everything = await exportICS(calendar, { all: true });

Un fichier .ics garde ce qu’un tableur aplatit. Un événement est écrit tel qu’il est : son début et sa fin chacun dans son fuseau (TZID), avec un VTIMEZONE pour chaque fuseau, tiré des vrais changements d’heure du fuseau, afin que toute application d’agenda le place au bon instant ; un événement en UTC est écrit en UTC. Une série récurrente est écrite entière, une seule fois, quelle que soit celle de ses occurrences que la plage montre : sa règle (RRULE), ses dates exclues et ajoutées (EXDATE, RDATE), et chaque occurrence déplacée ou modifiée, en événement du même UID avec un RECURRENCE-ID (voir Récurrence). Un événement sur la journée est une date, sans fuseau.

Par défaut le fichier contient ce que la plage montre, événements d’arrière-plan compris — marqués transparents (TRANSP:TRANSPARENT), ils n’occupent donc l’agenda de personne là où le fichier est importé ; all: true écrit tout ce que le calendrier a chargé. name devient le nom du calendrier dans le fichier (X-WR-CALNAME). C’est le format à donner à une autre application d’agenda ; pour lire un flux en entrée, voyez Sources d’événements.

Les en-têtes de colonnes, les statuts et « 1 / 3 » existent en anglais, en français, en arabe, en espagnol et en allemand, choisis par la locale du calendrier ; toute autre langue retombe sur l’anglais. Changez n’importe lequel avec messages, qui ne prend que les mots à remplacer, ou ajoutez une langue entière avec defineExportLocale :

await exportCSV(calendar, { messages: { title: 'Intitulé', allDay: 'Toute la journée' } });

« Journée entière » et « Aucun événement » suivent les messages du calendrier. Plus sur les langues dans Langues.

Un Blob n’est pas encore un téléchargement. download en enregistre un par le navigateur :

import { download, exportXLSX } from '@dzcalendar/pro/export';
const { blob } = await exportXLSX(calendar);
if (blob) download(blob, 'agenda.xlsx');

Ou faites et enregistrez en un seul appel avec downloadExport(calendar, kind, filename, options), où kind vaut 'pdf', 'png', 'xlsx', 'csv' ou 'ics'. Il rend les problèmes rencontrés, et n’est jamais rejeté : sans erreur parmi eux, le fichier a été enregistré. Un export PNG de plusieurs feuilles est enregistré en une seule archive, agenda.zip, qui contient agenda-1.png, agenda-2.png…

Les paquets Pro des frameworks font la même chose par le calendrier qu’ils tiennent, et chargent l’impression et les exports à la première utilisation. Créez le contrôleur du calendrier, donnez-le au calendrier, et appelez les exports depuis vos propres boutons :

import { createCalendar } from '@dzcalendar/dom';
import { downloadExport } from '@dzcalendar/pro/export';
import { printPages } from '@dzcalendar/pro/print';
const calendar = createCalendar(element, { timeZone: 'Europe/Paris', initialView: 'timeGridWeek' });
document.getElementById('print')!.addEventListener('click', () => void printPages(calendar));
document.getElementById('csv')!.addEventListener('click', async () => {
const problems = await downloadExport(calendar, 'csv', 'agenda.csv', { separator: ';' });
if (problems.length > 0) console.warn(problems);
});

En Angular, DzExport accepte le controller du composant (comme ci-dessus), le <dz-calendar> lui-même, ou le calendrier de @dzcalendar/dom. Les mêmes exports, pdf, png, xlsx, csv, ics et print, sont des méthodes de exports en React et en Vue, et de DzExport en Angular (avec le calendrier en premier argument).

Une entrée incorrecte ne lève jamais d’exception. Un résultat porte des problems, chacun avec le code invalid-export, un path (ce qui n’allait pas) et un court detail. Une erreur signifie pas de fichier (blob: null, aucun blobs, aucune feuille) : une vue inconnue, ou dont la famille n’est pas chargée ; un from ou un to qui n’est pas un Temporal.PlainDate, ou une plage qui finit avant de commencer ; un papier qui n’est ni a4, ni letter, ni a3 ; un séparateur qui n’est ni ,, ni ;, ni la tabulation ; dans un framework, un calendrier pas encore monté (not-attached).

Un avertissement signifie que le fichier a été fait malgré tout : une supposition (un scale, une orientation ou un rowsPerPage invalide, remplacé par sa valeur par défaut), une plage de dates qui n’a pu être chargée (sources), une coupe au-delà de 60 périodes ou de 300 feuilles, ou, à l’impression, une feuille qui n’a pu tout contenir (clipped:2, le nombre étant la feuille).