Jak dostosować dokumenty ONLYOFFICE do swojej marki, dodając logo i kolory

Najkrótsza odpowiedź: użyj brandingu API Dokumentów dla logo i niestandardowego motywu interfejsu dla kolorów

Jeśli chcesz, aby edytor ONLYOFFICE Docs wyglądał jak część Twojego produktu, najczystszym rozwiązaniem jest dwuwarstwowa konfiguracja: skonfiguruj editorConfig.customization.logologo nagłówka w integracji API Docs, a następnie dodaj plik JSON motywu niestandardowego na serwerze dokumentów dla kolorów edytora. To oddzielne mechanizmy i mają różne zasady dostępności.

Zgodnie z dokumentacją ONLYOFFICE z 7 października 2026 r., logoparametr editor-header jest dostępny tylko dla ONLYOFFICE Docs Developer. Oficjalny interfejs API określa obrazy o wymiarach 300×20 dla image, imageDarki imageLight, z zalecaną wysokością logo 20 pikseli. Niestandardowe motywy interfejsu są obsługiwane od wersji 7.0 ONLYOFFICE Docs i są instalowane jako pliki motywów JSON na serwerze dokumentów. Aktualnym oficjalnym dokumentem jest standardowa dokumentacja brandingu ONLYOFFICE Docs , a przepływ pracy z plikami motywów opisano w dokumencie „ Zmiana motywów interfejsu w ONLYOFFICE Docs” .

To podejście jest odpowiednie dla zespołów, które osadzają ONLYOFFICE Docs we własnej aplikacji internetowej i kontrolują Serwer Dokumentów. Nie jest to to samo, co zmiana motywu portalu DocSpace lub Workspace. Jeśli celem jest otaczający portal, a nie sam edytor, należy użyć ustawień brandingu tego produktu.

Krok 1: potwierdź, co faktycznie musisz oznaczyć marką

Przed edycją plików podziel powierzchnię brandingu na trzy pytania. Czy potrzebujesz logo tylko w nagłówku edytora? Czy chcesz, aby kolory marki znalazły się również na paskach narzędzi, przyciskach, w tekście, obramowaniach i panelach? A może potrzebujesz bardziej zaawansowanego rozwiązania white-label, które zmienia dodatkowe elementy interfejsu?

• Logo nagłówka: użyj editorConfig.customization.logo. ONLYOFFICE oznacza ten parametr jako Tylko dla programistów.
• Kolory interfejsu: zainstaluj niestandardowy motyw JSON na serwerze dokumentów. To właściwy mechanizm dla kolorów marki.
• Bardziej szczegółowe kontrole typu white-label: zapoznaj się z rozszerzoną dokumentacją white-label . ONLYOFFICE stwierdza, że ​​te parametry wymagają rozszerzonej licencji white-label dla Docs Developer.

To rozróżnienie jest istotne, ponieważ zmiana pliku motywu nie spowoduje automatycznej zamiany logo w nagłówku, a ustawienie obiektu logo nie spowoduje zmiany koloru reszty edytora.

Krok 2: przygotuj pliki logo dla jasnych i ciemnych nagłówków

Przygotuj szerokie, proste logo, które pozostanie czytelne przy wysokości nagłówka 20 pikseli. Dokumentacja API określa rozmiar obrazu 300×20 dla standardowych wariantów obrazu nagłówka. Użyj osobnej grafiki dla ciemnego i jasnego tła, gdy znak Twojej marki straciłby na kontraście. Na przykład, ciemnogranatowy logotyp może pasować do jasnego nagłówka, ale znikać w ciemnym motywie; biała lub jasna wersja rozwiązuje ten problem.

Przechowuj obrazy pod stabilnymi adresami URL HTTPS, które edytor może załadować. Unikaj krótkotrwałych, podpisanych adresów URL, jeśli logo musi być stale dostępne. Przetestuj również zasoby za pośrednictwem tej samej ścieżki sieciowej i polityki bezpieczeństwa przeglądarki, z której korzystają prawdziwi użytkownicy.

Krok 3: dodaj logo do konfiguracji interfejsu API Dokumentów

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

imagejest popularnym logo trybu pracy. imageDarkdotyczy ciemnego lub kolorowego nagłówka, a imageLightjasnego nagłówka, takiego jak motyw Szary. urlokreśla, gdzie kierowane jest kliknięcie na logo; ustaw na pusty ciąg lub nullokreśl, czy logo nie powinno być klikalne. visibleokreśla, czy logo jest wyświetlane.

