Come personalizzare i documenti ONLYOFFICE con il tuo logo e i tuoi colori.

La risposta più breve: usa il marchio Docs API per il logo e un tema di interfaccia personalizzato per i colori.

Se il tuo obiettivo è far sì che l'editor di ONLYOFFICE Docs si integri perfettamente con il tuo prodotto, la configurazione più pulita prevede una personalizzazione a due livelli: configura editorConfig.customization.logol'integrazione dell'API di Docs per il logo dell'intestazione, quindi aggiungi un file JSON di tema personalizzato sul Document Server per i colori dell'editor. Si tratta di meccanismi separati, con regole di disponibilità differenti.

Come verificato rispetto alla documentazione di ONLYOFFICE il 7 ottobre 2026, il logoparametro editor-header è disponibile solo per ONLYOFFICE Docs Developer. L'API ufficiale specifica immagini 300×20 per image, imageDark, e imageLight, con un'altezza del logo consigliata di 20 pixel. I temi di interfaccia personalizzati, invece, sono supportati dalla versione 7.0 di ONLYOFFICE Docs e vengono installati come file di tema JSON sul Document Server. Il riferimento ufficiale attuale è la documentazione standard di branding di ONLYOFFICE Docs e il flusso di lavoro dei file di tema è documentato in Modifica dei temi di interfaccia in ONLYOFFICE Docs .

Questo approccio è adatto ai team che integrano ONLYOFFICE Docs nella propria applicazione web e controllano il Document Server. Non è la stessa cosa di cambiare il tema di un portale DocSpace o Workspace. Se l'obiettivo è il portale in cui è inserito, anziché l'editor stesso, è necessario utilizzare le impostazioni di branding di quel prodotto.

Passaggio 1: conferma cosa devi effettivamente marchiare

Prima di modificare i file, suddividete l'area di branding in tre punti chiave. Vi serve solo un logo nell'intestazione dell'editor? Volete che i colori del brand siano presenti anche in barre degli strumenti, pulsanti, testo, bordi e pannelli? Oppure avete bisogno di un'esperienza white-label più completa che modifichi ulteriori elementi dell'interfaccia?

• Logo dell'intestazione: utilizzare editorConfig.customization.logo. ONLYOFFICE contrassegna questo parametro come riservato agli sviluppatori.
• Colori dell'interfaccia: installa un tema JSON personalizzato sul Document Server. Questo è il meccanismo corretto per i colori del marchio.
• Controlli white-label più avanzati: consultare la documentazione white-label estesa . ONLYOFFICE afferma che tali parametri richiedono la licenza white-label estesa per Docs Developer.

Questa distinzione è importante perché la modifica di un file del tema non sostituirà automaticamente il logo dell'intestazione e l'impostazione dell'oggetto logo non modificherà i colori del resto dell'editor.

Passaggio 2: preparare i file del logo per le intestazioni chiare e scure

Prepara un logo ampio e semplice che rimanga leggibile con un'altezza di 20 pixel nell'intestazione. La documentazione API specifica una dimensione di 300×20 pixel per le varianti standard dell'immagine di intestazione. Utilizza immagini diverse per sfondi scuri e chiari quando il tuo marchio perderebbe contrasto. Ad esempio, un logo blu scuro potrebbe funzionare su un'intestazione chiara ma scomparire su un tema scuro; una variante bianca o chiara risolve questo problema.

Ospita le immagini su URL HTTPS stabili che l'editor possa caricare. Evita URL firmati con validità limitata se il logo deve essere sempre disponibile. Inoltre, testa le risorse utilizzando lo stesso percorso di rete e le stesse impostazioni di sicurezza del browser utilizzate dagli utenti reali.

Passaggio 3: aggiungi il logo alla configurazione dell'API di Documenti

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è il logo comune della modalità di lavoro. imageDarkè per un'intestazione scura o colorata, e imageLightè per un'intestazione chiara come il tema Grigio. urlcontrolla dove viene indirizzato un clic sul logo; impostalo su una stringa vuota o nullse il logo non deve essere cliccabile. visiblecontrolla se il logo viene visualizzato.

