Référence API — vue d'ensemble

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)!;

Tout est exporté depuis la racine du paquet :

import { loadReqIfPackage, renderPackageToHtml /* … */ } from "reqif-preview";

Les dix fonctions qui comptent

Export	Description
loadReqIfPackage(input, options?)	Charge un .reqif (string/bytes) ou .reqifz (bytes), retourne un ReqIfPackage.
parseReqIfXml(xml, options?)	Parse une seule chaîne XML ReqIF en ReqIfDocument.
ReqIfIndex	Index de résolution O(1) des références croisées d'un ou plusieurs documents.
renderPackageToHtml(pkg, options?)	Rendu HTML complet — tous les documents du paquet.
renderDocumentToHtml(doc, attachments, options?, sharedIndex?)	Rendu HTML d'un seul document.
renderSpecification(spec, index, attachments, labels?, options?)	Rendu synchrone d'une seule arborescence — pour une UI virtualisée.
createAttachmentLookup(doc, resolver, maxInlineBytes?, onDegradation?)	Pré-résout les pièces jointes en data: URI — nécessaire pour alimenter renderSpecification.
renderXhtmlContent(content, options?)	Sérialisation assainie d'un fragment XHTML isolé.
xhtmlToPlainText(content)	Extraction texte brut d'un fragment XHTML.
createAttachmentResolver(fn)	Construit un résolveur de pièces jointes personnalisé.

Où trouver quoi

Page	Contenu
Chargement et parsing	loadReqIfPackage, parseReqIfXml, ParseOptions, ReqIfParseError, résolveurs de pièces jointes
Rendu HTML	Les quatre fonctions de rendu, renderXhtmlContent, xhtmlToPlainText, escapeHtml
Options de rendu	RenderOptions au complet, RenderLabels, les rendus personnalisés
Modèle de données	Tous les types du modèle ReqIF, ReqIfIndex et les helpers de lecture
Diagnostics	DegradationCode, DegradationEvent, DegradationHandler

Ce qui peut lever

Une seule chose : le parsing.

import { ReqIfParseError } from "reqif-preview";

try {
  const pkg = await loadReqIfPackage(bytes);
} catch (e) {
  if (e instanceof ReqIfParseError) { /* XML invalide, zip corrompu, racine absente… */ }
}

Passé ce point, plus rien ne lève : les fonctions de rendu dégradent localement et poursuivent. Pour savoir ce qui a été dégradé, voir Diagnostics.

Feuille de style

Le rendu embarque sa propre feuille de style dans un <style> en tête du HTML retourné, scopée sur .reqif-preview. Il n'y a donc rien à importer ni à lier : c'est ce qui rend la sortie autonome, insérable telle quelle avec innerHTML.

Pour la fournir vous-même — cas d'une politique de sécurité de contenu (CSP) interdisant les <style> inline, ou d'un thème maison :

const html = await renderPackageToHtml(pkg, { includeCss: false });

La feuille reste alors accessible de deux façons, l'une et l'autre issues de la même source, donc jamais désynchronisées :

// Un fichier, pour un <link> ou un import de bundler.
import "reqif-preview/style.css";

// Le texte, pour ce qu'un <link> n'atteint pas — un Shadow DOM, par exemple.
import { DEFAULT_CSS } from "reqif-preview";

const shadowRoot = document.getElementById("preview")!.attachShadow({ mode: "open" });

const sheet = new CSSStyleSheet();
sheet.replaceSync(DEFAULT_CSS);
shadowRoot.adoptedStyleSheets = [sheet];

Si vous écrivez vos propres règles à la place, sachez que les onglets cessent de fonctionner sans elles : leur mécanisme est entièrement porté par les règles :target de cette feuille.

La feuille suppose un fond clair

.reqif-preview fixe une couleur de texte (#1a1a1a) mais aucun fond. Inséré tel quel dans une page au thème sombre, l'aperçu serait illisible : c'est à l'hôte de fournir une surface claire.