Oznacz dokumenty ONLYOFFICE swoim logo i kolorami motywu

Aby dostosować osadzony edytor ONLYOFFICE Docs, nadaj edytorowi firmowy motyw kolorystyczny i przekaż adresy URL swojego logo w konfiguracji inicjalizacyjnej. Motyw to plik JSON zainstalowany na serwerze Docs; logo jest konfigurowane przez aplikację, w której osadzony jest edytor. Udokumentowana opcja nagłówka-logo jest dostępna tylko w programie ONLYOFFICE Docs Developer, dlatego przed przygotowaniem zasobów należy potwierdzić wersję.

Dotyczy to integracji z Docs hostowanej na własnym serwerze, a nie brandingu DocSpace ani lokalnego selektora motywów w Desktop Editors. ONLYOFFICE to niestandardowe motywy dokumentów z Docs v7.0. Te ustawienia wpływają na interfejs osadzonego edytora, a nie na zawartość dokumentu ani na nawigację w witrynie.

Co należy przygotować w pierwszej kolejności?

Zbierz dwa pliki logo: wersję czytelną na jasnym nagłówku i wersję odwróconą na ciemny lub kolorowy nagłówek. Interfejs API Dokumentów określa obraz o wymiarach 300 × 20 pikseli dla logo nagłówka edytora. Użyj przezroczystego pliku PNG, jeśli pasuje do Twojej grafiki, i zachowaj znak o wysokim kontraście i niewielkiej ilości drobnych szczegółów, ponieważ obraz pojawia się w wąskim pasku. Przechowuj oba pliki pod stabilnymi adresami HTTPS, które przeglądarka użytkownika edytora może załadować.

Potrzebny jest również dostęp do zapisu na serwerze, kod, który buduje konfigurację edytora, oraz dokument testowy. W przypadku Dockera należy zidentyfikować nazwę lub identyfikator uruchomionego kontenera. Najpierw przetestuj zmianę w środowisku nieprodukcyjnym.

1. Utwórz plik JSON motywu dla swoich kolorów

Plik JSON motywu to plik ustawień, który mapuje nazwane tokeny kolorów interfejsu na wartości kolorów. idMusi być unikatowy i zaczynać się od theme-; to namewłaśnie to, co użytkownicy widzą w selektorze motywu. Wybierz jasną lub ciemną bazę, która pasuje do całego interfejsu, a następnie zastąp kolory nagłówka i wybrane akcenty. Poniższy przykład zachowuje jasne tło edytora, używa indygo dla każdego nagłówka edytora i koralowego dla przycisku akcentu edytora dokumentów.

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

Zapisz jako acme-brand-light.json. Tokeny kolorów nagłówka są oddzielne dla dokumentów, arkuszy kalkulacyjnych, prezentacji i plików PDF; ustaw każdy z nich, jeśli chcesz, aby marka była spójna we wszystkich typach plików. Pokazany tutaj token akcentu wpływa na przycisk akcentu w edytorze dokumentów tekstowych, a nie na każdy kolorowy element w Dokumentach. ONLYOFFICE oferuje dodatkowe tokeny kolorów dla tła, obramowań, stanów najechania kursorem, ikon, tekstu i obszaru roboczego edycji, więc rozszerzaj paletę tylko wtedy, gdy potrzebujesz tych obszarów. Przed publikacją sprawdź kontrast tekstu i ikon z wybranym tłem; sam kolor marki nie gwarantuje czytelności kontrolek.

Aby zapoznać się z pełną listą obsługiwanych tokenów i wymaganymi polami JSON, skorzystaj z oficjalnego dokumentu referencyjnego dotyczącego niestandardowych motywów ONLYOFFICE .

2. Zainstaluj motyw na serwerze Docs

Skopiuj plik JSON do katalogu motywów serwera. Oficjalna dokumentacja Linuksa i Dockera podaje następującą ścieżkę:

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

