ozi-editor

Versão: 3.1.0 — Atualizado em: 2026-06-01

Você tem a escolha de editor html ou editor markdown na mesma ferramenta.

Descrição

Editor visual ativado sobre um <textarea>, com suporte a dois modos: HTML e Markdown. O <textarea> continua sendo o campo real de envio — o plugin cria uma interface visual sobre ele, mantendo compatibilidade natural com formulários, Livewire e qualquer backend PHP.

O type é declarado diretamente no atributo identificador:

data-ozi-editor-html="key"   <!-- editor HTML -->
data-ozi-editor-md="key"     <!-- editor Markdown -->

Zero ambiguidade — o type é visível de relance no template, sem atributo extra.

O modo Markdown requer o arquivo complementar ozi-editor-md.js.

Recursos

• Dois modos — HTML rico ou Markdown com preview visual
• Toolbar configurável — ferramentas, grupos e quebras de linha via atributo
• Themes de toolbar — presets built-in e presets do dev via oziConf
• Classes CSS customizadas — dropdown de estilos aplicáveis ao texto selecionado
• Headings — dropdown h1–h6 na toolbar
• Sanitização — remove tags fora do conjunto permitido ao colar conteúdo externo
• Validação — campo obrigatório com mensagem customizada e integração com ozi-validate
• Disabled — bloqueia edição e toolbar programaticamente
• Cor customizável — data-ozi-editor-uicolor controla foco e botões ativos
• Dark mode — via [data-ozi-theme="dark"] e @media (prefers-color-scheme: dark)
• Compatível com Livewire — re-init via OZI.hooks.afterRender
• API pública — leitura, escrita, disable, reload e destroy por chave

Exemplos

[1] Simples — HTML e Markdown

<!-- Editor HTML -->
<textarea
    name="conteudo"
    data-ozi-editor-html="conteudo">
</textarea>

<!-- Editor Markdown -->
<textarea
    name="conteudo"
    data-ozi-editor-md="conteudo">
</textarea>

[2] Custom simples — HTML e Markdown

<!-- Editor HTML -->
<textarea
    name="descricao"
    data-ozi-editor-html="descricao"
    data-ozi-editor-tools="bold, italic, underline, ul, codeblock, table"
    data-ozi-editor-uicolor="#9AB8F3"
    data-ozi-editor-placeholder="Digite aqui..."
    data-ozi-editor-height="220px">
</textarea>

<!-- Editor Markdown -->
<textarea
    name="descricao"
    data-ozi-editor-md="descricao"
    data-ozi-editor-tools="bold, italic, ul, codeblock, table"
    data-ozi-editor-uicolor="#9AB8F3"
    data-ozi-editor-placeholder="Digite aqui..."
    data-ozi-editor-height="220px">
</textarea>

[3] Toolbar agrupada — HTML e Markdown

[ ] agrupa botões visualmente — , separa itens — ; quebra a linha da toolbar.

<!-- Editor HTML -->
<textarea
    name="descricao"
    data-ozi-editor-html="descricao"
    data-ozi-editor-tools="[bold,italic,underline], [ul,ol], codeblock; table, clear, [left,center,right], source"
    data-ozi-editor-uicolor="#9AB8F3"
    data-ozi-editor-placeholder="Digite aqui..."
    data-ozi-editor-height="220px">
</textarea>

<!-- Editor Markdown -->
<textarea
    name="descricao"
    data-ozi-editor-md="descricao"
    data-ozi-editor-tools="[bold,italic], [ul,ol], codeblock; table, source"
    data-ozi-editor-uicolor="#9AB8F3"
    data-ozi-editor-placeholder="Digite aqui..."
    data-ozi-editor-height="220px">
</textarea>

left, center, right e clear não estão disponíveis no modo Markdown — se declarados, aparecem como ? (inativo).

[4] Classes CSS e headings — HTML e Markdown

<!-- Editor HTML -->
<textarea
    name="descricao"
    data-ozi-editor-html="descricao"
    data-ozi-editor-tools="[bold,italic,underline], classes, [ul,ol], codeblock; heading, table, clear, [left,center,right], source"
    data-ozi-editor-class="text-success:Sucesso, text-info:Info, text-danger:Perigo"
    data-ozi-editor-uicolor="#9AB8F3"
    data-ozi-editor-placeholder="Digite aqui..."
    data-ozi-editor-height="220px">
</textarea>

<!-- Editor Markdown -->
<textarea
    name="descricao"
    data-ozi-editor-md="descricao"
    data-ozi-editor-tools="[bold,italic], [ul,ol], codeblock; heading, table, source"
    data-ozi-editor-uicolor="#9AB8F3"
    data-ozi-editor-placeholder="Digite aqui..."
    data-ozi-editor-height="220px">
</textarea>

O botão classes só aparece na toolbar se data-ozi-editor-class estiver declarado com ao menos uma entrada válida. No modo Markdown o dev pode usá-lo conscientemente — gera HTML literal no Markdown.

[5] Editor HTML — Themes de toolbar

Themes são atalhos para strings de toolbar pré-definidas. Evitam repetir configuração em cada elemento.

Themes built-in para HTML:

Usando um theme built-in:

<textarea
    name="descricao"
    data-ozi-editor-html="descricao"
    data-ozi-editor-theme="blog"
    data-ozi-editor-uicolor="#9AB8F3"
    data-ozi-editor-placeholder="Digite aqui..."
    data-ozi-editor-height="220px">
