Personalização Profunda do Editor TinyMCE 5.10.2 em Projetos Vue3: Guia de Skin em Português e Armadilhas Comuns

Após integrar com sucesso o editor TinyMCE no seu projeto Vue3, o próximo desafio é torná-lo verdadeiramente "em português" e com uma interface que se alinhe ao estilo do seu projeto. Este artigo irá guiá-lo através do processo completo de localização e customização visual do TinyMCE versão 5.10.2, compartilhando experiências práticas que só quem enfrentou os problemas conhece.

1. Configuração Precisa do Pacote de Idioma Português

Muitos desenvolvedores acreditam que simplesmente incluir o pacote de idioma é suficiente para a tradução, mas na verdade o suporte ao português no TinyMCE requer resolver três problemas-chave: caminho de carregamento dos arquivos de idioma, tradução completa dos itens do menu e localização de termos específicos dos plugins.

1.1 Obtendo o Pacote de Idioma Oficial em Português

Não baixe pacotes de idioma de fontes não oficiais, pois incompatibilidades de versão podem causar falta de alguns termos. A abordagem correta é:

1. Acesse a página oficial de pacotes de idioma do TinyMCE
2. Baixe o arquivo pt\_BR.js correspondente à versão 5.10.2
3. Verifique a integridade do arquivo (a versão completa deve exceder 20KB)

Nota: Existem diferenças entre os pacotes de idioma das versões gratuita e paga, especialmente nas traduções dos plugins avançados.

1.2 Configuração de Caminho no Projeto

Erros comuns de caminho incluem: o carregamento funciona no ambiente de desenvolvimento mas falha no ambiente de produção, ou problemas de resolução de caminho após o build do webpack. A estrutura de diretórios recomendada é:

public/
  └── tinymce/
       ├── langs/
       │    └── pt_BR.js
       └── skins/
            └── (arquivos do skin)

A configuração de inicialização correspondente deve ser:

const init = {
  language_url: '/tinymce/langs/pt_BR.js',
  language: 'pt_BR',
  skin_url: '/tinymce/skins/ui/oxide'
}

1.3 Verificando a Completude da Tradução

Mesmo com a configuração correta do pacote de idioma, podem aparecer termos em inglês em certos cenários:

• Plugins carregados dinamicamente: como o spellchecker, que requer configuração de idioma separada
• Itens de menu personalizados: menus adicionados manualmente precisam de tradução correspondente
• Plugins de terceiros: alguns plugins da comunidade podem não incluir recursos em português

Pode-se resolver parte desses problemas sobrescrevendo o dicionário padrão:

tinymce.addI18n('pt_BR', {
  'Meu item de menu personalizado': 'Meu item de menu personalizado',
  // Adicione outras traduções personalizadas
});

2. Customização Profunda do Sistema de Skins

O TinyMCE 5.10.2 oferece dois skins oficiais: oxide (tema claro) e oxide-dark (tema escuro), mas em projetos reais é frequentemente necessária uma customização visual mais aprofundada.

2.1 Troca Básica de Skin

Trocar o skin não é apenas alterar cores, mas considerar a consistência visual de todo o conjunto de componentes UI:

// Tema claro
skin_url: '/tinymce/skins/ui/oxide'

// Temo escuro
skin_url: '/tinymce/skins/ui/oxide-dark'

2.2 Sobrescrita com CSS Personalizado

através do parâmetro content_css é possível customizar profundamente os estilos da área de edição:

/* public/tinymce/content.css */
body {
  font-family: "Segoe UI", sans-serif;
  line-height: 1.6;
  color: #333;
}

table {
  border-collapse: collapse;
  width: 100%;
}

img {
  max-width: 100%;
  height: auto;
}

Na configuração de inicialização, referencie este arquivo:

content_css: '/tinymce/content.css'

2.3 Criando um Skin Totalmente Personalizado

Se for necessário um skin totalmente customizado, pode-se copiar os arquivos do skin oficial como base:

1. Copie todos os arquivos de node_modules/tinymce/skins/ui/oxide
2. Crie um diretório de skin personalizado no diretório public, como meu-skin-personalizado
3. Modifique as variáveis de cor e estilo no arquivo skin.css
4. Na configuração, aponte para o caminho personalizado:

skin_url: '/tinymce/skins/ui/meu-skin-personalizado'

3. Tratamento de Compatibilidade do Sistema de Plugins

A funcionalidade poderosa do TinyMCE vem de seu sistema de plugins, mas problemas de compatibilidade entre versões frequentemente se tornam pesadelos para desenvolvedores.

3.1 Combinação Recomendada de Plugins para a Versão 5.10.2

Com base em experiência prática em projetos, a seguintee combinação de plugins apresenta estabilidade em ambientes Vue3:

plugins: [
  'advlist anchor autolink autoresize',
  'code codesample directionality',
  'emoticons image importcss',
  'link lists media nonbreaking',
  'pagebreak paste preview print',
  'quickbars save searchreplace',
  'table template textpattern',
  'visualblocks visualchars wordcount'
].join(' ')

3.2 Soluções para Conflitos Comuns de Plugins

Conflito entre autoresize e o atributo height

Sintoma: A configuração de height é ignorada e a altura do editor é instável.

Solução: Use o parâmetro autoresize_on_init em vez de height:

autoresize_on_init: true,
height: '500px'

Problemas com o plugin de importação de CSS

Sintoma: Estilos personalizados não são aplicados corretamente no editor.

Solução: Configure o plugin importcss corretamente:

importcss_append: true,
content_css: '/caminho/para/seus/estilos.css'

Incompatibilidade com Vue3 reactivity

Sintoma: O editor não responde às atualizações de dados no componente Vue.

Solução: Use refs e o método updateContent para sincronização:

const editorRef = ref(null);

const updateEditorContent = (content) => {
  if (editorRef.value) {
    editorRef.value.editorInstance?.getContent().setContent(content);
  }
};