Como personalizar o ONLYOFFICE Docs com seu logotipo e cores.

A resposta mais curta: use a identidade visual da API do Docs para o logotipo e um tema de interface personalizado para as cores.

Se o seu objetivo é fazer com que o editor do ONLYOFFICE Docs pareça parte integrante do seu próprio produto, a configuração mais elegante é uma personalização em duas camadas: configure editorConfig.customization.logoa integração da API do Docs para o logotipo do cabeçalho e, em seguida, adicione um arquivo JSON de tema personalizado no Servidor de Documentos para as cores do editor. Esses são mecanismos separados e possuem regras de disponibilidade diferentes.

Conforme verificado na documentação do ONLYOFFICE em 7 de outubro de 2026, o logoparâmetro editor-header está disponível apenas para o ONLYOFFICE Docs Developer. A API oficial especifica imagens de 300×20 para <header> image, imageDark<header> e imageLight<body>, com uma altura recomendada para o logotipo de 20 pixels. Temas de interface personalizados, por sua vez, são suportados desde o ONLYOFFICE Docs v7.0 e são instalados como arquivos JSON de tema no Servidor de Documentos. A referência oficial atual é a documentação de identidade visual padrão do ONLYOFFICE Docs , e o fluxo de trabalho com arquivos de tema está documentado em Alterando temas de interface no ONLYOFFICE Docs .

Essa abordagem é adequada para equipes que incorporam o ONLYOFFICE Docs em seus próprios aplicativos web e controlam o Servidor de Documentos. Não se trata do mesmo que alterar o tema de um portal DocSpace ou Workspace. Se o seu objetivo for o portal em si, e não o editor, utilize as configurações de marca desse produto.

Passo 1: confirme o que você realmente precisa para a sua marca.

Antes de editar os arquivos, divida a personalização da marca em três questões. Você precisa apenas de um logotipo no cabeçalho do editor? Deseja também as cores da marca em barras de ferramentas, botões, textos, bordas e painéis? Ou precisa de uma experiência de personalização completa que altere outros elementos da interface?

• Logotipo do cabeçalho: use editorConfig.customization.logo. ONLYOFFICE marca este parâmetro como exclusivo para desenvolvedores.
• Cores da interface: instale um arquivo JSON de tema personalizado no Servidor de Documentos. Este é o mecanismo correto para cores da marca.
• Controles de marca branca mais detalhados: consulte a documentação completa sobre marca branca . A ONLYOFFICE afirma que esses parâmetros exigem a licença de marca branca estendida para o Docs Developer.

Essa distinção é importante porque alterar um arquivo de tema não substituirá automaticamente o logotipo do cabeçalho, e definir o objeto do logotipo não alterará a cor do restante do editor.

Etapa 2: prepare os arquivos de logotipo para cabeçalhos claros e escuros.

Crie um logotipo amplo e simples que permaneça legível com uma altura de cabeçalho de 20 pixels. A documentação da API especifica um tamanho de imagem de 300×20 para as variantes padrão da imagem de cabeçalho. Use artes diferentes para fundos claros e escuros quando a sua marca perder contraste. Por exemplo, uma logomarca em azul-marinho escuro pode funcionar bem em um cabeçalho claro, mas desaparecer em um tema escuro; uma variante branca ou clara resolve esse problema.

Hospede as imagens em URLs HTTPS estáveis ​​que o editor consiga carregar. Evite URLs assinadas de curta duração se o logotipo precisar estar sempre disponível. Teste também os arquivos usando o mesmo caminho de rede e a mesma política de segurança do navegador que os usuários reais.

Etapa 3: adicione o logotipo à sua configuração da API de Documentos.

const config = {
  editorConfig: {
    customization: {
      logo: {
        image: "https://app.example.com/branding/logo.png",
        imageDark: "https://app.example.com/branding/logo-dark.png",
        imageLight: "https://app.example.com/branding/logo-light.png",
        url: "https://www.example.com",
        visible: true
      }
    }
  }
};

const docEditor = new DocsAPI.DocEditor("placeholder", config);

