Personalize o ONLYOFFICE Docs com seu logotipo e cores temáticas.

Para personalizar um editor ONLYOFFICE Docs incorporado, atribua a ele um tema de cores da sua marca e inclua os URLs do seu logotipo na configuração de inicialização. O tema é um arquivo JSON instalado no servidor Docs; o logotipo é configurado pelo aplicativo que incorpora o editor. A opção de logotipo no cabeçalho, conforme documentado, está disponível apenas no ONLYOFFICE Docs Developer; portanto, confirme sua edição antes de preparar os recursos.

Isso se aplica a uma integração do Docs hospedada localmente, não à identidade visual do DocSpace ou ao seletor de temas local dos Editores de Desktop. O ONLYOFFICE documenta temas personalizados do Docs v7.0. Essas configurações afetam a interface do editor incorporado, não o conteúdo do documento ou a navegação do seu site.

O que você deve preparar primeiro?

Reúna dois arquivos para o logotipo: uma versão legível em um cabeçalho claro e uma versão invertida para um cabeçalho escuro ou colorido. A API de Documentação especifica uma imagem de 300 × 20 pixels para o logotipo do cabeçalho do editor. Use um PNG transparente, se for adequado para sua arte, e mantenha um logotipo de alto contraste com poucos detalhes finos, pois a imagem aparece em uma faixa estreita. Hospede ambos os arquivos em endereços HTTPS estáveis ​​que o navegador do usuário do editor possa carregar.

Você também precisa de acesso de escrita ao servidor, do código que gera a configuração do editor e de um documento de teste. Para o Docker, identifique o nome ou o ID do contêiner em execução. Teste a alteração primeiro em um ambiente de não produção.

1. Crie um arquivo JSON de tema para suas cores.

Um arquivo JSON de tema é um arquivo de configurações que mapeia tokens de cores de interface nomeados para valores de cores. O token iddeve ser único e começar com `<nome_do_tema> theme-`; o token nameé o que os usuários veem no seletor de temas. Escolha uma base clara ou escura que combine com a interface geral desejada e, em seguida, substitua as cores do cabeçalho e os destaques selecionados. O exemplo abaixo mantém o fundo do editor claro, usa índigo para cada cabeçalho do editor e usa coral para o botão de destaque do editor de documentos.

{
  "name": "Acme Brand Light",
  "id": "theme-acme-brand-light",
  "type": "light",
  "colors": {
    "toolbar-header-document": "#263B67",
    "toolbar-header-spreadsheet": "#263B67",
    "toolbar-header-presentation": "#263B67",
    "toolbar-header-pdf": "#263B67",
    "text-toolbar-header": "#fff",
    "background-accent-button": "#D8613C"
  }
}

Salve como acme-brand-light.json. Os tokens de cor do cabeçalho são separados para documentos, planilhas, apresentações e PDFs; defina cada um se desejar uma identidade visual consistente em todos os tipos de arquivo. O token de destaque mostrado aqui afeta o botão de destaque do editor de texto, não todos os elementos coloridos no Docs. A ONLYOFFICE documenta tokens de cor adicionais para planos de fundo, bordas, estados de foco, ícones, texto e a tela de edição; portanto, expanda a paleta somente quando precisar dessas áreas. Verifique o contraste do texto e dos ícones com os planos de fundo escolhidos antes da publicação; uma cor de marca por si só não garante controles legíveis.

Para obter a lista completa de tokens suportados e os campos JSON necessários, consulte a referência oficial de temas personalizados do ONLYOFFICE .

2. Instale o tema no servidor de documentação.

Copie o arquivo JSON para o diretório de temas do servidor. A documentação oficial do Linux e do Docker indica este caminho:

/var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes

Para uma implantação em Docker, coloque o arquivo no diretório de onde você executará o comando e substitua `<nome_do_container>` CONTAINER_IDpelo nome ou ID do container Docs em execução:

docker cp ./acme-brand-light.json CONTAINER_ID:/var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes/

No Linux, copie o arquivo para esse caminho usando uma conta com permissão de gravação. No Windows, use o diretório de temas em %ProgramFiles%\ONLYOFFICE\DocumentServer; consulte o guia de instalação para obter o caminho completo. Um tema personalizado é um arquivo JSON adicional, não uma edição dos arquivos incluídos no aplicativo.

O ONLYOFFICE informa que o cache de temas é atualizado a cada cinco minutos. Atualize o editor após copiar o arquivo; se ele ainda estiver faltando, siga as instruções de solução de problemas de cache do Docker ou do Linux e reinicie os serviços somente se necessário. Para contêineres de produção, inclua o arquivo em sua imagem ou automação de implantação para que a substituição de um contêiner não o remova.

3. Aplique o tema e defina o logotipo do editor.

Após o tema ser descoberto, os usuários podem selecioná-lo em Exibir > Tema da Interface . Para que o editor incorporado inicie com esse tema, adicione o ID dele ao objeto de configuração que seu aplicativo passa para a API de Documentação. Defina o logotipo dentro do mesmo editorConfig.customizationobjeto:

editorConfig: {
  customization: {
    uiTheme: "theme-acme-brand-light",
    logo: {
      image: "https://assets.example.com/logo-light.png",
      imageDark: "https://assets.example.com/logo-dark.png",
      imageLight: "https://assets.example.com/logo-light.png",
      url: "https://www.example.com"
    }
  }
}

Substitua os URLs de exemplo pelos URLs reais do seu recurso público e do destino. logo.imageé o caminho padrão do logotipo para os modos de edição mais comuns; os campos separados para escuro e claro permitem que você escolha a arte para um cabeçalho escuro ou claro. O URL é para onde um clique no logotipo deve levar. A API lista essa configuração de logotipo do cabeçalho como um recurso do Docs Developer e especifica o tamanho de 300 × 20. Não confunda com customer.logo, que é uma imagem maior usada nas informações "Sobre" do editor.

Se a sua integração assina as configurações do editor com JWT, reconstrua a assinatura após adicionar ou alterar esses campos assinados e mantenha o segredo de assinatura no servidor. O exemplo oficial de integração do ONLYOFFICE explica que o token deve corresponder à configuração e ser regenerado quando os parâmetros assinados forem alterados. Observe também que o tema previamente selecionado pelo usuário pode ter precedência sobre o tema padrão uiTheme; teste com um novo perfil de navegador ou redefina a preferência de tema salva do usuário se o tema padrão solicitado não for exibido.

Para informações sobre tamanhos de propriedades do logotipo e disponibilidade de edições, consulte a referência oficial de configuração de marca padrão .

Verifique o resultado antes da implementação.

Abra os tipos de arquivo que seus usuários precisam. Confirme as cores do cabeçalho, a legibilidade do texto e dos ícones, o logotipo correto nos cabeçalhos claros e escuros e o local onde o logotipo deve ser clicado. Verifique os modos de edição e visualização no layout incorporado.

Se o tema estiver faltando, valide o JSON e o ID, verifique o diretório de temas do servidor ativo e aguarde a atualização do cache. Se o logotipo estiver faltando, verifique o requisito da edição Developer, o acesso do navegador ao URL da imagem e se a configuração de inicialização inclui o arquivo logo. Regenere o JWT no backend se você alterou os campos assinados.