So gestalten Sie ONLYOFFICE Docs mit Ihrem Logo und Ihren Farben individuell

Die kürzeste Antwort: Verwenden Sie das Branding der Docs API für das Logo und ein benutzerdefiniertes Oberflächendesign für die Farben.

Wenn Sie den ONLYOFFICE Docs-Editor optisch in Ihr eigenes Produkt integrieren möchten, empfiehlt sich eine zweistufige Anpassung: Konfigurieren Sie zunächst editorConfig.customization.logodas Header-Logo in der Docs-API-Integration und fügen Sie anschließend eine benutzerdefinierte Design-JSON-Datei für die Editorfarben auf dem Dokumentenserver hinzu. Es handelt sich dabei um separate Mechanismen mit unterschiedlichen Verfügbarkeitsregeln.

Wie am 7. Oktober 2026 anhand der ONLYOFFICE-Dokumentation überprüft wurde, logoist der Parameter „editor-header“ nur für ONLYOFFICE Docs Developer verfügbar. Die offizielle API spezifiziert 300×20 Pixel große Bilder für image<img>, imageDark<img> und imageLight<img> mit einer empfohlenen Logohöhe von 20 Pixeln. Benutzerdefinierte Oberflächendesigns werden seit ONLYOFFICE Docs v7.0 unterstützt und als JSON-Designdateien auf dem Dokumentenserver installiert. Die aktuelle offizielle Referenz ist die ONLYOFFICE Docs-Standard-Branding-Dokumentation . Der Workflow für Designdateien ist unter „ Ändern von Oberflächendesigns in ONLYOFFICE Docs“ beschrieben .

Dieser Ansatz eignet sich für Teams, die ONLYOFFICE Docs in ihre eigene Webanwendung einbinden und den Dokumentenserver verwalten. Er ist nicht mit dem Ändern des Designs eines DocSpace- oder Workspace-Portals vergleichbar. Wenn Sie das übergeordnete Portal und nicht den Editor selbst ändern möchten, verwenden Sie stattdessen die Branding-Einstellungen des jeweiligen Produkts.

Schritt 1: Prüfen Sie, was Sie tatsächlich branden müssen.

Bevor Sie Dateien bearbeiten, sollten Sie die Branding-Oberfläche anhand von drei Fragen unterteilen. Benötigen Sie nur ein Logo in der Editor-Kopfzeile? Möchten Sie die Markenfarben auch in Symbolleisten, Schaltflächen, Texten, Rahmen und Bedienfeldern verwenden? Oder benötigen Sie eine umfassendere White-Label-Lösung, die zusätzliche Oberflächenelemente verändert?

• Logo im Header: Verwenden Sie editorConfig.customization.logo. ONLYOFFICE kennzeichnet diesen Parameter als nur für Entwickler bestimmt.
• Farben der Benutzeroberfläche: Installieren Sie eine benutzerdefinierte Design-JSON-Datei auf dem Dokumentenserver. Dies ist der richtige Mechanismus für Markenfarben.
• Erweiterte White-Label-Steuerung: Beachten Sie die ausführliche White-Label-Dokumentation . ONLYOFFICE gibt an, dass für diese Parameter die erweiterte White-Label-Lizenz für Docs Developer erforderlich ist.

Diese Unterscheidung ist wichtig, weil das Ändern einer Designdatei nicht automatisch das Header-Logo ersetzt und das Festlegen des Logo-Objekts nicht den Rest des Editors neu einfärbt.

Schritt 2: Logodateien für helle und dunkle Header vorbereiten

Erstellen Sie ein breites, einfaches Logo, das auch bei einer Headerhöhe von 20 Pixeln gut lesbar ist. Die API-Dokumentation empfiehlt eine Bildgröße von 300 × 20 Pixel für die Standard-Headerbildvarianten. Verwenden Sie separate Grafiken für dunkle und helle Hintergründe, wenn Ihr Markenzeichen sonst an Kontrast verlieren würde. Beispielsweise kann ein dunkelblaues Wortlogo auf einem hellen Header gut sichtbar sein, aber auf einem dunklen Hintergrund verschwinden; eine weiße oder helle Variante löst dieses Problem.

Laden Sie die Bilder unter stabilen HTTPS-URLs hoch, die der Editor laden kann. Vermeiden Sie kurzlebige signierte URLs, wenn das Logo dauerhaft verfügbar sein muss. Testen Sie die Assets außerdem über denselben Netzwerkpfad und dieselbe Browser-Sicherheitsrichtlinie, die auch von echten Nutzern verwendet wird.

Schritt 3: Fügen Sie das Logo Ihrer Docs-API-Konfiguration hinzu.

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

imageist das Standardlogo für den Arbeitsmodus. imageDarkist für dunkle oder farbige Kopfzeilen und imageLightfür helle Kopfzeilen wie das graue Design. urlsteuert das Ziel eines Klicks auf das Logo; geben Sie hier eine leere Zeichenkette ein oder , nullwenn das Logo nicht anklickbar sein soll. visiblesteuert, ob das Logo angezeigt wird.