Passaggio 4: verificare il logo sia in condizioni di luce che di buio

Apri un documento reale tramite la tua integrazione e controlla l'intestazione con lo zoom normale del browser. Un risultato positivo non si limita al semplice caricamento del file. Il logo deve essere nitido, centrato verticalmente, leggibile all'altezza compatta dell'intestazione e privo di riquadri di sfondo indesiderati. Verifica inoltre che il clic si comporti come previsto.

Passa quindi a un'interfaccia scura e ripeti il ​​controllo. Se il logo risulta a basso contrasto, utilizza una imageDarkrisorsa dedicata anziché cercare di adattare un'unica grafica a qualsiasi ambiente.

Passaggio 5: crea un tema di colori personalizzato JSON

Per i colori dell'interfaccia, crea un file tema che idinizia con theme-. I documenti ONLYOFFICE lightsono darktipi di tema validi e supportano colori in notazione esadecimale o RGBA. Non confonderlo con uno schema di colori del documento: questo JSON modifica l'aspetto dell'editor stesso, non i colori del tema memorizzati all'interno di un file DOCX, XLSX o PPTX.

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

I valori sopra riportati sono una tavolozza di esempio, non un tema ONLYOFFICE predefinito. I nomi dei parametri sono variabili del tema documentate. In produzione, iniziate con un piccolo set di valori ad alto impatto, visualizzate l'anteprima del risultato e poi espandete solo se necessario. Questo semplifica l'individuazione di contrasti insufficienti o incongruenze.

Passaggio 6: posizionare il file del tema nella directory dei temi del server di documenti.

ONLYOFFICE documenta queste posizioni per i file dei temi personalizzati:

• Linux: /var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes
• Windows: %ProgramFiles%\ONLYOFFICE\DocumentServer\web-apps\apps\common\main\resources\themes
• Docker: copia il file JSON nello stesso percorso all'interno del container Docs.

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

Sostituisci onlyofficecon il nome o l'ID effettivo del tuo container. Se la tua distribuzione viene ricostruita frequentemente, non affidarti a una singola copia come unica fonte di verità. Integra il tema nel processo di distribuzione, nella personalizzazione dell'immagine o in un altro meccanismo persistente appropriato al tuo ambiente, in modo che gli aggiornamenti e la sostituzione del container non lo rimuovano silenziosamente.

Passaggio 7: aggiorna, attendi il caricamento della cache e seleziona il tema personalizzato

La guida ufficiale indica che la cache del server per la richiesta del tema ha una durata di cinque minuti. Dopo aver inserito il file, attendere questo lasso di tempo e aggiornare l'editor. In alcuni casi, ONLYOFFICE consiglia anche di riavviare i servizi e svuotare la cache se il tema non viene visualizzato.

Una volta caricato, il tema dovrebbe apparire nell'elenco dei temi dell'interfaccia nelle impostazioni avanzate. Selezionalo ed esamina attentamente non solo l'intestazione. Controlla menu, finestre di dialogo, schede selezionate, stati al passaggio del mouse, controlli disabilitati, icone, badge di notifica e contrasto del testo.

Passaggio 8: convalidare il marchio finale come un sistema, non solo come uno screenshot.

Un buon marchio personalizzato dovrebbe resistere al normale utilizzo dell'editor. Apri un documento, un foglio di calcolo, una presentazione e un PDF, se questi editor sono inclusi. Prova le finestre di dialogo e i controlli di collaborazione più comuni. Verifica sia la modalità chiara che quella scura, se disponibili. Controlla il focus della tastiera, gli stati disabilitati, il contrasto al passaggio del mouse e i nomi dei file lunghi. Un colore che appare attraente nell'intestazione può comunque rendere difficile la lettura di una scheda selezionata o di un testo secondario.

