Hoe u ONLYOFFICE-documenten kunt personaliseren met uw logo en kleuren

Het kortste antwoord: gebruik de huisstijl van Docs API voor het logo en een aangepast interfacethema voor de kleuren.

Als je de OnlyOffice Docs-editor eruit wilt laten zien als een onderdeel van je eigen product, is de meest overzichtelijke configuratie een aanpassing in twee stappen: configureer de editorConfig.customization.logointegratie in de Docs API voor het logo in de header en voeg vervolgens een aangepast thema-JSON-bestand toe aan de documentserver voor de kleuren van de editor. Dit zijn aparte mechanismen met verschillende beschikbaarheidsregels.

Zoals geverifieerd aan de hand van de ONLYOFFICE-documentatie op 7 oktober 2026, logois de parameter editor-header alleen beschikbaar voor ONLYOFFICE Docs Developer. De officiële API specificeert afbeeldingen van 300×20 voor image, imageDark, en imageLight, met een aanbevolen logohoogte van 20 pixels. Aangepaste interfacethema's worden daarentegen ondersteund sinds ONLYOFFICE Docs v7.0 en worden geïnstalleerd als JSON-themabestanden op de Document Server. De huidige officiële referentie is de standaard brandingdocumentatie van ONLYOFFICE Docs en de workflow voor themabestanden is gedocumenteerd in Changing interface themes in ONLYOFFICE Docs .

Deze aanpak is geschikt voor teams die ONLYOFFICE Docs in hun eigen webapplicatie integreren en de documentserver beheren. Het is niet hetzelfde als het wijzigen van het thema van een DocSpace- of Workspace-portaal. Als het uw doel is om het omringende portaal aan te passen in plaats van de editor zelf, gebruik dan de huisstijlinstellingen van dat product.

Stap 1: Bepaal wat je daadwerkelijk wilt branden.

Voordat je bestanden bewerkt, kun je de branding van het ontwerp het beste in drie vragen onderverdelen. Heb je alleen een logo nodig in de header van de editor? Wil je de merkkleuren ook terugzien in toolbars, knoppen, tekst, randen en panelen? Of wil je een uitgebreidere white-label-ervaring waarbij je ook andere interface-elementen aanpast?

• Headerlogo: gebruik editorConfig.customization.logo. ONLYOFFICE markeert deze parameter als alleen voor ontwikkelaars.
• Interfacekleuren: installeer een aangepast thema-JSON-bestand op de documentserver. Dit is de juiste manier om merkkleuren te implementeren.
• Uitgebreidere white-label-instellingen: raadpleeg de uitgebreide white-label-documentatie . ONLYOFFICE geeft aan dat voor deze parameters de uitgebreide white-label-licentie voor Docs Developer vereist is.

Dit onderscheid is belangrijk omdat het wijzigen van een themabestand het headerlogo niet automatisch vervangt, en het instellen van het logo-object de rest van de editor niet van kleur verandert.

Stap 2: bereid de logo-bestanden voor de lichte en donkere headers voor.

Maak een breed, eenvoudig logo dat leesbaar blijft bij een hoogte van 20 pixels in de header. De API-documentatie specificeert een afbeeldingsformaat van 300×20 voor de standaard header-afbeeldingen. Gebruik aparte afbeeldingen voor donkere en lichte achtergronden wanneer uw merklogo aan contrast zou verliezen. Een donkerblauw woordmerk kan bijvoorbeeld goed werken op een lichte header, maar verdwijnen op een donker thema; een witte of lichte variant biedt hiervoor een oplossing.

Plaats de afbeeldingen op stabiele HTTPS-URL's die de editor kan laden. Vermijd kortstondige, ondertekende URL's als het logo continu beschikbaar moet zijn. Test de bestanden ook via hetzelfde netwerkpad en met hetzelfde browserbeveiligingsbeleid als echte gebruikers.

Stap 3: voeg het logo toe aan uw Docs API-configuratie

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);