Schritt 4: Überprüfen Sie das Logo sowohl bei hellen als auch bei dunklen Lichtverhältnissen.

Öffnen Sie ein echtes Dokument über Ihre Integration und prüfen Sie die Kopfzeile bei normaler Browser-Zoomstufe. Ein erfolgreiches Ergebnis bedeutet nicht nur, dass die Datei geladen wurde. Das Logo sollte scharf, vertikal zentriert und in der kompakten Kopfzeilenhöhe gut lesbar sein und keine unerwünschten Hintergrundrahmen aufweisen. Prüfen Sie außerdem, ob ein Klick wie erwartet funktioniert.

Wechseln Sie anschließend zu einer dunklen Benutzeroberfläche und wiederholen Sie die Überprüfung. Falls das Logo zu kontrastarm wird, verwenden Sie ein separates imageDarkElement, anstatt zu versuchen, eine einzige Grafik überall verwenden zu können.

Schritt 5: Erstellen eines benutzerdefinierten Farbthemas (JSON)

Für die Benutzeroberflächenfarben erstellen Sie eine Designdatei, deren idName mit „.OFFICE“ beginnt theme-. Nur Office-Dokumente lightund darkdie Dateitypen DOCX, XLSX oder PPTX sind als gültige Designtypen zulässig. Die Datei unterstützt Farben in Hexadezimal- oder RGBA-Notation. Verwechseln Sie dies nicht mit einem Dokumentfarbschema: Die JSON-Datei ändert die Benutzeroberfläche des Editors selbst, nicht die in einer DOCX-, XLSX- oder PPTX-Datei gespeicherten Designfarben.

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

Die oben genannten Werte stellen eine Beispielpalette dar und sind kein vorgegebenes ONLYOFFICE-Design. Die Parameternamen sind dokumentierte Designvariablen. Im Produktivbetrieb empfiehlt es sich, mit wenigen, aber aussagekräftigen Werten zu beginnen, das Ergebnis in der Vorschau zu überprüfen und den Bereich erst bei Bedarf zu erweitern. So lassen sich mangelnder Kontrast oder inkonsistente Zustände leichter erkennen.

Schritt 6: Platzieren Sie die Designdatei im Designverzeichnis des Dokumentenservers.

ONLYOFFICE dokumentiert diese Speicherorte für benutzerdefinierte Designdateien:

• Linux: /var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes
• Windows: %ProgramFiles%\ONLYOFFICE\DocumentServer\web-apps\apps\common\main\resources\themes
• Docker: Kopieren Sie die JSON-Datei in denselben Pfad innerhalb des Docs-Containers.

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

Ersetzen Sie dies onlyofficedurch Ihren tatsächlichen Containernamen oder Ihre Container-ID. Wenn Ihre Bereitstellung häufig neu erstellt wird, sollten Sie sich nicht ausschließlich auf eine einmalige Kopie verlassen. Integrieren Sie das Design in Ihren Bereitstellungsprozess, die Image-Anpassung oder einen anderen persistenten Mechanismus, der für Ihre Umgebung geeignet ist, damit es bei Aktualisierungen und Containeraustausch nicht unbemerkt entfernt wird.

Schritt 7: Aktualisieren, auf das Laden des Caches warten und das benutzerdefinierte Design auswählen.

Die offizielle Anleitung weist darauf hin, dass der Server-Cache für die Theme-Anfrage fünf Minuten lang gültig ist. Warten Sie nach dem Einfügen der Datei diese kurze Zeit ab und aktualisieren Sie den Editor. In manchen Fällen empfiehlt ONLYOFFICE außerdem, die Dienste neu zu starten und den Cache zu leeren, falls das Theme nicht angezeigt wird.

Nach dem Laden sollte das Design in der Liste der Benutzeroberflächendesigns in den erweiterten Einstellungen erscheinen. Wählen Sie es aus und untersuchen Sie nicht nur die Kopfzeile. Prüfen Sie Menüs, Dialogfelder, ausgewählte Registerkarten, Hover-Zustände, deaktivierte Steuerelemente, Symbole, Benachrichtigungs-Badges und den Textkontrast.

Schritt 8: Validieren Sie die fertige Marke als System, nicht nur als Screenshot.

Eine gut gestaltete Benutzeroberfläche sollte auch bei normaler Nutzung im Editor zuverlässig funktionieren. Öffnen Sie ein Dokument, eine Tabellenkalkulation, eine Präsentation und ein PDF, sofern diese Editoren verfügbar sind. Testen Sie gängige Dialogfelder und Funktionen für die Zusammenarbeit. Überprüfen Sie die Darstellung im hellen und dunklen Modus, falls Sie beides anbieten. Achten Sie auf Tastaturfokus, deaktivierte Funktionen, Kontrast beim Überfahren mit der Maus und lange Dateinamen. Eine ansprechende Farbe in der Kopfzeile kann die Lesbarkeit eines ausgewählten Tabs oder von Sekundärtexten beeinträchtigen.