Come capire se la personalizzazione funziona

L'implementazione può considerarsi riuscita quando il logo configurato viene visualizzato in modo coerente, la variante corretta del logo rimane leggibile nell'intestazione attiva, il tema personalizzato viene visualizzato nel selettore dei temi, i colori del marchio vengono riprodotti senza compromettere il contrasto del testo o delle icone e l'esperienza utente rimane fruibile in tutti i tipi di editor effettivamente aperti dagli utenti.

Se il logo non cambia mai, anche se l'oggetto di configurazione viene passato correttamente, verifica innanzitutto l'edizione e la licenza, poiché la documentazione API indica che il parametro del logo è riservato agli sviluppatori. Se il tema colore non viene visualizzato, verifica l'ID JSON e la sintassi, la posizione del file, la persistenza del contenitore, i tempi della cache e lo stato del servizio. Se un tema viene caricato ma ha un aspetto errato, riduci la personalizzazione a un insieme più piccolo di variabili documentate e aggiungi i colori gradualmente.

Confini comuni ed errori

Dare un marchio all'editor non è la stessa cosa che dare un marchio a DocSpace o Workspace.

ONLYOFFICE offre diverse interfacce di personalizzazione. Questa guida si concentra specificamente sulla personalizzazione del marchio nell'editor di documenti di ONLYOFFICE. I controlli di personalizzazione del portale, i nomi dei tenant, le favicon del portale e la navigazione circostante appartengono alle impostazioni di DocSpace o Workspace, non all'oggetto logo dell'intestazione dell'API di Documenti.

La combinazione di colori di un documento non è un tema di interfaccia

Le combinazioni di colori dei documenti influenzano contenuti come testo, tabelle, grafici e forme. Un tema di interfaccia personalizzato controlla gli elementi dell'interfaccia utente dell'editor, come barre degli strumenti, pannelli, pulsanti, icone, bordi ed etichette. Scegli il meccanismo che corrisponde all'aspetto che desideri modificare.

Non dare per scontato che ogni controllo white-label sia incluso nel marchio standard

ONLYOFFICE separa il branding standard dai parametri white-label estesi. Se hai bisogno di un controllo più ampio su elementi come i font dell'interfaccia, la visibilità del layout o gli elementi relativi alla sezione "Informazioni su di me", verifica i requisiti di licenza attuali nella documentazione ufficiale white-label prima di pianificare l'implementazione.

Lista di controllo per l'implementazione pratica

• Conferma con ONLYOFFICE Docs Developer se hai bisogno della personalizzazione del logo dell'intestazione descritta qui.
• Crea il logo in formato 300×20, incluse le varianti chiare e scure laddove il contrasto lo richieda.
• Configurare editorConfig.customization.logonel livello di integrazione.
• Crea un JSON di tema personalizzato valido con un ID che inizia con theme-.
• Posiziona il file del tema nella directory dei temi del server di documentazione.
• Per le implementazioni Docker o immutabili, rendi l'installazione del tema ripetibile e persistente.
• Attendi il ritardo di cache documentato, quindi aggiorna la pagina e seleziona il tema.
• Prima di implementare la funzionalità su larga scala, testa il contrasto, gli stati, i tipi di editor e sia le condizioni di luce che di buio.

Mantenendo separati concettualmente il logo, il tema dell'interfaccia e i controlli white-label avanzati, ONLYOFFICE Docs diventa molto più facile da personalizzare in modo prevedibile. Iniziate con la modifica più piccola che consenta di ottenere l'allineamento desiderato con il marchio, verificatela in condizioni di utilizzo reali e solo successivamente estendete il tema.

Riferimenti ufficiali

• API ONLYOFFICE Docs: Personalizzazione – Branding standard
• Centro assistenza ONLYOFFICE: Come modificare i temi dell'interfaccia in ONLYOFFICE Docs
• API ONLYOFFICE Docs: Personalizzazione – White label