Gestalten Sie Ihre Dokumente mit Ihrem Logo und Ihren Designfarben – ONLYOFFICE Docs

Um einen eingebetteten ONLYOFFICE Docs-Editor anzupassen, weisen Sie ihm ein eigenes Farbschema zu und übergeben Sie Ihre Logo-URLs in der Initialisierungskonfiguration. Das Farbschema ist eine JSON-Datei, die auf dem Docs-Server installiert wird; das Logo wird von der Anwendung konfiguriert, die den Editor einbettet. Die dokumentierte Option „Header-Logo“ ist nur in ONLYOFFICE Docs Developer verfügbar. Prüfen Sie daher Ihre Edition, bevor Sie die Assets vorbereiten.

Dies gilt für eine selbstgehostete Docs-Integration, nicht für DocSpace-Branding oder die lokale Designauswahl von Desktop Editors. ONLYOFFICE verwendet benutzerdefinierte Designs aus Docs v7.0. Diese Einstellungen betreffen die Benutzeroberfläche des eingebetteten Editors, nicht den Dokumentinhalt oder die Website-Navigation.

Was sollten Sie zuerst vorbereiten?

Erstellen Sie zwei Dateien für das Logo: eine Version, die sich gut von einem hellen Header abhebt, und eine invertierte Version für einen dunklen oder farbigen Header. Die Dokumentation der API gibt ein 300 × 20 Pixel großes Bild für das Editor-Header-Logo an. Verwenden Sie ein transparentes PNG, falls dies zu Ihrem Design passt, und achten Sie auf einen hohen Kontrast und wenige Details, da das Bild in einem schmalen Streifen erscheint. Laden Sie beide Dateien auf stabile HTTPS-Adressen hoch, die vom Browser des Editor-Nutzers geladen werden können.

Sie benötigen außerdem Schreibzugriff auf den Server, den Code zur Erstellung der Editorkonfiguration und ein Testdokument. Ermitteln Sie bei Docker den Namen oder die ID des laufenden Containers. Testen Sie die Änderung zunächst in einer Nichtproduktionsumgebung.

1. Erstellen Sie eine Design-JSON-Datei für Ihre Farben.

Eine Theme-JSON-Datei ist eine Einstellungsdatei, die benannte Farb-Tokens der Benutzeroberfläche Farbwerten zuordnet. Die Tokens idmüssen eindeutig sein und mit einem Komma beginnen theme-; die nameangezeigten Farben werden Benutzern in der Theme-Auswahl angezeigt. Wählen Sie eine helle oder dunkle Basisfarbe, die zur gewünschten Benutzeroberfläche passt, und ersetzen Sie anschließend die Headerfarben und die ausgewählten Akzentfarben. Das folgende Beispiel verwendet einen hellen Hintergrund für den Editor, Indigo für die Editor-Header und Koralle für die Akzentschaltfläche des Dokumenteditors.

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

Speichern Sie es unter einem anderen Namen acme-brand-light.json. Die Header-Farben sind für Dokumente, Tabellenkalkulationen, Präsentationen und PDFs separat. Legen Sie jede Farbe einzeln fest, um ein einheitliches Erscheinungsbild über alle Dateitypen hinweg zu gewährleisten. Die hier gezeigte Akzentfarbe wirkt sich auf die Akzentschaltfläche des Texteditors aus, nicht auf alle farbigen Elemente in Docs. ONLYOFFICE bietet zusätzliche Farben für Hintergründe, Rahmen, Hover-Effekte, Symbole, Text und die Bearbeitungsfläche. Erweitern Sie die Farbpalette daher nur, wenn Sie diese Bereiche benötigen. Überprüfen Sie vor der Veröffentlichung den Kontrast von Text und Symbolen vor dem Hintergrund der gewählten Hintergründe. Eine Markenfarbe allein garantiert keine gute Lesbarkeit der Steuerelemente.

Die vollständige Liste der unterstützten Token und die erforderlichen JSON-Felder finden Sie in der offiziellen ONLYOFFICE-Referenz für benutzerdefinierte Designs .

2. Installieren Sie das Theme auf dem Docs-Server.

Kopieren Sie die JSON-Datei in das Theme-Verzeichnis des Servers. Die offizielle Linux- und Docker-Dokumentation gibt folgenden Pfad an:

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