imageis het standaard werkmoduslogo. imageDarkis voor een donkere of gekleurde header, en imageLightis voor een lichte header zoals het grijze thema. urlbepaalt waar een klik op het logo naartoe gaat; stel dit in op een lege tekenreeks of nullals het logo niet klikbaar moet zijn. visiblebepaalt of het logo wordt weergegeven.

Stap 4: controleer het logo zowel in lichte als in donkere omstandigheden.

Open een echt document via uw integratie en controleer de header bij een normale browserzoom. Een succesvol resultaat is niet alleen "het bestand is geladen". Het logo moet scherp zijn, verticaal gecentreerd, leesbaar bij de compacte headerhoogte en vrij van ongewenste achtergrondvakken. Controleer ook of een klik zich gedraagt ​​zoals bedoeld.

Schakel vervolgens over naar een donkere interface en herhaal de controle. Als het logo dan een laag contrast heeft, gebruik dan een apart imageDarkelement in plaats van te proberen één afbeelding overal te laten werken.

Stap 5: maak een aangepast kleurenthema aan in JSON-formaat.

Voor interfacekleuren maakt u een themabestand aan dat idbegint met theme-. ONLYOFFICE-documenten lighten darkals geldige thematypen en dat kleuren in hexadecimale of RGBA-notatie ondersteunt. Verwar dit niet met een kleurenschema voor documenten: deze JSON wijzigt de editor-interface zelf, niet de themakleuren die zijn opgeslagen in een DOCX-, XLSX- of PPTX-bestand.

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

De bovenstaande waarden zijn een voorbeeldpalet, geen voorgeschreven ONLYOFFICE-thema. De parameternamen zijn gedocumenteerde themavariabelen. Begin in een productieomgeving met een kleine set waarden met een grote impact, bekijk het resultaat in een voorbeeldweergave en breid het palet vervolgens alleen uit indien nodig. Dit maakt het gemakkelijker om een ​​slecht contrast of inconsistenties op te sporen.

Stap 6: Plaats het themabestand in de thema-directory van de Document Server.

ONLYOFFICE documenteert de volgende locaties voor aangepaste themabestanden:

• Linux: /var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes
• Windows: %ProgramFiles%\ONLYOFFICE\DocumentServer\web-apps\apps\common\main\resources\themes
• Docker: kopieer de JSON naar hetzelfde pad in de Docs-container.

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

Vervang dit onlyofficedoor de daadwerkelijke naam of ID van uw container. Als uw implementatie regelmatig opnieuw wordt opgebouwd, vertrouw dan niet alleen op een eenmalige kopie als enige bron van waarheid. Voeg het thema toe aan uw implementatieproces, image-aanpassing of een ander persistent mechanisme dat geschikt is voor uw omgeving, zodat upgrades en containervervangingen het thema niet ongemerkt verwijderen.

Stap 7: vernieuw de pagina, wacht tot de cache geladen is en selecteer het aangepaste thema.

De officiële handleiding vermeldt dat de servercache voor het themaverzoek een levensduur van vijf minuten heeft. Nadat u het bestand hebt geplaatst, moet u deze vertraging afwachten en de editor vernieuwen. In sommige gevallen raadt ONLYOFFICE ook aan om services opnieuw te starten en de cache te wissen als het thema niet verschijnt.

Zodra het thema is geladen, zou het in de lijst met interfacethema's in de geavanceerde instellingen moeten verschijnen. Selecteer het en bekijk meer dan alleen de header. Controleer menu's, dialoogvensters, geselecteerde tabbladen, hover-effecten, uitgeschakelde besturingselementen, pictogrammen, notificatiebadges en tekstcontrast.

Stap 8: Valideer het voltooide merk als een systeem, niet slechts als een screenshot.

Een goede, op maat gemaakte huisstijl moet bestand zijn tegen normaal gebruik in tekstverwerkers. Open een document, spreadsheet, presentatie of pdf (indien beschikbaar). Test de meest gebruikte dialoogvensters en samenwerkingsopties. Controleer zowel de lichte als de donkere modus (indien beschikbaar). Controleer de toetsenbordfocus, de uitgeschakelde status, het hovercontrast en lange bestandsnamen. Een aantrekkelijke kleur in de header kan er nog steeds voor zorgen dat een geselecteerd tabblad of secundaire tekst moeilijk leesbaar is.

