Importar estilos

Preenche os menus de estilo do editor com as classes CSS que o seu site já tem. Com importStyles: true, o editor lê as folhas de estilo da página, encontra seletores de classe como p.lede ou img.rounded e adiciona cada classe ao menu de estilos de parágrafo, inline, de imagem ou de link; assim, os autores escolhem as classes do seu design system em vez das de exemplo.

Ative o recurso

O recurso é o plugin importstyles.js (também incluído em plugins/all_plugins.js). Ele fica desativado até você definir importStyles: true. Não tem botão próprio; ele preenche os menus por trás de paragraphstyle e inlinestyle (barra de ferramentas principal), imagestyle (barra de ferramentas de imagem) e linkstyle (barra de ferramentas de link).

A folha de estilo deste exemplo:

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>

Essa folha de estilo gerou estes menus (editor.getImportedStyles() informou applied: { imageStyles: 1, linkStyles: 1, inlineStyles: 2, paragraphStyles: 5 }):

Menu	Entradas importadas
Estilos de parágrafo	Lede, Pull Quote, Highlight, Note, Section Title
Estilos inline	Badge, Highlight
Estilos de imagem	Rounded
Estilos de link	Cta

Escolher Lede no primeiro parágrafo salvou <p class="lede">Intro paragraph that should become a lede.</p>.

Como as classes são distribuídas

• Só a última parte de um seletor conta: article .card p.note:hover gera note para parágrafos. Pseudo-classes e filtros de atributo são ignorados.
• O elemento na frente da classe decide o menu: img, figure, picture vão para os estilos de imagem; a para os estilos de link; span, strong, b, em, i, code, mark, small, sub, sup, abbr, q, cite para os estilos inline; p, div, títulos, blockquote, listas, pre, seções e células de tabela para os estilos de parágrafo. Uma classe sem elemento (.highlight) vai tanto para os estilos inline quanto para os de parágrafo. Outros elementos são ignorados.
• Um seletor com duas classes no mesmo elemento (p.lede.wide) é ignorado, já que nenhuma classe sozinha corresponde a ele.
• As classes dentro de @media e @supports são encontradas.
• O rótulo é criado a partir do nome da classe: pull-quote vira "Pull Quote". Um prefixo my-cls-, u- ou c- no início é removido.
• As folhas de estilo do próprio editor nunca são lidas (nada da pasta /richtexteditor/, nem os estilos que o editor injeta).

Opções

Opção	Padrão	O que faz
importStyles	false	Ativa a importação.
importStylesSheets	null (todas as folhas legíveis)	Quais folhas ler: uma string comparada com a URL da folha ("site.css"), uma RegExp (/theme/) ou uma função que recebe a CSSStyleSheet e retorna true ou false.
importStylesExclude	/^(rte[-_]|ck[-_]|cke[-_]|mce[-_]|tox[-_]|js[-_]|is[-_]|has[-_])/i	Nomes de classes que nunca são importados. Uma RegExp, uma função do nome da classe ou um prefixo em string. O padrão ignorou .js-toggle acima.
importStylesFilter	null	function (className, selectorText, menu). Retorne false para ignorar uma classe, ou uma string para usá-la como rótulo. menu é "paragraphStyles", "inlineStyles", "imageStyles" ou "linkStyles".
importStylesReplace	false	false adiciona as classes importadas depois das configuradas; true as substitui.
importStylesLimit	100	Máximo de entradas por menu. As classes excedentes são descartadas com um aviso no console. 0 significa sem limite.

Por exemplo, para ocultar uma classe e renomear outra:

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

API

• editor.getImportedStyles() retorna o que a última importação fez: { applied, truncated, droppedCount, unreadableSheets, documentsScanned, replaced }.
• editor.scanStylesheetClasses(options) lista o que seria importado, como { classes: [{ cls, tag, selector }], unreadableSheets, documents }, sem alterar os menus. Funciona com importStyles desativado.
• editor.importStyles(options) executa a importação de novo, por exemplo depois de carregar outra folha de estilo. As opções usam os nomes curtos: { sheets, exclude, filter, replace, limit }.

O que você precisa saber

• Folhas de estilo de outra origem não podem ser lidas. O navegador bloqueia as regras delas; elas são contadas em unreadableSheets e ignoradas, e o resto da varredura continua. No teste acima, uma cópia da mesma folha de estilo carregada de uma segunda origem foi informada como unreadableSheets: 1. Sirva a partir do seu próprio domínio a folha de estilo cujas classes você quer.
• Os dois documentos são lidos: a página e a área de edição do editor (onde contentCssUrl é carregado). A importação roda quando o editor inicia e de novo quando ele fica pronto.
• Passe as suas próprias listas quando a página tiver vários editores. Na 2.6.12, com importStylesReplace: false, as classes importadas são adicionadas às listas padrão compartilhadas (RTE_DefaultConfig.paragraphStyles e as outras); assim, um segundo editor criado depois na mesma página as mostra mesmo com importStyles desativado. Definir paragraphStyles, inlineStyles, imageStyles e linkStyles na configuração de cada editor, ou importStylesReplace: true, mantém tudo separado.
• O HTML salvo só leva o nome da classe (class="lede"). A página que exibe o conteúdo precisa da mesma folha de estilo, e um sanitizador de HTML precisa permitir class.
• Em uma página com CSS utilitário (centenas de classes de propósito único), restrinja a importação com importStylesSheets ou importStylesFilter em vez de aumentar o limite.

Relacionados: demonstração de estilos de parágrafo e inline, referência de configuração.