Un bloc de texte posé sur la page
Composer du texte dans un rectangle choisi, avec sa police, sa taille et sa couleur, et mettre en valeur un mot au milieu d’une phrase.
Le résultat dans un vrai PDF
Les polices contenues dans le fichier
Du texte composé dans une police incorporée au fichier, réduite aux seules lettres employées, et que l’on peut toujours chercher, copier et lire à voix haute.
Ouvrir le PDF Voir l’exemple complet
Également dans les exemples : Des mots qui suivent une courbe · Des prix barrés, une ombre derrière le titre · Un texte qui épouse une forme
Résumé
Comme si le cadre avait été tracé au crayon : vous dites ce qui va dedans, et le texte s’y range tout seul, ligne après ligne, jusqu’au dernier mot. En chemin, un mot peut être mis en valeur — plus grand, en gras, souligné, d’une autre couleur — sans casser la phrase autour de lui. C’est le morceau qui sert partout, du titre d’une facture à la mention en petit en bas de page.
Techniquement
Demandé avec
"type": "text"
Un élément text pose un bloc de texte dans un rectangle donné en points, dans le repère de la page : l’origine est en bas à gauche et l’axe vertical monte. Les fragments entrent dans le flux de contenu de la page entre BT et ET, avec les polices déclarées par la requête. Le contenu est une suite de fragments : une chaîne simple prend le style du bloc, un objet redéfinit pour lui seul la police, la taille, l’interligne, la couleur, les filets (souligné, barré, trait au-dessus) ou le trait qui cerne ses lettres. Un fragment peut aussi demander au serveur l’instant du rendu, mis en forme au format strftime dans le fuseau nommé. Le texte accepte les substituants de pagination, résolus une fois la dernière page connue, ce qui donne un pied de page « page 3 sur 12 » écrit une seule fois pour tout le document.
Schéma de la requête
Clés obligatoires : rect, un objet de quatre coordonnées llx, lly, urx, ury, chacune un nombre ou une expression entre guillemets (+ - * / ( ), variables {page_width}, {page_height}, {current_page}, {total_pages}, {llx}, {lly}, {urx}, {ury}, profondeur maximale 100) ; content, un tableau de passages ; font, une chaîne qui nomme une police déclarée par la requête (standard_fonts, fonts, type1_fonts, type3_fonts, font_chains, font_variants) ; font_size, un nombre de points. Un passage prend trois formes : une simple chaîne ; un objet {"text": …} avec, en option, font, font_size, leading, underline, strikethrough, overline, color et outline, valables pour ce seul passage ; un objet {"date": "strftime pattern"} avec une clé zone facultative (un nom IANA ; en son absence, l’heure est inscrite en temps universel). Clés facultatives du bloc : align (left par défaut, right, center, justify) ; overlong (overflow par défaut : un mot trop large dépasse le bord ; break le coupe) ; leading (1.2 × font_size par défaut) ; break_after, les caractères après lesquels une ligne peut être coupée (par défaut, les coupures tombent aux espaces et aux traits d’union conditionnels) ; break_at_punctuation, booléen, false par défaut, qui permet aussi de couper une ligne là où sa ponctuation l’autorise, après une barre oblique ou un trait d’union à l’intérieur d’un mot ; replacing, objet dont chaque clé est un caractère unique, associée soit à {"each": "…"}, substitué à chaque occurrence du caractère, soit à {"run": "…"}, substitué une seule fois à chaque suite ininterrompue de ce caractère ; le remplacement a lieu avant la coupure des lignes, et une chaîne vide supprime le caractère ; les passages sont lus comme un seul texte : ce qui remplace un caractère prend le style du passage où il se trouve, et une suite de ce caractère qui déborde d’un passage sur le suivant n’est remplacée qu’une fois, dans le style du passage où elle commence ; underline, strikethrough, overline, booléens, false par défaut ; color (noir par défaut) ; outline, un objet composé de width, nombre de points obligatoire, de color (noir par défaut) et de filled (false par défaut) : le contour tracé autour des lettres de tout passage qui n’en indique pas lui-même ; les lettres restent creuses, sauf si filled les remplit aussi ; shadow, un objet dont dx, dy et color sont tous obligatoires ; pages, un tableau d’entiers comptés à partir de 1, vide par défaut, c’est-à-dire toutes les pages ; id, une chaîne à laquelle un autre élément se réfère ; relative_to, un objet composé de id, edge (top ou bottom), offset et d’une clé part facultative (par défaut : la dernière partie posée) ; transform, six nombres ; rotate, un angle en degrés, dans le sens antihoraire, autour du centre du rectangle ; layer, le nom d’un calque déclaré ; clip, un objet avec une clé segments obligatoire et une clé rule (nonzero par défaut, even_odd), la forme à travers laquelle le bloc est vu ; graphics_state, le nom d’un état graphique déclaré, sous lequel le bloc entier, ombre comprise, est dessiné. Combinaisons refusées : transform avec rotate ; un clip aux segments vides. Chacune des clés underline, strikethrough et overline, sur le bloc comme sur un passage, accepte aussi un objet {"position": …, "thickness": …} à la place de true : le trait est alors tracé avec son bord supérieur à ce nombre de points de la ligne de base (en dessous si le nombre est négatif), et avec cette épaisseur. Trois autres clés règlent la disposition des lettres : character_spacing, un nombre de points ajouté à la largeur que la police donne à chaque glyphe, une valeur positive écartant les lettres et une valeur négative les rapprochant ; horizontal_scaling, le pourcentage de cette largeur auquel les glyphes sont dessinés, 80 les ramenant aux quatre cinquièmes et 120 les élargissant d’un cinquième, sans changer leur hauteur ; une valeur nulle ou négative est refusée ; cut_mark, un caractère dessiné en fin de ligne là où "overlong": "break" coupe un mot trop large pour la boîte, sa largeur étant réservée au moment de placer la coupure. Les lignes sont coupées selon les largeurs qui résultent des deux premières. invisible, booléen, false par défaut ; lorsqu’il vaut true, chaque lettre est placée là où elle serait dessinée, sans être peinte, si bien que les mots se sélectionnent, se recherchent et se copient sans jamais être visibles : c’est la couche de texte posée sur l’image d’une page numérisée, quel que soit l’outline indiqué par le bloc. described, lorsque aucun élément de l’arbre de structure ne contient le bloc, un objet composé de expansion, actual_text, alt et lang, ce que le passage dit de lui-même ; il est refusé avec tag ou artifact. Trois autres clés règlent ce qu’un bloc a en commun avec un bloc de texte en flux : last_align, l’alignement de la dernière ligne de chaque paragraphe, par défaut identique à align, mais à gauche avec justify ; first_baseline, la position de la première ligne de base sous le haut du rectangle, qui vaut leading (par défaut), ascender, cap_height ou {"points": …} ; tabs, un objet contenant method, size, ruler, alignments et align_char, qui indique où les tabulations présentes dans les segments placent le point d’écriture ; en l’absence de cette clé, une tabulation est composée comme un blanc. Deux autres clés sont reprises de l’élément flow. leader : les points de conduite répétés dans l’espace qu’ouvre une tabulation et dans la place que laisse libre la dernière ligne d’un paragraphe, soit un caractère composé dans la police, la taille et la couleur du passage voisin, soit l’objet accepté par le leader d’un élément flow ; sans leader, ces espaces restent vides. line_height : le style qui, parmi ceux que traverse une ligne, lui donne sa hauteur, tallest, le plus haut (par défaut), ou first, celui par lequel la ligne commence ; un interlignage indiqué par leading l’emporte sur l’un comme sur l’autre.
Une requête entière qui crée un PDF
{
"standard_fonts": [{"name": "sans", "face": "helvetica"}],
"items": [
{
"type": "text",
"rect": {"llx": 72, "lly": 740, "urx": 523, "ury": 780},
"content": ["Invoice 1964413", {"text": " — paid", "color": [0.1, 0.45, 0.25]}],
"font": "sans",
"font_size": 16,
"outline": {"width": 0.4, "color": [0.1, 0.45, 0.25], "filled": true}
}
]
}
Texte
Du texte en paragraphes, avec retraits et tabulations Un tampon en travers de la page Une ligne de mots posée le long d’un chemin Une rangée de glyphes demandés par leur numéro Des blocs posés les uns sous les autres, page après page
Où aller ensuite
Toutes les clés JSON d’une requête, en une page Les vingt-deux autres choses que l’on peut dessiner