</textarea>

Criando um theme customizado via oziConf:

<textarea
    name="descricao"
    data-ozi-editor-html="descricao"
    data-ozi-editor-theme="custom"
    data-ozi-editor-class="text-success:Sucesso, text-info:Info, text-danger:Perigo"
    data-ozi-editor-uicolor="#9AB8F3"
    data-ozi-editor-placeholder="Digite aqui..."
    data-ozi-editor-height="220px">
</textarea>

<script>
oziConf({
    components: {
        editor: {
            themes: {
                html: {
                    custom: '[bold,italic], heading, source'
                }
            }
        }
    }
});
</script>

Prioridade de resolução da toolbar (do mais ao menos específico):

[6] Editor Markdown

Requer ozi-editor-md.js carregado após ozi-editor.js.

Themes built-in para MD:

Ferramentas bloqueadas em MD — aparecem como ? (inativas, com tooltip explicativo):

Subset Markdown suportado:

Carregamento do ozi-editor-md.js:

Via oziConf (recomendado):

oziConf({
    plugins: ['editor', 'editor-md']
});

Via <script> manual (ordem importa):

<script src="./plugins/ozi-ui/components/ozi-editor/js/ozi-editor.js"></script>
<script src="./plugins/ozi-ui/components/ozi-editor/js/ozi-editor-md.js"></script>

[7] Dois editores na mesma página

<!-- HTML para o corpo do post -->
<textarea
    name="corpo"
    data-ozi-editor-html="corpo"
    data-ozi-editor-theme="blog">
</textarea>

<!-- Markdown para a descrição técnica -->
<textarea
    name="readme"
    data-ozi-editor-md="readme"
    data-ozi-editor-theme="standard">
</textarea>

Nenhuma configuração extra — cada atributo carrega seu type.

[8] Saída enviada ao backend

O <textarea> sempre recebe o conteúdo no formato nativo do type:

data-ozi-editor-html — HTML sanitizado:

<p>Texto normal</p>
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>
<pre><code>const x = 10;</code></pre>

data-ozi-editor-md — Markdown puro:

Texto normal

- Item 1
- Item 2

```js
const x = 10;
` ` `

[9] Uso via JavaScript

// Inicializar todos os editores da página
OZI.components.editor.init();

// Inicializar em conteúdo injetado (ex: após loaddata ou Livewire)
OZI.components.editor.init(document.querySelector('#destino'));

// Obter valor (retorna no formato nativo do type)
var conteudo = OZI.components.editor.value('descricao');

// Definir valor
OZI.components.editor.value('descricao', '<p>Texto inicial</p>');

// Obter instância
var inst = OZI.components.editor.get('descricao');
console.log(inst.editorType); // 'html' ou 'md'

// Listar todas as instâncias ativas
var todas = OZI.components.editor.getAll();

// Disable / Enable
OZI.components.editor.disable('descricao');
OZI.components.editor.enable('descricao');

// Recarregar instância
OZI.components.editor.reload('descricao');

// Destruir instância
OZI.components.editor.destroy('descricao');

Ferramentas disponíveis

⛔ Ferramentas bloqueadas no modo Markdown aparecem como ? na toolbar (inativas, com tooltip explicativo).

Atributos HTML

[1] Identificação e tipo

Um dos dois é obrigatório. Usar os dois no mesmo elemento inicializa como HTML (html vence).

[2] Toolbar

[3] Visual

[4] Estado e Validação

HTML Permitido (sanitização)

Tags aceitas na área editável e no conteúdo colado:

p, br, strong, em, u, span,
ul, ol, li,
pre, code,
table, thead, tbody, tr, td, th,
h1, h2, h3, h4, h5, h6

Substituições automáticas: <div> → <p>, <b> → <strong>, <i> → <em>. Atributos removidos exceto style.textAlign e class (quando aplicado via dropdown de classes).

API Pública

OZI.components.editor

Namespace legado

Eventos

document.querySelector('[data-ozi-editor-html="descricao"]')
    .addEventListener('ozi:change', function (e) {
        console.log(e.detail.key);   // 'descricao'
        console.log(e.detail.value); // conteúdo atual
        console.log(e.detail.type);  // 'html'
    });

oziConf

oziConf({
    components: {
        editor: {
            uicolor:      'var(--ozi-color-primary)', // cor padrão global
            defaultTheme: 'standard',                 // theme padrão global
            defaultTools: '[bold,italic]; source',    // string direta (compat)
            themes: {
                html: {
                    custom: '[bold,italic], heading, source'
                },
                md: {
                    custom: '[bold,italic]; heading; source'
                }
            }
        }
    }
});

Como funciona

1. <script src="ozi.js"> carrega o ecossistema

2. _boot() inicializa apenas [data-ozi-editor-html]
   → elementos [data-ozi-editor-md] aguardam

3. ozi-editor-md.js carrega (após ozi-editor.js)
   → registerConverters({ mdToHtml, htmlToMd })
   → init(null, 'md') inicializa os elementos md pendentes

4. Usuário edita no modo visual
   → conteúdo sanitizado sincroniza com o <textarea>

5. Livewire / loaddata injeta HTML novo
   → OZI.hooks.afterRender.run(root)
   → editor reinicializa nos novos elementos

6. Formulário submete
   → <textarea> com conteúdo no formato nativo do type

Chaves em uso nesta página