Polices personnalisées

L'objet fonts enregistre les familles de polices personnalisées à partir des fichiers de police téléchargés. Une fois enregistrée, une famille de polices peut être référencée par son nom dans n'importe quelle définition de style en utilisant la propriété fontFamily.

Les polices standard (Helvetica, Times-Roman, Courier) sont toujours disponibles sans enregistrement.

Enregistrement d'une famille de polices

Déclarez les polices au niveau du document avec un nom de famille et des chemins vers chaque variante :

{
  "document": {
    "fonts": {
      "Roboto": {
        "regular": "fonts/Roboto-Regular.ttf",
        "bold": "fonts/Roboto-Bold.ttf",
        "italic": "fonts/Roboto-Italic.ttf",
        "boldItalic": "fonts/Roboto-BoldItalic.ttf"
      }
    },
    "styles": {
      "body": { "fontFamily": "Roboto", "fontSize": 10 }
    },
    "content": [
      { "p": "Ce texte s'affiche en Roboto.", "style": "body" }
    ]
  }
}

Les fichiers de police sont résolus via le système de stockage des actifs — de la même manière que les images sont chargées. Téléchargez les polices via l'API des actifs du locataire avant de les référencer.

Propriétés de la famille de polices

Propriété	Type	Requis	Description
`regular`	string	Oui	Chemin vers le fichier de police de poids normal
`bold`	string	Non	Chemin vers le fichier de police de poids gras
`italic`	string	Non	Chemin vers le fichier de police italique
`boldItalic`	string	Non	Chemin vers le fichier de police gras-italique

Seul regular est requis. Les variantes manquantes se rabattent sur le fichier normal — le texte s'affiche mais sans le poids visuel ou l'inclinaison.

Téléchargement des fichiers de police

Téléchargez les fichiers de police au stockage des actifs de votre locataire :

POST /api/v1/{tenantId}/assets/fonts
Content-Type: multipart/form-data

file: Roboto-Regular.ttf

Formats pris en charge : .ttf (TrueType) et .otf (OpenType). Les polices sont intégrées dans le PDF avec support Unicode complet.

Utilisation dans les styles

Référencez le nom de famille enregistré dans la propriété fontFamily de n'importe quel style :

{
  "fonts": {
    "NotoSerif": {
      "regular": "fonts/NotoSerif-Regular.ttf",
      "bold": "fonts/NotoSerif-Bold.ttf",
      "italic": "fonts/NotoSerif-Italic.ttf",
      "boldItalic": "fonts/NotoSerif-BoldItalic.ttf"
    }
  },
  "styles": {
    "title": { "fontFamily": "NotoSerif", "fontSize": 22, "fontWeight": "bold" },
    "body": { "fontFamily": "NotoSerif", "fontSize": 11 },
    "bodyItalic": { "fontFamily": "NotoSerif", "fontSize": 11, "fontStyle": "italic" },
    "caption": { "fontFamily": "NotoSerif", "fontSize": 8, "fontStyle": "italic" }
  }
}

Les drapeaux de style bold, italic et boldItalic sélectionnent la variante correspondante de la famille enregistrée.

Formatage en ligne

Les Codes courts ([b], [i], [bi]) utilisent automatiquement la variante de police correcte :

{ "p": "Texte normal avec [b]emphase gras[/b] et [i]notes italiques[/i].", "style": "body" }

Si la police du style est NotoSerif, [b] s'affiche avec NotoSerif-Bold.ttf, [i] avec NotoSerif-Italic.ttf, et ainsi de suite.

Mélange de polices personnalisées et standard

Les polices personnalisées et standard coexistent dans le même document. Les styles sans propriété fontFamily utilisent la Helvetica par défaut :

{
  "fonts": {
    "NotoSerif": { "regular": "fonts/NotoSerif-Regular.ttf" }
  },
  "styles": {
    "body": { "fontFamily": "NotoSerif", "fontSize": 11 },
    "footnote": { "fontSize": 8, "color": "#999999" }
  },
  "content": [
    { "p": "Texte du corps en serif.", "style": "body" },
    { "p": "Note de bas de page sans-serif en Helvetica par défaut.", "style": "footnote" }
  ]
}

Familles partielles

Si vous n'avez que le poids normal, enregistrez juste ce fichier :

{
  "fonts": {
    "BrandFont": {
      "regular": "fonts/BrandFont-Regular.ttf"
    }
  }
}