W przypadku wdrożenia Dockera umieść plik w katalogu, z którego uruchomisz polecenie, a następnie zastąp go CONTAINER_IDnazwą lub identyfikatorem uruchomionego kontenera Docs:

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

W systemie Linux skopiuj plik do tej ścieżki, używając konta z włączonym zapisem. W systemie Windows użyj katalogu motywów w katalogu %ProgramFiles%\ONLYOFFICE\DocumentServer; zapoznaj się z instrukcją instalacji, aby poznać pełną ścieżkę. Motyw niestandardowy to dodany plik JSON, a nie edycja dołączonych plików aplikacji.

ONLYOFFICE informuje, że pamięć podręczna motywu odświeża się co pięć minut. Odśwież edytor po skopiowaniu pliku; jeśli nadal go brakuje, postępuj zgodnie z instrukcjami rozwiązywania problemów z pamięcią podręczną w Dockerze lub Linuksie i uruchom ponownie usługi tylko w razie potrzeby. W przypadku kontenerów produkcyjnych dołącz plik do obrazu lub automatyzacji wdrożenia, aby zastąpienie kontenera nie spowodowało jego usunięcia.

3. Zastosuj motyw i ustaw logo edytora

Po wykryciu motywu użytkownicy mogą go wybrać z menu Widok > Motyw interfejsu . Aby edytor osadzony uruchamiał się z tym motywem, dodaj jego identyfikator do obiektu konfiguracji, który aplikacja przekazuje do API Dokumentów. Umieść logo w tym samym editorConfig.customizationobiekcie:

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

Zastąp przykładowe adresy URL rzeczywistymi adresami URL zasobów publicznych i docelowymi. logo.imageto standardowa ścieżka do logo dla typowych trybów edytora; oddzielne ciemne i jasne pola pozwalają wybrać grafikę dla ciemnego lub jasnego nagłówka. Adres URL to miejsce, w którym powinno zostać wyświetlone logo po kliknięciu. API wymienia to ustawienie nagłówka-logo jako funkcję Docs Developer i określa rozmiar 300 × 20. Nie należy go mylić z customer.logo, który oznacza większy obraz używany w informacjach o edytorze.

Jeśli Twoja integracja podpisuje konfiguracje edytora za pomocą JWT, odbuduj podpis po dodaniu lub zmianie tych podpisanych pól i zachowaj tajność podpisu na serwerze. Oficjalny przykład integracji ONLYOFFICE wyjaśnia, że ​​token musi być zgodny z konfiguracją i zostać ponownie wygenerowany po zmianie podpisanych parametrów. Należy również pamiętać, że wcześniej wybrany motyw użytkownika może mieć pierwszeństwo przed uiThemetestem z nowym profilem przeglądarki lub zresetować zapisane preferencje motywu użytkownika, jeśli żądany domyślny motyw nie jest wyświetlany.

Informacje na temat rozmiarów logo i dostępności edycji można znaleźć w oficjalnym standardowym dokumencie referencyjnym dotyczącym konfiguracji marki .

Sprawdź wynik przed wdrożeniem

Otwórz typy plików potrzebne użytkownikom. Sprawdź kolory nagłówka, czytelny tekst i ikony, poprawność logo w jasnych i ciemnych nagłówkach oraz miejsce kliknięcia logo. Sprawdź tryby edycji i widoku w rzeczywistym osadzonym układzie.

Jeśli brakuje motywu, sprawdź poprawność kodu JSON i identyfikatora, sprawdź katalog motywów na aktywnym serwerze i poczekaj na odświeżenie pamięci podręcznej. Jeśli brakuje logo, sprawdź wymagania dotyczące edycji Developer, dostęp przeglądarki do adresu URL obrazu oraz czy konfiguracja inicjująca zawiera logo. Wygeneruj ponownie JWT w zapleczu, jeśli zmieniłeś pola podpisu.