Documenti ONLYOFFICE personalizzati con il tuo logo e i colori del tuo tema.

Per personalizzare un editor ONLYOFFICE Docs incorporato, assegnategli un tema di colori personalizzato e passate gli URL del vostro logo nella configurazione di inizializzazione. Il tema è un file JSON installato sul server Docs; il logo viene configurato dall'applicazione che incorpora l'editor. L'opzione per il logo nell'intestazione, documentata, è disponibile solo in ONLYOFFICE Docs Developer, quindi verificate la vostra versione prima di preparare le risorse.

Questo si applica a un'integrazione di Documenti self-hosted, non al marchio DocSpace o al selettore di temi locali di Desktop Editors. ONLYOFFICE documenta temi personalizzati da Documenti v7.0. Queste impostazioni influiscono sull'interfaccia dell'editor incorporato, non sul contenuto del documento o sulla navigazione del sito Web.

Cosa bisogna preparare per prima cosa?

Procuratevi due file per il logo: una versione leggibile chiaramente su un'intestazione chiara e una versione invertita per un'intestazione scura o colorata. L'API di Docs specifica un'immagine di 300 × 20 pixel per il logo dell'intestazione dell'editor. Utilizzate un'immagine PNG trasparente se si adatta alla vostra grafica e mantenete un'immagine ad alto contrasto con pochi dettagli fini, poiché l'immagine appare in una striscia stretta. Ospitate entrambi i file su indirizzi HTTPS stabili che il browser dell'utente dell'editor possa caricare.

È inoltre necessario disporre dei permessi di scrittura sul server, del codice che crea la configurazione dell'editor e di un documento di prova. Per Docker, è necessario identificare il nome o l'ID del container in esecuzione. Testare prima la modifica in un ambiente non di produzione.

1. Crea un file JSON del tema per i tuoi colori

Un file JSON del tema è un file di impostazioni che mappa i token di colore dell'interfaccia denominati ai valori di colore. I token iddevono essere univoci e iniziare con theme-; il tema nameè ciò che gli utenti vedono nel selettore del tema. Scegli una base chiara o scura che si adatti all'interfaccia generale desiderata, quindi sostituisci i colori dell'intestazione e gli accenti selezionati. L'esempio seguente mantiene lo sfondo dell'editor chiaro, utilizza l'indaco per ogni intestazione dell'editor e utilizza il corallo per il pulsante di accento dell'editor di documenti.

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

Salvalo come acme-brand-light.json. I token di colore dell'intestazione sono separati per documenti, fogli di calcolo, presentazioni e PDF; impostali uno per uno se desideri un'immagine coordinata tra i diversi tipi di file. Il token di accento mostrato qui influisce sul pulsante di accento dell'editor di documenti di testo, non su tutti gli elementi colorati in Documenti. ONLYOFFICE documenta ulteriori token di colore per sfondi, bordi, stati al passaggio del mouse, icone, testo e area di modifica, quindi espandi la tavolozza solo quando hai bisogno di queste aree. Verifica il contrasto del testo e delle icone rispetto agli sfondi scelti prima della pubblicazione; un colore di marca da solo non garantisce controlli leggibili.

Per l'elenco completo dei token supportati e i campi JSON richiesti, consultare la documentazione ufficiale dei temi personalizzati di ONLYOFFICE .

2. Installa il tema sul server Docs

Copia il file JSON nella directory dei temi del server. La documentazione ufficiale di Linux e Docker indica questo percorso:

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

Per una distribuzione Docker, posiziona il file nella directory da cui eseguirai il comando, quindi sostituisci CONTAINER_IDcon il nome o l'ID del container Docs in esecuzione:

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

Su Linux, copia il file in quel percorso con un account con permessi di scrittura. Su Windows, usa la directory dei temi in %ProgramFiles%\ONLYOFFICE\DocumentServer; consulta la guida all'installazione per il percorso completo. Un tema personalizzato è un file JSON aggiunto, non una modifica ai file dell'applicazione inclusa.

ONLYOFFICE afferma che la cache dei temi si aggiorna ogni cinque minuti. Aggiorna l'editor dopo aver copiato il file; se il file risulta ancora mancante, segui le istruzioni per la risoluzione dei problemi della cache di Docker o Linux e riavvia i servizi solo se necessario. Per i container di produzione, includi il file nell'immagine o nell'automazione del deployment in modo che la sostituzione di un container non lo rimuova.

3. Applica il tema e imposta il logo dell'editor

Una volta individuato il tema, gli utenti possono selezionarlo da Visualizza > Tema interfaccia . Per fare in modo che l'editor incorporato si avvii con quel tema, aggiungi il suo ID all'oggetto di configurazione che l'applicazione passa all'API Docs. Imposta il logo all'interno dello stesso editorConfig.customizationoggetto:

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

Sostituisci gli URL di esempio con gli URL effettivi delle tue risorse pubbliche e di destinazione. logo.imageè il percorso standard del logo per le modalità di modifica comuni; i campi separati per scuro e chiaro consentono di scegliere l'immagine per un'intestazione scura o chiara. L'URL è dove dovrebbe essere indirizzato un clic sul logo. L'API elenca questa impostazione del logo dell'intestazione come funzionalità per sviluppatori della documentazione e specifica le dimensioni 300 × 20. Non confonderla con customer.logo, che è un'immagine più grande utilizzata nelle informazioni "Informazioni" dell'editor.

Se la tua integrazione firma le configurazioni dell'editor con JWT, ricostruisci la firma dopo aver aggiunto o modificato questi campi firmati e conserva il segreto di firma sul server. L' esempio di integrazione ufficiale di ONLYOFFICE spiega che il token deve corrispondere alla configurazione e deve essere rigenerato quando i parametri firmati cambiano. Tieni presente inoltre che il tema precedentemente selezionato da un utente può avere la precedenza uiTheme; prova con un nuovo profilo del browser o ripristina la preferenza del tema salvata da quell'utente se il tema predefinito richiesto non viene visualizzato.

Per informazioni sulle dimensioni e le edizioni disponibili del logo, consultare il documento di riferimento ufficiale sulla configurazione standard del marchio .

Verificare il risultato prima dell'implementazione.

Apri i tipi di file necessari ai tuoi utenti. Verifica i colori dell'intestazione, la leggibilità del testo e delle icone, la correttezza del logo nelle intestazioni chiare e scure e la destinazione del clic sul logo. Controlla le modalità di modifica e visualizzazione nel layout incorporato effettivo.

Se il tema non è presente, convalida il JSON e l'ID, controlla la directory dei temi del server attivo e attendi l'aggiornamento della cache. Se il logo non è presente, verifica i requisiti dell'edizione Developer, l'accesso del browser all'URL dell'immagine e se la configurazione di inizializzazione include logo. Rigenera il JWT sul backend se hai modificato i campi firmati.