Krok 4: sprawdź logo zarówno w warunkach jasnych, jak i ciemnych

Otwórz prawdziwy dokument za pomocą integracji i sprawdź nagłówek w normalnym powiększeniu przeglądarki. Udany wynik to nie tylko „załadowany plik”. Logo powinno być ostre, wyśrodkowane w pionie, czytelne na niewielkiej wysokości nagłówka i pozbawione nieoczekiwanych ramek tła. Sprawdź również, czy kliknięcie działa zgodnie z oczekiwaniami.

Następnie przełącz interfejs na ciemny i powtórz sprawdzanie. Jeśli logo stanie się mało kontrastowe, użyj dedykowanego imageDarkzasobu, zamiast próbować na siłę wyświetlać jedną grafikę wszędzie.

Krok 5: utwórz niestandardowy motyw kolorów JSON

W przypadku kolorów interfejsu utwórz plik motywu, którego idnazwa zaczyna się od theme-. ONLYOFFICE light, darkjako prawidłowe typy motywu i obsługujący kolory w notacji szesnastkowej lub RGBA. Nie należy tego mylić ze schematem kolorów dokumentu: ten kod JSON zmienia sam chrom edytora, a nie kolory motywu zapisane w pliku DOCX, XLSX lub 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"
  }
}

Powyższe wartości to przykładowa paleta, a nie określony motyw ONLYOFFICE. Nazwy parametrów to udokumentowane zmienne motywu. W środowisku produkcyjnym należy zacząć od małego zestawu wartości o dużym wpływie, wyświetlić podgląd rezultatu, a następnie rozszerzać go tylko w razie potrzeby. Ułatwia to wykrycie słabego kontrastu lub niespójnych stanów.

Krok 6: umieść plik motywu w katalogu motywu Serwera dokumentów

ONLYOFFICE dokumentuje następujące lokalizacje plików motywów niestandardowych:

• Linux: /var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes
• Okna: %ProgramFiles%\ONLYOFFICE\DocumentServer\web-apps\apps\common\main\resources\themes
• Docker: skopiuj JSON do tej samej ścieżki w kontenerze Docs.

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

Zastąp je onlyofficerzeczywistą nazwą lub identyfikatorem kontenera. Jeśli wdrożenie jest często przebudowywane, nie polegaj na jednorazowej kopii jako jedynym źródle informacji. Umieść motyw w procesie wdrażania, dostosowywaniu obrazu lub innym trwałym mechanizmie odpowiednim dla Twojego środowiska, aby aktualizacje i wymiana kontenera nie spowodowały jego bezgłośnego usunięcia.

Krok 7: odśwież, poczekaj na pamięć podręczną i wybierz motyw niestandardowy

Oficjalny przewodnik informuje, że pamięć podręczna serwera dla żądania motywu ma pięciominutowy okres ważności. Po umieszczeniu pliku należy uwzględnić to opóźnienie i odświeżyć edytor. W niektórych przypadkach ONLYOFFICE zaleca również ponowne uruchomienie usług i wyczyszczenie pamięci podręcznej, jeśli motyw się nie pojawi.

Po załadowaniu motyw powinien pojawić się na liście motywów interfejsu w Ustawieniach zaawansowanych. Wybierz go i sprawdź nie tylko nagłówek. Sprawdź menu, okna dialogowe, wybrane karty, stany najechania kursorem, wyłączone elementy sterujące, ikony, plakietki powiadomień i kontrast tekstu.

Krok 8: zatwierdź gotową markę jako system, a nie tylko zrzut ekranu

Dobra, spersonalizowana marka powinna przetrwać normalne użytkowanie edytora. Otwórz dokument, arkusz kalkulacyjny, prezentację i plik PDF, jeśli te edytory są w zasięgu. Wypróbuj popularne okna dialogowe i narzędzia do współpracy. Sprawdź zarówno jasność, jak i ciemność, jeśli oferujesz oba. Sprawdź fokus klawiatury, stany wyłączone, kontrast najechania kursorem i długie nazwy plików. Kolor, który wygląda atrakcyjnie w nagłówku, nadal może utrudniać odczytanie wybranej zakładki lub tekstu pomocniczego.

