Un bloc de texte posé sur la page

Écrire 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.

Demandé avec "type": "text"

En mots de tous les jours

Écrit pour tout le monde. Il dit ce que cela pose sur une feuille de papier, et ne vous demande rien de plus.

Vous choisissez un cadre sur la feuille, comme si vous traciez un rectangle au crayon, et vous dites ce qui doit y être écrit. Vous donnez l'écriture, sa taille et sa couleur, et le texte se range tout seul à l'intérieur, ligne après ligne. Au milieu d'une phrase, un mot peut prendre une écriture à lui : plus grand, en gras, souligné ou d'une autre couleur. C'est le morceau qui sert partout, du titre d'une facture à la mention en petit en bas de page.

Pour un développeur

Écrit pour celui qui écrit le programme appelant : le modèle, les unités, et les réglages qui portent le poids.

Un article 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. 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 ou les filets (souligné, barré, surligné). 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, ce qui donne un pied de page « page 3 sur 12 » écrit une seule fois pour tout le document.

Chaque clé, avec son défaut

La référence : quelles clés sont obligatoires, lesquelles sont facultatives, ce que vaut chacune par défaut et quelles combinaisons le serveur décline.

Clés obligatoires : rect, objet à 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, tableau de fragments ; font, chaîne, nom d'une police déclarée par la requête (standard_fonts, fonts, type1_fonts, type3_fonts, font_chains, font_variants) ; font_size, nombre de points. Un fragment prend trois formes : une chaîne nue ; un objet {"text": …} avec font, font_size, leading, underline, strikethrough, overline, color facultatifs, chacun valant pour ce fragment seul ; un objet {"date": "strftime pattern"} avec zone facultatif (nom IANA, sinon le fuseau de la machine de rendu). Clés facultatives du bloc : align (left par défaut, right, center, justify) ; overlong (overflow par défaut, le mot trop large continue au-delà du bord ; break le coupe) ; leading (défaut 1,2 × font_size) ; break_after, chaîne des caractères après lesquels une coupure est permise (par défaut la coupure a lieu aux espaces et aux tirets conditionnels) ; underline, strikethrough, overline, booléens à false ; color (défaut noir) ; shadow, objet à dx, dy et color tous trois obligatoires ; pages, tableau d'entiers en base 1, défaut vide, c'est-à-dire toutes les pages ; id, chaîne à laquelle un autre article se réfère ; relative_to, objet id, edge (top ou bottom), offset, part facultatif (défaut : la dernière partie posée) ; transform, six nombres ; rotate, degrés dans le sens trigonométrique autour du centre de la boîte ; layer, nom d'un calque déclaré. Refus croisé : transform et rotate ensemble.

Une requête entière qui le dessine

Envoyez ceci tel quel et un PDF revient. Rien n'en a été retiré.

{
  "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
    }
  ]
}

La ligne qui l'envoie, en trois langages

Texte

Du texte en paragraphes, avec retraits et tabulations Un tampon en travers de la page

Où aller ensuite

Chaque clé d'une requête, en une page Les vingt autres choses que l'on peut dessiner

Voir les prix Voir les exemples

Glossaire

police: Le dessin de chaque lettre, de chaque chiffre et de chaque signe qu'un document écrit, rangé dans un fichier à part. Un PDF emporte à l'intérieur de lui-même les polices dans lesquelles il est composé : c'est pour cela qu'il s'ouvre à l'identique sur une machine qui ne les a jamais eues. Sans elles, un lecteur en met une autre à la place, et la mise en page bouge.
requête: Un appel au service : vous envoyez ce que le document doit dire, et vous recevez le document. Votre facture compte ces appels, un par document. Le nombre de pages d'un document n'est jamais compté.
serveur: Une machine qui attend des appels et y répond, jour et nuit, sans personne devant elle. Celle qui dessine les documents ici porte le moteur et rend les pages finies ; celle où tourne votre site est une autre machine qui fait le même genre de travail.
calque: Un groupe nommé de choses dessinées sur une page, que le lecteur peut afficher ou masquer, comme un calque posé sur un plan. Un plan peut garder ses cotes sur l'un et ses notes sur l'autre, et un calque peut être réglé pour s'afficher à l'écran et rester hors de l'impression.

Tous les mots que le site explique