Hoe weet ik of de aanpassingen werken?

Je kunt de implementatie als geslaagd beschouwen wanneer het geconfigureerde logo consistent wordt weergegeven, de juiste logovariant leesbaar blijft in de actieve header, het aangepaste thema in de themakiezer verschijnt, de merkkleuren worden weergegeven zonder het contrast van tekst of pictogrammen te verstoren, en de gebruikerservaring bruikbaar blijft in alle editortypen die je gebruikers daadwerkelijk openen.

Als het logo nooit verandert, ondanks dat het configuratieobject correct wordt doorgegeven, controleer dan eerst de editie en licentie, aangezien de API-referentie de logoparameter als 'alleen voor Docs-ontwikkelaars' markeert. Als het kleurenthema nooit verschijnt, controleer dan de JSON-ID en -syntaxis, de bestandslocatie, de persistentie van de container, de cachetiming en de servicestatus. Als een thema wel laadt, maar er verkeerd uitziet, beperk dan de aanpassingen tot een kleinere set gedocumenteerde variabelen en voeg kleuren stapsgewijs toe.

Veelvoorkomende grenzen en veelgemaakte fouten

Het vormgeven van de editor is niet hetzelfde als het vormgeven van de merkidentiteit van DocSpace of Workspace.

ONLYOFFICE heeft aparte aanpassingsmogelijkheden. Deze handleiding gaat specifiek over de branding van de ONLYOFFICE Docs-editor. De instellingen voor portalbranding, tenantnamen, portalfavicons en de bijbehorende navigatie behoren tot de DocSpace- of Workspace-instellingen, niet tot het logo-object in de header van de Docs API.

Een kleurenschema voor een document is geen interfacethema.

De kleurenschema's van documenten beïnvloeden de inhoud, zoals tekst, tabellen, grafieken en vormen. Een aangepast interfacethema bepaalt de UI-elementen van de editor, zoals toolbars, panelen, knoppen, pictogrammen, randen en labels. Kies het mechanisme dat past bij het oppervlak dat u wilt wijzigen.

Ga er niet van uit dat elke white-label-component standaard bij de branding is inbegrepen.

ONLYOFFICE scheidt standaard branding van uitgebreide white-label parameters. Als u meer controle wilt over zaken zoals interfacelettertypen, zichtbaarheid van de lay-out of elementen met betrekking tot 'Over ons', controleer dan de huidige licentievoorwaarden in de officiële white-label referentie voordat u de implementatie plant.

Praktische checklist voor de implementatie

• Neem contact op met ONLYOFFICE Docs Developer als u de hier beschreven aanpassing van het headerlogo nodig heeft.
• Maak logo's van 300×20 pixels, inclusief lichte en donkere varianten waar contrast dit vereist.
• Configureer dit editorConfig.customization.logoin de integratielaag.
• Maak een geldige aangepaste thema-JSON aan met een ID die begint met theme-.
• Plaats het themabestand in de gedocumenteerde themamap van de Document Server.
• Voor Docker- of immutable-implementaties moet de thema-installatie herhaalbaar en persistent zijn.
• Houd rekening met de aangegeven cachevertraging, vernieuw vervolgens de pagina en selecteer het thema.
• Test het contrast, de status, de editortypes en zowel de licht- als de donkeromstandigheden voordat je de functie op grote schaal uitrolt.

Door logo-branding, interface-thema's en uitgebreide white-label-besturingselementen conceptueel gescheiden te houden, wordt het aanpassen van ONLYOFFICE Docs veel eenvoudiger en voorspelbaarder. Begin met de kleinste wijziging die de gewenste merkidentiteit oplevert, test deze in een realistische editoromgeving en breid het thema pas daarna uit.

Officiële referenties

• ONLYOFFICE Docs API: Aanpassing – Standaard huisstijl
• ONLYOFFICE Helpcentrum: Interfacethema's wijzigen in ONLYOFFICE Docs
• ONLYOFFICE Docs API: Aanpassing – White label