Jak sprawdzić, czy personalizacja działa

Wdrożenie można uznać za udane, gdy skonfigurowane logo pojawia się spójnie, prawidłowa odmiana logo jest czytelna w aktywnym nagłówku, niestandardowy motyw jest widoczny w selektorze motywów, kolory marki są wyświetlane bez zakłócania kontrastu tekstu lub ikon, a doświadczenie użytkownika pozostaje użyteczne we wszystkich typach edytora, które faktycznie otwierają użytkownicy.

Jeśli logo nigdy się nie zmienia, mimo że obiekt konfiguracji jest poprawnie przekazywany, najpierw sprawdź edycję i licencję, ponieważ w referencjach API parametr logo jest oznaczony jako „Docs Developer-only”. Jeśli motyw kolorów nigdy się nie pojawia, sprawdź identyfikator JSON i składnię, lokalizację pliku, trwałość kontenera, czas buforowania i stan usługi. Jeśli motyw ładuje się, ale wygląda nieprawidłowo, ogranicz dostosowanie do mniejszego zestawu udokumentowanych zmiennych i dodawaj kolory stopniowo.

Typowe granice i błędy

Branding edytora nie jest tym samym, co branding DocSpace lub Workspace

ONLYOFFICE ma osobne powierzchnie personalizacji. Ten przewodnik dotyczy konkretnie brandingu edytora dokumentów ONLYOFFICE. Elementy sterujące brandingiem portalu, nazwy dzierżawców, ikony portalu i otaczająca je nawigacja należą do ustawień DocSpace lub Workspace, a nie do obiektu logo nagłówka API Dokumentów.

Schemat kolorów dokumentu nie jest motywem interfejsu

Schematy kolorów dokumentów wpływają na zawartość, taką jak tekst, tabele, wykresy i kształty. Niestandardowy motyw interfejsu kontroluje elementy interfejsu edytora, takie jak paski narzędzi, panele, przyciski, ikony, obramowania i etykiety. Wybierz mechanizm pasujący do powierzchni, którą chcesz zmienić.

Nie zakładaj, że każda kontrola białej etykiety jest objęta standardowym brandingiem

ONLYOFFICE oddziela standardowe elementy brandingu od rozszerzonych parametrów white-label. Jeśli potrzebujesz szerszej kontroli nad elementami, takimi jak czcionki interfejsu, widoczność układu lub elementy związane z sekcją „O nas”, sprawdź aktualne wymagania licencyjne w oficjalnym dokumencie white-label przed zaplanowaniem wdrożenia.

Lista kontrolna praktycznego wdrożenia

• Jeśli potrzebujesz dostosowania logo nagłówka opisanego tutaj, skontaktuj się z ONLYOFFICE Docs Developer.
• Utwórz zasoby logo o rozmiarze 300×20, w tym jasne i ciemne warianty, jeśli wymaga tego kontrast.
• Skonfiguruj editorConfig.customization.logow warstwie integracyjnej.
• Utwórz prawidłowy kod JSON motywu niestandardowego, którego identyfikator zaczyna się od theme-.
• Umieść plik motywu w udokumentowanym katalogu motywów serwera dokumentów.
• W przypadku wdrożeń Docker lub niezmiennych należy zadbać o to, aby instalacja motywu była powtarzalna i trwała.
• Zezwól na udokumentowane opóźnienie pamięci podręcznej, a następnie odśwież stronę i wybierz motyw.
• Przed szerokim wdrożeniem przetestuj kontrast, stany, typy edytorów oraz warunki oświetlenia i ciemności.

Gdy branding logo, motywy interfejsu i rozbudowane opcje white-label są koncepcyjnie oddzielone, ONLYOFFICE Docs staje się o wiele łatwiejszy do przewidywalnego dostosowania. Zacznij od najmniejszej zmiany, która zapewni pożądane dopasowanie do marki, zweryfikuj ją w rzeczywistych warunkach edytora, a dopiero potem rozbuduj motyw.

Oficjalne referencje

• ONLYOFFICE Docs API: Dostosowywanie – Standardowe oznakowanie
• Centrum pomocy ONLYOFFICE: Zmiana motywów interfejsu w dokumentach ONLYOFFICE
• ONLYOFFICE Docs API: Dostosowywanie – Biała etykieta