imageé o logotipo padrão do modo de trabalho. imageDarké para um cabeçalho escuro ou colorido, e imageLighté para um cabeçalho claro, como o tema Cinza. urlcontrola para onde o clique leva ao logotipo; defina-o como uma string vazia ou nullse o logotipo não deve ser clicável. visiblecontrola se o logotipo é exibido.

Etapa 4: verifique o logotipo em condições de luz e escuridão.

Abra um documento real através da sua integração e verifique o cabeçalho com o zoom normal do navegador. Um resultado satisfatório não se resume apenas ao carregamento do arquivo. O logotipo deve estar nítido, centralizado verticalmente, legível na altura compacta do cabeçalho e sem caixas de fundo inesperadas. Verifique também se o clique funciona conforme o esperado.

Em seguida, mude para um modo de interface escuro e repita a verificação. Se o logotipo ficar com baixo contraste, use um imageDarkrecurso específico em vez de tentar forçar um único gráfico a funcionar em todos os lugares.

Etapa 5: criar um tema de cores personalizado em JSON

Para cores da interface, crie um arquivo de tema cujo idnome comece com `.`. Somente theme-documentos do OFFICE aceitam tipos de tema válidos e suportam cores em notação hexadecimal ou RGBA. Não confunda isso com um esquema de cores de documento: este JSON altera a própria interface do editor, não as cores do tema armazenadas dentro de um arquivo DOCX, XLSX ou PPTX.lightdark

{
  "name": "Northstar Light",
  "id": "theme-northstar-light",
  "type": "light",
  "colors": {
    "toolbar-header-document": "#1E3A8A",
    "toolbar-header-spreadsheet": "#166534",
    "toolbar-header-presentation": "#B45309",
    "background-normal": "#FFFFFF",
    "background-accent-button": "#1E3A8A",
    "text-normal": "#1F2937",
    "icon-normal": "#374151"
  }
}

Os valores acima são uma paleta de exemplo, não um tema ONLYOFFICE predefinido. Os nomes dos parâmetros são variáveis ​​de tema documentadas. Em produção, comece com um pequeno conjunto de valores de alto impacto, visualize o resultado e expanda apenas conforme necessário. Isso facilita a identificação de baixo contraste ou estados inconsistentes.

Passo 6: coloque o arquivo de tema no diretório de temas do Servidor de Documentos.

A ONLYOFFICE documenta estes locais para arquivos de temas personalizados:

• Linux: /var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes
• Windows: %ProgramFiles%\ONLYOFFICE\DocumentServer\web-apps\apps\common\main\resources\themes
• Docker: copie o JSON para o mesmo caminho dentro do contêiner Docs.

sudo docker cp northstar-theme.json onlyoffice:/var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes/

Substitua onlyofficepelo nome ou ID real do seu contêiner. Se sua implantação for reconstruída com frequência, não confie em uma cópia única como sua única fonte de verdade. Incorpore o tema ao seu processo de implantação, personalização de imagem ou outro mecanismo persistente apropriado ao seu ambiente, para que atualizações e substituições de contêineres não o removam silenciosamente.

Passo 7: atualize a página, aguarde o cache e selecione o tema personalizado.

O guia oficial observa que o cache do servidor para a solicitação do tema tem uma duração de cinco minutos. Após inserir o arquivo, aguarde esse período e atualize o editor. Em alguns casos, a ONLYOFFICE também recomenda reiniciar os serviços e limpar o cache se o tema não aparecer.

Após o carregamento, o tema deverá aparecer na lista de temas da interface nas configurações avançadas. Selecione-o e examine mais do que apenas o cabeçalho. Verifique os menus, as caixas de diálogo, as abas selecionadas, os estados de foco, os controles desativados, os ícones, os indicadores de notificação e o contraste do texto.

Etapa 8: valide a marca finalizada como um sistema, não apenas como uma captura de tela.

