Documents ONLYOFFICE personnalisés avec votre logo et vos couleurs thématiques

Pour personnaliser un éditeur ONLYOFFICE Docs intégré, attribuez-lui un thème de couleurs à votre marque et indiquez les URL de votre logo lors de sa configuration initiale. Le thème est un fichier JSON installé sur le serveur Docs ; le logo est configuré par l’application qui intègre l’éditeur. L’option de logo d’en-tête documentée est disponible uniquement dans ONLYOFFICE Docs Developer ; veuillez donc vérifier votre édition avant de préparer les ressources.

Ceci concerne l'intégration de Docs auto-hébergée, et non la personnalisation de DocSpace ni le sélecteur de thèmes local de Desktop Editors. ONLYOFFICE prend en charge les thèmes personnalisés de Docs v7.0. Ces paramètres affectent l'interface de l'éditeur intégré, et non le contenu des documents ni la navigation de votre site web.

Que devez-vous préparer en premier ?

Préparez deux fichiers pour le logo : une version lisible sur fond clair et une version inversée pour un fond foncé ou coloré. L’API Docs spécifie une image de 300 × 20 pixels pour le logo de l’éditeur. Utilisez un PNG transparent si cela convient à votre visuel, et privilégiez un logo à fort contraste avec peu de détails fins, car l’image apparaîtra dans une bande étroite. Hébergez les deux fichiers sur des adresses HTTPS stables et accessibles depuis le navigateur de l’utilisateur.

Vous aurez également besoin d'un accès en écriture au serveur, du code qui génère la configuration de l'éditeur et d'un document de test. Pour Docker, identifiez le nom ou l'ID du conteneur en cours d'exécution. Testez d'abord la modification dans un environnement hors production.

1. Créez un fichier JSON de thème pour vos couleurs.

Un fichier JSON de thème est un fichier de configuration qui associe des jetons de couleur d'interface nommés à des valeurs de couleur. Ces jetons iddoivent être uniques et commencer par theme-`<thème>`. C'est namece que les utilisateurs voient dans le sélecteur de thème. Choisissez une base claire ou foncée qui correspond à l'interface générale souhaitée, puis modifiez les couleurs d'en-tête et les accents sélectionnés. L'exemple ci-dessous conserve un fond clair pour l'éditeur, utilise l'indigo pour chaque en-tête et le corail pour le bouton d'accentuation de l'éditeur de documents.

{
  "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"
  }
}

Enregistrez-le sous le nom acme-brand-light.json. Les jetons de couleur d'en-tête sont distincts pour les documents, les feuilles de calcul, les présentations et les PDF ; définissez-les individuellement pour une identité visuelle cohérente sur tous les types de fichiers. Le jeton d'accentuation présenté ici affecte le bouton d'accentuation de l'éditeur de texte, et non tous les éléments colorés de Docs. ONLYOFFICE utilise des jetons de couleur supplémentaires pour les arrière-plans, les bordures, les effets de survol, les icônes, le texte et la zone d'édition ; n'étendez donc la palette que lorsque vous en avez besoin. Vérifiez le contraste du texte et des icônes par rapport aux arrière-plans choisis avant publication ; une couleur de marque seule ne garantit pas la lisibilité des commandes.

Pour obtenir la liste complète des jetons pris en charge et les champs JSON requis, consultez la documentation officielle des thèmes personnalisés ONLYOFFICE .

2. Installez le thème sur le serveur Docs

Copiez le fichier JSON dans le répertoire des thèmes du serveur. La documentation officielle Linux et Docker indique ce chemin :

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

Pour un déploiement Docker, placez le fichier dans le répertoire à partir duquel vous exécuterez la commande, puis remplacez CONTAINER_IDpar le nom ou l'ID du conteneur Docs en cours d'exécution :

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

Sous Linux, copiez le fichier à cet emplacement avec un compte disposant des droits d'écriture. Sous Windows, utilisez le répertoire « themes » situé sous%ProgramFiles%\ONLYOFFICE\DocumentServer ; consultez le guide d'installation pour connaître son chemin d'accès complet. Un thème personnalisé est un fichier JSON ajouté, et non une modification des fichiers système de l'application.

ONLYOFFICE indique que le cache du thème se met à jour toutes les cinq minutes. Actualisez l'éditeur après avoir copié le fichier ; s'il est toujours introuvable, suivez les instructions de dépannage du cache Docker ou Linux et redémarrez les services uniquement si nécessaire. Pour les conteneurs de production, incluez le fichier dans votre image ou votre automatisation de déploiement afin que le remplacement d'un conteneur ne le supprime pas.

3. Appliquez le thème et définissez le logo de l'éditeur

Une fois le thème détecté, les utilisateurs peuvent le sélectionner dans Affichage > Thème d'interface . Pour que votre éditeur intégré utilise ce thème par défaut, ajoutez son ID à l'objet de configuration transmis par votre application à l'API Docs. Définissez le logo dans ce même editorConfig.customizationobjet.

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"
    }
  }
}

Remplacez les URL d'exemple par vos URL publiques réelles de ressources et de destination. logo.imageest le chemin d'accès standard du logo pour les modes d'édition courants ; les champs clair et foncé vous permettent de choisir une image pour un en-tête clair ou foncé. L'URL correspond à l'adresse vers laquelle un clic sur le logo redirigera. L'API répertorie ce paramètre de logo d'en-tête comme une fonctionnalité pour développeurs de documents et spécifie une taille de 300 × 20. Ne le confondez pas avec customer.logo, qui est une image plus grande utilisée dans les informations « À propos » de l'éditeur.

Si votre intégration signe les configurations de l'éditeur avec JWT, régénérez la signature après chaque ajout ou modification de champs signés et conservez le secret de signature sur le serveur. L' exemple d'intégration officiel d'ONLYOFFICE explique que le jeton doit correspondre à la configuration et être régénéré lorsque les paramètres signés sont modifiés. Notez également que le thème précédemment sélectionné par l'utilisateur peut être prioritaireuiTheme ; effectuez un test avec un nouveau profil de navigateur ou réinitialisez la préférence de thème enregistrée de l'utilisateur si le thème par défaut demandé ne s'affiche pas.

Pour connaître les dimensions et la disponibilité des éditions des logos, veuillez consulter le document de référence officiel sur la configuration de la marque .

Vérifiez le résultat avant le déploiement

Ouvrez les types de fichiers nécessaires à vos utilisateurs. Vérifiez les couleurs des en-têtes, la lisibilité du texte et des icônes, l'exactitude du logo dans les en-têtes clairs et foncés, ainsi que la destination du clic sur le logo. Testez les modes d'édition et d'affichage dans la mise en page intégrée.

Si le thème est manquant, vérifiez le JSON et l'identifiant, consultez le répertoire des thèmes du serveur actif et attendez la mise à jour du cache. Si le logo est manquant, vérifiez la configuration requise pour l'édition Développeur, l'accès du navigateur à l'URL de l'image et la présence des éléments nécessaires dans la configuration initiale logo. Régénérez le JWT côté serveur si vous avez modifié des champs signés.