Options de rendu

Conventions des exemples de cette page

Pour ne pas répéter la même amorce partout, les exemples qui suivent supposent ce décor. Chaque bloc ne montre donc que ce qu'il démontre.

import { loadReqIfPackage, ReqIfIndex } from "reqif-preview";

// Les octets de votre fichier .reqif ou .reqifz.
// Voir [Démarrage](/fr/guide/demarrage) pour les obtenir depuis un <input type="file">,
// depuis Node ou depuis une URL.
declare const bytes: Uint8Array;

const pkg = await loadReqIfPackage(bytes);
const doc = pkg.document; // le premier document du paquet

// pkg.documents, pas pkg.document : c'est ce qui résout les relations qui
// traversent la frontière entre deux .reqif d'un même .reqifz.
const index = new ReqIfIndex(pkg.documents);

const spec = doc.coreContent.specifications[0];
const obj = index.specObjects.get(spec.children[0].objectRef)!;

`RenderOptions`

Le même objet est accepté par renderPackageToHtml, renderDocumentToHtml et renderSpecification. Toutes les propriétés sont facultatives.

Présentation

Option	Type	Défaut	Effet
`includeCss`	`boolean`	`true`	Inclut la feuille de style par défaut dans un `<style>` en tête de la sortie. Si `false`, chargez-la via `reqif-preview/style.css` ou l'export `DEFAULT_CSS` — voir Feuille de style.
`layout`	`"stacked" \| "tabs"`	`"stacked"`	Onglets CSS entre documents et entre spécifications. Sans effet s'il n'y en a qu'un. Détails
`readingMode`	`boolean`	`false`	Vue de lecture : masque ID, créé/modifié et panneau technique ; titres en `<h3>`…`<h6>`.
`chapterNumbers`	`boolean`	`false`	Préfixe les titres de `1`, `1.1`, `1.1.1`… en repartant à 1 par `Specification`.
`chapterNumberAttributes`	`string[]`	—	Ne numérote que les nœuds portant l'un de ces attributs. Sans effet sans `chapterNumbers`.
`labels`	`Partial<RenderLabels>`	anglais	Remplace les libellés d'interface.
`dateLocale`	`string`	`"en-GB"`	Locale de formatage des dates créé/modifié.

Contenu

Option	Type	Défaut	Effet
`contentAttributes`	`string[]`	—	Liste blanche stricte des attributs formant le contenu principal, dans cet ordre. Détails
`titleAttributes`	`string[]`	—	Attributs essayés comme titre en dernier recours, après les `LONG-NAME`.
`showTechnicalByDefault`	`boolean`	`false`	Ouvre le panneau « Détails techniques » d'entrée.
`hideEmptyAttributes`	`boolean`	`true`	Omet du panneau technique les attributs sans aucune valeur.
`preferSimplifiedXhtml`	`boolean`	`false`	Affiche la version simplifiée plutôt que l'original. Détails
`showRelations`	`boolean`	`true`	Affiche les liens entrants/sortants. Visible aussi en `readingMode`.
`customAttributeRenderers`	`CustomAttributeRenderer[]`	—	Injecte votre propre HTML avant/après le contenu.

Placeholders « (sans titre) » / « (vide) »

Option	Type	Effet
`suppressEmptyPlaceholdersForChapters`	`boolean`	Raccourci pour les objets « chapitres ». Sans effet sans `chapterNumberAttributes`.
`isTitleless`	`(obj, specType, index) => boolean`	Décide, par vos critères, qu'un titre vide est normal pour cet objet.
`isContentless`	`(obj, specType, index) => boolean`	Idem pour un contenu vide. Indépendant du précédent.

Les trois se composent : la suppression a lieu si l'un dit oui. Voir Titre et contenu affichés.

Pièces jointes et diagnostics

Option	Type	Défaut	Effet
`attachments`	`AttachmentResolver`	celui du paquet	Remplace le résolveur. Détails
`maxInlineBytes`	`number`	`5 * 1024 * 1024`	Taille maximale intégrée en `data:` URI, par fichier.
`onDegradation`	`DegradationHandler`	—	Observe tout ce que le rendu dégrade silencieusement. Détails

`RenderLabels`

Tous les libellés d'interface, en anglais par défaut. labels accepte un objet partiel — seuls les libellés fournis sont remplacés.