Gras, italique et gras-italique se rabattent tous sur le fichier normal. Le texte s'affiche mais sans différences de poids ou d'inclinaison visuels.

Exemple complet

{
  "document": {
    "metadata": { "title": "Rapport de police personnalisée" },
    "fonts": {
      "NotoSerif": {
        "regular": "fonts/NotoSerif-Regular.ttf",
        "bold": "fonts/NotoSerif-Bold.ttf",
        "italic": "fonts/NotoSerif-Italic.ttf",
        "boldItalic": "fonts/NotoSerif-BoldItalic.ttf"
      }
    },
    "styles": {
      "title": { "fontFamily": "NotoSerif", "fontSize": 20, "fontWeight": "bold" },
      "body": { "fontFamily": "NotoSerif", "fontSize": 11 },
      "caption": { "fontFamily": "NotoSerif", "fontSize": 8, "fontStyle": "italic", "color": "#888888" }
    },
    "content": [
      { "h1": "Rapport trimestriel" },
      { "p": "Ce rapport utilise Noto Serif dans son intégralité pour une apparence traditionnelle et lisible.", "style": "body" },
      { "p": "Les métriques clés sont mises en évidence avec [b]gras[/b] et les notes supplémentaires en [i]italique[/i].", "style": "body" },
      {
        "table": {
          "widths": [3, 1, 1],
          "rows": [
            [{ "p": "Département", "style": "title" }, { "p": "T1", "style": "title" }, { "p": "T2", "style": "title" }],
            [{ "p": "Ingénierie", "style": "body" }, { "p": "$1.2M", "style": "body" }, { "p": "$1.4M", "style": "body" }],
            [{ "p": "Marketing", "style": "body" }, { "p": "$800K", "style": "body" }, { "p": "$950K", "style": "body" }]
          ]
        }
      },
      { "p": "Source : systèmes financiers internes. Les chiffres ne sont pas audités.", "style": "caption" }
    ]
  }
}

Texte multi-script et complexe

Les polices enregistrées sont façonnées au moment du rendu avec HarfBuzz — le même moteur que les navigateurs et LibreOffice utilisent. Les scripts complexes s'affichent correctement directement à partir de JSON, sans rendu côté client :

De droite à gauche — Les lettres arabes, persanes et hébraïques se joignent dans leurs formes initiale/médiale/finale/isolée et s'affichent de droite à gauche automatiquement.
Indic — Les conjonctifs Devanagari (क्ष, श्र), le bengali et le tamoul s'affichent avec la bonne superposition des ligatures et le positionnement des voyelles.
Thaï — Les marques de voyelle et de ton au-dessus/au-dessous se positionnent correctement.
CJK — Le chinois, le japonais et le coréen s'affichent à partir d'une seule famille Noto Sans CJK.
Latin / Cyrillique / Grec — Noto Sans couvre le latin étendu, le cyrillique et le grec aux côtés de la police par défaut.
Symboles géométriques — Noto Sans Symbols 2 couvre les formes géométriques, dingbats et symboles Unicode divers (▲ ▼ ◆ ✓ ★ et le bloc U+2000–U+2FFF complet) sans configuration.
Mathématiques et technique — Noto Sans Math couvre automatiquement les flèches, opérateurs mathématiques et symboles techniques (→ ← ≥ ≤ ≠ ∞ etc.).

Les polices suivantes sont intégrées et appliquées automatiquement sans inscription :

Script / catégorie	Police vendorisée
Arabe, persan	Noto Sans Arabic
Hébreu	Noto Sans Hebrew
Devanagari (hindi, sanskrit)	Noto Sans Devanagari
Bengali	Noto Sans Bengali
Tamoul	Noto Sans Tamil
Thaï	Noto Sans Thai
Chinois, japonais, coréen	Noto Sans CJK SC
Grec, cyrillique (russe, ukrainien, bulgare…), latin étendu	Noto Sans
Symboles géométriques, dingbats (▲ ▼ ◆ ✓ ★, U+2000–U+2FFF)	Noto Sans Symbols 2
Opérateurs mathématiques, flèches (→ ≥ ≤ ≠ ∞)	Noto Sans Math

Deux polices supplémentaires sont vendorisées mais invoquées explicitement plutôt qu'automatiques :

Icônes Font Awesome — accédez aux glyphes via le raccourci [font, Icons]…[/font]
MICR E-13B — appliquée automatiquement aux passages contenant des caractères magnétiques MICR (numéros de routage/compte sur les chèques bancaires)

