Importer des styles

Remplit les menus de styles avec les classes CSS déjà utilisées par votre site. Avec importStyles: true, l’éditeur lit les feuilles de style de la page, trouve les sélecteurs de classe tels que p.lede ou img.rounded, puis ajoute chaque classe au menu de styles de paragraphes, de texte, d’images ou de liens. Les auteurs choisissent ainsi les classes de votre système de design plutôt que les classes d’exemple.

Activation

Cette fonctionnalité est fournie par le plugin importstyles.js (également inclus dans plugins/all_plugins.js). Elle reste désactivée tant que vous ne définissez pas importStyles: true. Elle n’a pas de bouton propre ; elle remplit les menus de paragraphstyle et inlinestyle (barre principale), imagestyle (barre d’image) et linkstyle (barre de lien).

Feuille de style de cet exemple :

p.lede { font-size: 1.25em; color: #334155; }
blockquote.pull-quote { border-left: 4px solid #2563eb; padding-left: 12px; font-style: italic; }
span.badge { background: #fde68a; padding: 0 4px; border-radius: 4px; }
.highlight { background: #dcfce7; }
img.rounded { border-radius: 12px; }
a.cta { background: #2563eb; color: #fff; padding: 4px 10px; border-radius: 6px; }
article .card p.note:hover { color: #0f766e; }
p.lede.wide { max-width: none; }
.js-toggle { display: none; }
@media (min-width: 600px) { h2.section-title { letter-spacing: .02em; } }

<link rel="stylesheet" href="site.css">
<script src="/richtexteditor/rte.js"></script>
<script src="/richtexteditor/plugins/all_plugins.js"></script>
<div id="editor"><p>Intro paragraph that should become a lede.</p></div>
<script>
var editor = new RichTextEditor("#editor", {
  toolbar: "full",
  contentCssUrl: "site.css",   // so the classes also look right inside the editor
  importStyles: true
});
</script>

Cette feuille a produit les menus suivants (editor.getImportedStyles() a indiqué applied: { imageStyles: 1, linkStyles: 1, inlineStyles: 2, paragraphStyles: 5 }):

Menu	Entrées importées
Styles de paragraphes	Lede, Pull Quote, Highlight, Note, Section Title
Styles de texte	Badge, Highlight
Styles d’images	Rounded
Styles de liens	Cta

Choisir Lede sur le premier paragraphe a enregistré <p class="lede">Intro paragraph that should become a lede.</p>.

Classement des classes

• Seule la dernière partie d’un sélecteur compte : article .card p.note:hover donne note pour les paragraphes. Les pseudo-classes et filtres d’attributs sont ignorés.
• L’élément devant la classe détermine le menu : img, figure, picture vont dans les styles d’images ; a dans les styles de liens ; span, strong, b, em, i, code, mark, small, sub, sup, abbr, q, cite dans les styles de texte ; p, div, les titres, blockquote, les listes, pre, les sections et cellules de tableau dans les styles de paragraphes. Une classe sans élément (.highlight) va à la fois dans les styles de texte et de paragraphes. Les autres éléments sont ignorés.
• Un sélecteur avec deux classes sur un élément (p.lede.wide) est ignoré, car aucune classe seule ne lui correspond.
• Les classes dans @media et @supports sont détectées.
• Le libellé est construit à partir du nom de la classe : pull-quote devient « Pull Quote ». Un préfixe my-cls-, u- ou c- est retiré.
• Les feuilles de style de l’éditeur ne sont jamais lues (tout ce qui provient du dossier /richtexteditor/, ainsi que les styles injectés par l’éditeur).

Options

Option	Valeur par défaut	Fonctionnement
importStyles	false	Active l’importation.
importStylesSheets	null (toutes les feuilles lisibles)	Feuilles à lire : une chaîne recherchée dans l’URL de la feuille ("site.css"), une RegExp (/theme/) ou une fonction recevant la CSSStyleSheet et renvoyant true ou false.
importStylesExclude	/^(rte[-_]|ck[-_]|cke[-_]|mce[-_]|tox[-_]|js[-_]|is[-_]|has[-_])/i	Noms de classes à ne jamais importer. Une RegExp, une fonction du nom de classe ou un préfixe sous forme de chaîne. La valeur par défaut a ignoré .js-toggle ci-dessus.
importStylesFilter	null	function (className, selectorText, menu). Renvoyez false pour ignorer une classe, ou une chaîne pour son libellé. menu vaut "paragraphStyles", "inlineStyles", "imageStyles" ou "linkStyles".
importStylesReplace	false	false ajoute les classes importées après celles configurées ; true les remplace.
importStylesLimit	100	Nombre maximal d’entrées par menu. Les classes supplémentaires sont ignorées avec un avertissement dans la console. 0 signifie aucune limite.

Par exemple, pour masquer une classe et en renommer une autre :

importStylesFilter: function (cls, selector, menu) {
  if (cls === "highlight") return false;
  if (cls === "lede") return "Lead paragraph";
}

API

• editor.getImportedStyles() renvoie le résultat de la dernière importation : { applied, truncated, droppedCount, unreadableSheets, documentsScanned, replaced }.
• editor.scanStylesheetClasses(options) liste les classes qui seraient importées, sous la forme { classes: [{ cls, tag, selector }], unreadableSheets, documents }, sans modifier les menus. Fonctionne même si importStyles est désactivé.
• editor.importStyles(options) relance l’importation, par exemple après le chargement d’une autre feuille. Les options utilisent les noms courts : { sheets, exclude, filter, replace, limit }.

À savoir

• Les feuilles de style d’une autre origine ne peuvent pas être lues. Le navigateur bloque leurs règles ; elles sont comptées dans unreadableSheets et ignorées, puis l’analyse continue. Dans le test ci-dessus, une copie de la même feuille chargée depuis une seconde origine a été signalée comme unreadableSheets: 1. Servez la feuille dont vous souhaitez importer les classes depuis votre propre domaine.
• Les deux documents sont lus : la page et la zone d’édition (où contentCssUrl est chargé). L’importation s’exécute au démarrage de l’éditeur, puis lorsqu’il est prêt.
• Fournissez vos propres listes si la page contient plusieurs éditeurs. Dans la version 2.6.12, avec importStylesReplace: false, les classes importées sont ajoutées aux listes par défaut partagées (RTE_DefaultConfig.paragraphStyles et les autres) : un second éditeur créé ensuite sur la même page les affiche même si importStyles est désactivé. Définir paragraphStyles, inlineStyles, imageStyles et linkStyles dans la configuration de chaque éditeur, ou importStylesReplace: true, les garde séparées.
• Le HTML enregistré ne contient que le nom de classe (class="lede"). La page affichant le contenu doit charger la même feuille de style et le filtre de nettoyage HTML doit autoriser class.
• Sur une page utilisant du CSS utilitaire (des centaines de classes spécialisées), limitez l’importation avec importStylesSheets ou importStylesFilter plutôt que d’augmenter la limite.

Voir aussi : démonstration des styles de paragraphes et de texte, référence de configuration.