interface RenderLabels {
  noContent: string;              // "(vide)"
  untitled: string;               // "(sans titre)"
  idLabel: string;
  technicalDetails: string;       // "Détails techniques"
  headerTitle: string;
  headerSourceTool: string;
  headerExportedBy: string;
  headerCreationTime: string;
  headerComment: string;
  yes: string;
  no: string;
  createdByLabel: string;
  createdOnLabel: string;
  modifiedByLabel: string;
  modifiedOnLabel: string;
  relationsLabel: string;         // "Liens"
  relationFallbackType: string;
  relationUnresolved: string;
}

`FRENCH_LABELS`

const FRENCH_LABELS: RenderLabels;

Le jeu complet que la bibliothèque livrait par défaut jusqu'à la 0.2.0, pour que le rendu précédent soit à une ligne plutôt qu'à dix-huit :

import { FRENCH_LABELS } from "reqif-preview";

const html = await renderPackageToHtml(pkg, {
  labels: FRENCH_LABELS,
  dateLocale: "fr-FR",
});

Toute autre langue suit la même forme — labels est partiel, ne fournissez que ce qu'il vous faut.

`CustomAttributeRenderer`

interface CustomAttributeRenderer {
  attribute: string;                    // nom long (insensible casse/espaces) ou identifiant
  position?: "before" | "after";        // défaut : "before"
  render(value: AttributeValue | undefined, ctx: AttributeRenderContext): RenderOutput;
  hideFromTechnical?: boolean;          // défaut : false
}

Deux filets de sécurité : une exception dans render() est interceptée (custom-renderer-threw), et un dangerouslyRawHtml mal fermé est affiché en texte échappé (custom-renderer-unbalanced-html) plutôt que de casser la structure de tout ce qui suit. Voir Rendus personnalisés.

`RenderOutput`, `RenderNode`, `RenderElement`, `RenderRawHtml`

Ce qu'un rendu retourne. Le texte est échappé par défaut ; le balisage brut se demande explicitement.

type RenderNode = string | RenderElement | RenderRawHtml;

interface RenderElement {
  tag: string;                      // liste blanche, sinon déballé (unwrapped-tag)
  attrs?: Record<string, string>;   // liste blanche, valeurs échappées
  children?: RenderNode[];          // une chaîne y est du texte
}

interface RenderRawHtml {
  dangerouslyRawHtml: string;       // inséré tel quel — à vous de l'échapper
}

type RenderOutput = RenderElement | RenderRawHtml | RenderNode[] | undefined;

	Autorisé
Balises	`span` `div` `p` `a` `code` `strong` `b` `em` `i` `small` `br` `img` `ul` `ol` `li`
Attributs	`class` `id` `title` `lang` `dir`, plus `href` / `src` via le filtre de schéma d'URL

style est délibérément absent — la présentation va dans votre feuille de style. Une chaîne nue n'est pas acceptée au premier niveau : sous l'API précédente elle voulait dire du HTML brut, donc l'accepter changerait silencieusement ce que produisent les rendus existants. Depuis du JavaScript sans types, elle est échappée, avec custom-renderer-raw-string.

`AttributeRenderContext`

interface AttributeRenderContext {
  specObject: SpecObject;
  specType: SpecType | undefined;
  index: ReqIfIndex;
  attachments: AttachmentLookup;
  isChapter: boolean;
  getValue(attributeNameOrId: string): AttributeValue | undefined;
  getDefinition(attributeNameOrId: string): AttributeDefinition | undefined;
  formatValue(value: AttributeValue | undefined): string;
}

formatValue réutilise exactement le formatage du panneau technique : libellés d'énumération résolus, XHTML assaini, booléens selon labels.yes/labels.no. C'est le moyen le plus court d'afficher une valeur « comme la bibliothèque le ferait » sans réimplémenter la logique de type.

Options de rendu ​

RenderOptions ​

Présentation ​

Contenu ​

Placeholders « (sans titre) » / « (vide) » ​

Pièces jointes et diagnostics ​

RenderLabels ​

FRENCH_LABELS ​

CustomAttributeRenderer ​

RenderOutput, RenderNode, RenderElement, RenderRawHtml ​

AttributeRenderContext ​