Оформите документы ONLYOFFICE в соответствии с вашим логотипом и цветовой гаммой темы.

Чтобы настроить встроенный редактор документов ONLYOFFICE, задайте ему фирменную цветовую тему и передайте URL-адреса вашего логотипа в конфигурации инициализации. Тема представляет собой JSON-файл, устанавливаемый на сервере документов; логотип настраивается приложением, которое встраивает редактор. Опция header-logo, описанная в документации, доступна только в ONLYOFFICE Docs Developer, поэтому перед подготовкой ресурсов подтвердите свою версию.

Это относится к интеграции Docs с собственным сервером, а не к брендингу DocSpace или локальному выбору тем в Desktop Editors. ONLYOFFICE использует пользовательские темы для документов из Docs версии 7.0. Эти настройки влияют на интерфейс встроенного редактора, а не на содержимое документа или навигацию по вашему веб-сайту.

Что следует подготовить в первую очередь?

Для логотипа подготовьте два файла: версию, которая хорошо читается на светлом заголовке, и инвертированную версию для темного или цветного заголовка. API Docs указывает, что для логотипа в заголовке редактора требуется изображение размером 300 × 20 пикселей. Используйте прозрачный PNG-файл, если это подходит для вашего изображения, и сохраните высококонтрастность и минимум мелких деталей, поскольку изображение отображается в узкой полосе. Разместите оба файла по стабильным HTTPS-адресам, которые может загрузить браузер пользователя редактора.

Вам также потребуются права на запись на сервер, код, который формирует конфигурацию редактора, и тестовый документ. Для Docker необходимо определить имя или идентификатор запущенного контейнера. Сначала протестируйте изменения в непроизводственной среде.

1. Создайте JSON-файл темы для ваших цветов.

JSON-файл темы — это файл настроек, который сопоставляет именованные токены цвета интерфейса со значениями цвета. Идентификатор idдолжен быть уникальным и начинаться с theme-; nameименно его пользователи видят в палитре выбора темы. Выберите светлую или темную основу, соответствующую общему желаемому интерфейсу, затем замените цвета заголовка и выбранные акцентные цвета. В приведенном ниже примере фон редактора остается светлым, для каждого заголовка редактора используется цвет индиго, а для акцентной кнопки редактора документов — коралловый.

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

Сохраните как acme-brand-light.json. Цветовые метки заголовка разделены для документов, электронных таблиц, презентаций и PDF-файлов; установите каждую из них, если хотите использовать единый фирменный стиль для всех типов файлов. Показанная здесь метка акцента влияет на кнопку акцента в текстовом редакторе документов, а не на каждый цветной элемент в Docs. ONLYOFFICE добавляет дополнительные цветовые метки для фона, границ, состояний при наведении курсора, значков, текста и холста редактирования, поэтому расширяйте палитру только тогда, когда вам нужны эти области. Перед публикацией проверьте контрастность текста и значков с выбранным фоном; один только фирменный цвет не гарантирует читаемость элементов управления.

Полный список поддерживаемых токенов и необходимых полей JSON см. в официальном справочнике по пользовательским темам ONLYOFFICE .

2. Установите тему на сервере документации.

Скопируйте JSON-файл в каталог тем сервера. В официальной документации Linux и Docker указан следующий путь:

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

Для развертывания в Docker поместите файл в каталог, из которого вы будете запускать команду, а затем замените CONTAINER_IDна имя или идентификатор запущенного контейнера Docs:

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

В Linux скопируйте файл по указанному пути, используя учетную запись с правами на запись. В Windows используйте каталог themes в папке %ProgramFiles%\ONLYOFFICE\DocumentServer; полный путь к нему см. в руководстве по установке. Пользовательская тема — это добавленный JSON-файл, а не изменение файлов приложения, входящего в комплект поставки.

ONLYOFFICE сообщает, что кэш тем обновляется каждые пять минут. Обновите редактор после копирования файла; если он по-прежнему отсутствует, следуйте инструкциям по устранению неполадок с кэшем Docker или Linux и перезапускайте службы только при необходимости. Для производственных контейнеров включите файл в образ или автоматизацию развертывания, чтобы замена контейнера не привела к его удалению.

3. Примените тему и установите логотип редактора.

После того, как тема будет найдена, пользователи смогут выбрать её в меню «Вид» > «Тема интерфейса» . Чтобы ваш встроенный редактор запускался с этой темой, добавьте её ID в объект конфигурации, который ваше приложение передаёт в API документации. Разместите логотип внутри того же editorConfig.customizationобъекта:

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

Замените приведенные примеры URL-адресов на ваши фактические общедоступные URL-адреса ресурсов и целевые URL-адреса. logo.image— это стандартный путь к логотипу для распространенных режимов редактора; отдельные поля для темного и светлого режимов позволяют выбрать изображение для темного или светлого заголовка. URL-адрес — это место, куда должен вести клик по логотипу. API указывает этот параметр header-logo как функцию Docs Developer и задает размер 300 × 20. Не путайте его с customer.logo, который представляет собой более крупное изображение, используемое в информации «О программе» редактора.

Если ваша интеграция подписывает конфигурации редактора с помощью JWT, пересоздайте подпись после добавления или изменения этих подписанных полей и храните секретный ключ подписи на сервере. В официальном примере интеграции ONLYOFFICE объясняется, что токен должен соответствовать конфигурации и генерироваться заново при изменении подписанных параметров. Также обратите внимание, что ранее выбранная пользователем тема может иметь приоритет uiTheme; протестируйте с новым профилем браузера или сбросьте сохраненные настройки темы пользователя, если запрошенная вами тема по умолчанию не отображается.

Информацию о размерах логотипа и доступных вариантах оформления см. в официальном справочнике по стандартной конфигурации фирменной символики .

Перед внедрением проверьте результат.

Откройте файлы необходимых пользователям типов. Подтвердите цвета заголовка, читаемый текст и значки, корректность логотипа в светлом и темном заголовках, а также место перехода по ссылке к логотипу. Проверьте режимы редактирования и просмотра в фактическом встроенном макете.

Если тема отсутствует, проверьте JSON и ID, проверьте каталог тем активного сервера и дождитесь обновления кеша. Если логотип отсутствует, проверьте требования к версии для разработчиков, доступность URL-адреса изображения в браузере и наличие соответствующего параметра в конфигурации инициализации logo. Перегенерируйте JWT на бэкэнде, если вы изменили подписанные поля.