Bei einer Docker-Bereitstellung legen Sie die Datei in das Verzeichnis, aus dem Sie den Befehl ausführen, und ersetzen Sie dann <Name> CONTAINER_IDdurch den Namen oder die ID des laufenden Docs-Containers:

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

Unter Linux kopieren Sie die Datei mit einem Benutzerkonto mit Schreibrechten in den angegebenen Pfad. Unter Windows verwenden Sie das Verzeichnis „themes“ unter %ProgramFiles%\ONLYOFFICE\DocumentServer; den vollständigen Pfad finden Sie in der Installationsanleitung. Ein benutzerdefiniertes Theme ist eine hinzugefügte JSON-Datei und keine Änderung der mitgelieferten Anwendungsdateien.

ONLYOFFICE gibt an, dass der Theme-Cache alle fünf Minuten aktualisiert wird. Aktualisieren Sie den Editor nach dem Kopieren der Datei. Falls die Datei weiterhin fehlt, befolgen Sie die Anweisungen zur Fehlerbehebung im Docker- oder Linux-Cache und starten Sie Dienste nur bei Bedarf neu. Fügen Sie die Datei für Produktionscontainer Ihrem Image oder Ihrer Bereitstellungsautomatisierung hinzu, damit sie beim Austausch eines Containers nicht gelöscht wird.

3. Design anwenden und Editor-Logo festlegen

Nachdem das Design ermittelt wurde, können Benutzer es unter „Ansicht > Benutzeroberflächendesign“editorConfig.customization auswählen. Damit Ihr eingebetteter Editor mit diesem Design startet, fügen Sie dessen ID dem Konfigurationsobjekt hinzu, das Ihre Anwendung an die Docs-API übergibt. Legen Sie das Logo im selben Objekt fest .

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

Ersetzen Sie die Beispiel-URLs durch Ihre tatsächlichen öffentlichen Asset- und Ziel-URLs. logo.imageist der Standard-Logopfad für gängige Editormodi; mit den separaten Feldern für helles und dunkles Logo können Sie die Grafik für eine dunkle oder helle Kopfzeile auswählen. Die URL gibt an, wohin ein Klick auf das Logo führen soll. Die API listet diese Kopfzeilen-Logo-Einstellung als Funktion für Docs Developer auf und legt die Größe 300 × 20 fest. Verwechseln Sie diese nicht mit customer.logo, einem größeren Bild, das in den „Über“-Informationen des Editors verwendet wird.

Wenn Ihre Integration Editorkonfigurationen mit JWT signiert, erstellen Sie die Signatur nach dem Hinzufügen oder Ändern dieser signierten Felder neu und bewahren Sie das Signaturgeheimnis auf dem Server auf. Das offizielle ONLYOFFICE-Integrationsbeispiel erklärt, dass das Token mit der Konfiguration übereinstimmen und bei Änderungen der signierten Parameter neu generiert werden muss. Beachten Sie außerdem, dass das zuvor vom Benutzer ausgewählte Design Vorrang haben kann uiTheme. Testen Sie dies mit einem neuen Browserprofil oder setzen Sie die gespeicherten Designeinstellungen des Benutzers zurück, falls das gewünschte Standarddesign nicht angezeigt wird.

Informationen zu Logo-Eigenschaften, Größen und verfügbaren Editionen finden Sie in der offiziellen Referenz zur Standard-Branding-Konfiguration .

Überprüfen Sie das Ergebnis vor der Einführung.

Öffnen Sie die Dateitypen, die Ihre Benutzer benötigen. Überprüfen Sie die Headerfarben, die Lesbarkeit von Text und Symbolen, das korrekte Logo in hellen und dunklen Headern sowie das Klickziel des Logos. Prüfen Sie die Bearbeitungs- und Ansichtsmodi im tatsächlichen eingebetteten Layout.

Falls das Theme fehlt, überprüfen Sie JSON und ID, prüfen Sie das Theme-Verzeichnis des aktiven Servers und warten Sie, bis der Cache aktualisiert wurde. Falls das Logo fehlt, prüfen Sie die Anforderungen der Developer Edition, den Zugriff des Browsers auf die Bild-URL und ob die Initialisierungskonfiguration die erforderlichen Informationen enthält logo. Generieren Sie das JWT im Backend neu, falls Sie signierte Felder geändert haben.