Woran man erkennt, ob die Anpassung funktioniert

Die Implementierung kann als erfolgreich betrachtet werden, wenn das konfigurierte Logo konsistent angezeigt wird, die korrekte Logovariante im aktiven Header lesbar bleibt, das benutzerdefinierte Design in der Designauswahl erscheint, die Markenfarben ohne Beeinträchtigung des Text- oder Symbolkontrasts dargestellt werden und die Benutzererfahrung über alle Editortypen hinweg, die Ihre Benutzer tatsächlich öffnen, hinweg nutzbar bleibt.

Wenn sich das Logo trotz korrekter Übergabe des Konfigurationsobjekts nicht ändert, überprüfen Sie zunächst Edition und Lizenz, da der Logo-Parameter laut API-Referenz nur für Docs Developer zugänglich ist. Wird das Farbschema nicht angezeigt, überprüfen Sie JSON-ID und -Syntax, Dateispeicherort, Container-Persistenz, Cache-Timing und Dienststatus. Wird ein Design zwar geladen, sieht aber fehlerhaft aus, reduzieren Sie die Anpassung auf wenige dokumentierte Variablen und fügen Sie die Farben schrittweise hinzu.

Gemeinsame Grenzen und Fehler

Die Gestaltung des Editor-Brandings ist nicht dasselbe wie die Gestaltung von DocSpace oder Workspace.

ONLYOFFICE bietet separate Anpassungsmöglichkeiten. Dieser Leitfaden behandelt speziell das Branding des ONLYOFFICE Docs-Editors. Die Steuerelemente für das Portal-Branding, Mandantennamen, Portal-Favicons und die zugehörige Navigation gehören zu den DocSpace- oder Workspace-Einstellungen und nicht zum Header-Logo der Docs-API.

Ein Dokumentfarbschema ist kein Benutzeroberflächendesign.

Dokumentfarbschemata beeinflussen Inhalte wie Text, Tabellen, Diagramme und Formen. Ein benutzerdefiniertes Oberflächendesign steuert die UI-Elemente des Editors, z. B. Symbolleisten, Bedienfelder, Schaltflächen, Symbole, Rahmen und Beschriftungen. Wählen Sie den Mechanismus, der der gewünschten Oberfläche entspricht.

Gehen Sie nicht davon aus, dass jedes White-Label-Steuergerät im Standard-Branding enthalten ist.

ONLYOFFICE trennt Standard-Branding von erweiterten White-Label-Parametern. Benötigen Sie eine umfassendere Kontrolle über Elemente wie Schriftarten, Layout-Sichtbarkeit oder Info-Elemente, prüfen Sie bitte vor der Implementierung die aktuellen Lizenzbestimmungen in der offiziellen White-Label-Referenz .

Checkliste für den praktischen Einsatz

• Bitte bestätigen Sie dies bei ONLYOFFICE Docs Developer, wenn Sie die hier beschriebene Anpassung des Header-Logos benötigen.
• Erstellen Sie Logo-Assets im Format 300×20, inklusive heller und dunkler Varianten, wo dies aufgrund des Kontrasts erforderlich ist.
• Konfiguration editorConfig.customization.logoin der Integrationsschicht.
• Erstellen Sie eine gültige benutzerdefinierte Design-JSON-Datei mit einer ID, die mit . beginnt theme-.
• Platzieren Sie die Designdatei im dokumentierten Designverzeichnis des Document Servers.
• Bei Docker- oder unveränderlichen Bereitstellungen sollte die Theme-Installation wiederholbar und persistent sein.
• Bitte berücksichtigen Sie die dokumentierte Cache-Verzögerung, aktualisieren Sie anschließend die Seite und wählen Sie das gewünschte Design aus.
• Testen Sie Kontrast, Zustände, Editortypen sowie helle und dunkle Bedingungen, bevor Sie die breite Anwendung einführen.

Wenn Sie Logo-Branding, Interface-Design und erweiterte White-Label-Steuerelemente konzeptionell trennen, lässt sich ONLYOFFICE Docs deutlich einfacher und vorhersehbarer anpassen. Beginnen Sie mit der kleinsten Änderung, die die gewünschte Markenkonformität erreicht, testen Sie diese unter realen Bearbeitungsbedingungen und erweitern Sie das Design erst dann.

Offizielle Referenzen

• ONLYOFFICE Docs API: Anpassung – Standardbranding
• ONLYOFFICE-Hilfezentrum: Ändern von Benutzeroberflächendesigns in ONLYOFFICE Docs
• ONLYOFFICE Docs API: Anpassung – White Label