Pour toutes les polices automatiques, il suffit d'écrire le texte — la détection de script est automatique. Aucune inscription n'est nécessaire, sauf si vous souhaitez une police spécifique.

Lorsque vous enregistrez une police et la référencez via fontFamily dans un style ou le raccourci [font, Family]…[/font], elle prend la priorité sur le repli vendorisé pour ces passages.

La détection de script est désactivée par un fontFamily explicite

Lorsqu'un style définit fontFamily, cette famille est utilisée pour chaque passage du paragraphe — y compris les scripts qu'elle ne peut pas afficher. Si vous mélangez des scripts dans un tel paragraphe, enregistrez les familles supplémentaires et changez-en explicitement avec [font, Family]…[/font] :

{
  "fonts": {
    "Serif":  { "regular": "fonts/NotoSerif-Regular.ttf" },
    "Arabic": { "regular": "fonts/NotoSansArabic-Regular.ttf", "bold": "fonts/NotoSansArabic-Bold.ttf" }
  },
  "styles": {
    "feat": { "fontFamily": "Serif", "fontSize": 13 }
  },
  "content": [
    { "p": "Déposé par [font, Serif]$data.counsel.name[/font] · [font, Arabic]صالح عالميا[/font]", "style": "feat" }
  ]
}

Les paragraphes dont le style n'a pas de fontFamily bénéficient toujours de la détection automatique de script — aucune balise inline n'est nécessaire.

Intégration et sous-ensemble

Les polices s'intègrent automatiquement, et les grandes polices restent bon marché : un fichier Noto Sans CJK fait ~16 MB sur disque, mais seuls les glyphes réellement utilisés sont intégrés — un document utilisant une poignée de caractères CJK ajoute quelques kilo-octets, pas des mégaoctets. Les scripts qui dépendent de substitution contextuelle (arabe, Indic, thaï, hébreu) sont intégrés dans leur intégralité afin que chaque glyphe façonné soit conservé.

Voir en action

Le tutoriel Proclamation multilingue affiche 25 langues sur 8 systèmes d'écriture dans un seul document — sceau multi-script, changement de police en ligne, sauts de page et cinq symbologies de code-barres — entièrement à partir de JSON déclaratif.

Le Guide de dispositif multilingue prend le cas plus difficile : prose de sécurité complète **en chinois, japonais, coréen, hindi et thaï — conjonctifs Devanagari et empilage de tonalité thaï dans des phrases courantes, pas seulement des étiquettes — avec la famille CJK complète livrée par sous-ensemble.

Polices spéciales et de fantaisie

Au-delà des polices de texte, les familles enregistrées peuvent être des polices spécialisées ou de fantaisie — traitées de manière identique (enregistrez, puis référencez par fontFamily ou changez en ligne avec [font, Family]) :

Blackletter — mastheads de diplôme et de certificat, titres ornementaux.
Script de signature — noms signés à la main sur les lettres, les prix et les approbations.
Écriture manuscrite — annotations des réviseurs, appels informels, notes de marge.
Monospace — listes de code, sommes de contrôle, figures alignées en colonnes.
OCR-B — zone lisible à la machine (MRZ) de passeport et champs de formulaire OCR.
MICR E-13B — la bande d'encre magnétique de routage/compte/chèque sur les chèques bancaires.

Le tutoriel Spécimen de type montre chacun de ceux-ci dans un contexte réaliste, tous intégrés directement à partir de JSON.

Notes

Les fichiers de police sont intégrés au PDF généré. Les destinataires n'ont pas besoin d'avoir les polices installées.
Les polices sont chargées une fois par génération de document et mises en cache pour la durée du rendu.
Si un fichier de police est manquant ou illisible, la famille est ignorée et les styles la référençant se rabattent sur Helvetica.
Les noms des familles de polices ne sont pas sensibles à la casse : "NotoSerif" et "notoserif" se résolvent à la même famille.

Enregistrement d'une famille de polices​

Propriétés de la famille de polices​

Téléchargement des fichiers de police​

Utilisation dans les styles​

Formatage en ligne​

Mélange de polices personnalisées et standard​

Familles partielles​

Exemple complet​

Texte multi-script et complexe​

Intégration et sous-ensemble​

Voir en action​

Polices spéciales et de fantaisie​

Notes​