Uma boa identidade visual personalizada deve resistir ao uso normal do editor. Abra um documento, planilha, apresentação e PDF, se esses editores estiverem disponíveis. Teste as caixas de diálogo e os controles de colaboração mais comuns. Verifique os modos claro e escuro, caso ofereça ambos. Confira o foco do teclado, os estados desativados, o contraste ao passar o mouse e os nomes longos dos arquivos. Uma cor atraente no cabeçalho ainda pode dificultar a leitura de uma aba selecionada ou de um texto secundário.

Como saber se a personalização está funcionando

Você pode considerar a implementação bem-sucedida quando o logotipo configurado aparecer de forma consistente, a variante correta do logotipo permanecer legível no cabeçalho ativo, o tema personalizado aparecer no seletor de temas, as cores da marca forem renderizadas sem comprometer o contraste do texto ou dos ícones e a experiência permanecer utilizável em todos os tipos de editor que seus usuários realmente abrirem.

Se o logotipo não mudar mesmo que o objeto de configuração esteja sendo passado corretamente, primeiro confirme a edição e a licença, pois a referência da API indica que o parâmetro do logotipo é exclusivo para desenvolvedores do Docs. Se o tema de cores não aparecer, verifique o ID e a sintaxe do JSON, a localização do arquivo, a persistência do contêiner, o tempo de cache e o estado do serviço. Se um tema carregar, mas parecer incorreto, reduza a personalização a um conjunto menor de variáveis ​​documentadas e adicione cores gradualmente.

Limites comuns e erros

Personalizar a identidade visual do editor não é o mesmo que personalizar a identidade visual do DocSpace ou do Workspace.

O ONLYOFFICE possui superfícies de personalização separadas. Este guia trata especificamente da personalização da identidade visual do editor de documentos do ONLYOFFICE. Os controles de identidade visual do portal, nomes de locatários, favicons do portal e a navegação adjacente pertencem às configurações do DocSpace ou Workspace, e não ao objeto de logotipo do cabeçalho da API de Documentos.

Um esquema de cores de documento não é um tema de interface.

Os esquemas de cores do documento afetam o conteúdo, como texto, tabelas, gráficos e formas. Um tema de interface personalizado controla elementos da interface do editor, como barras de ferramentas, painéis, botões, ícones, bordas e rótulos. Escolha o mecanismo que melhor se adapta à superfície que deseja alterar.

Não assuma que todos os controles de marca branca estejam incluídos na personalização padrão.

A ONLYOFFICE separa a identidade visual padrão dos parâmetros estendidos de marca branca. Se você precisar de maior controle sobre itens como fontes da interface, visibilidade do layout ou elementos relacionados à página "Sobre", verifique os requisitos de licença atuais na documentação oficial de marca branca antes de planejar a implementação.

Lista de verificação prática para implantação

• Confirme com o desenvolvedor do ONLYOFFICE Docs se você precisa da personalização do logotipo do cabeçalho descrita aqui.
• Crie logotipos de 300×20, incluindo variantes claras e escuras onde o contraste for necessário.
• Configure editorConfig.customization.logona camada de integração.
• Crie um JSON de tema personalizado válido com um ID que comece com theme-.
• Coloque o arquivo de tema no diretório de temas do Document Server, conforme documentado.
• Para implantações Docker ou imutáveis, torne a instalação do tema repetível e persistente.
• Aguarde o atraso de cache documentado, atualize a página e selecione o tema.
• Teste o contraste, os estados, os tipos de editor e as condições de luz e escuridão antes de implementar amplamente.

Ao manter a identidade visual da marca, os temas da interface e os controles de marca branca estendidos conceitualmente separados, o ONLYOFFICE Docs torna-se muito mais fácil de personalizar de forma previsível. Comece com a menor alteração que atinja a adequação à marca desejada, verifique-a em condições reais de edição e somente então expanda o tema.

Referências oficiais

• API do ONLYOFFICE Docs: Personalização – Identidade visual padrão
• Central de Ajuda do ONLYOFFICE: Alterando temas de interface no ONLYOFFICE Docs
• API do ONLYOFFICE Docs: Personalização – Marca branca