Personaliza ONLYOFFICE Docs con tu logotipo y colores de tema.

Para personalizar un editor de ONLYOFFICE Docs integrado, asígnele un tema de color de marca e incluya las URL de su logotipo en la configuración de inicialización. El tema es un archivo JSON que se instala en el servidor de Docs; el logotipo lo configura la aplicación que integra el editor. La opción de logotipo en el encabezado, documentada en la documentación, solo está disponible en ONLYOFFICE Docs Developer, así que confirme su edición antes de preparar los recursos.

Esto se aplica a la integración de Docs autoalojada, no a la marca DocSpace ni al selector de temas locales de los editores de escritorio. ONLYOFFICE documenta los temas personalizados de Docs v7.0. Estos ajustes afectan a la interfaz del editor integrado, no al contenido del documento ni a la navegación de su sitio web.

¿Qué debes preparar primero?

Reúna dos archivos para el logotipo: una versión que se vea claramente sobre un encabezado claro y una versión invertida para un encabezado oscuro o de color. La API de Docs especifica una imagen de 300 × 20 píxeles para el logotipo del encabezado del editor. Si su diseño lo permite, utilice un PNG transparente y mantenga un alto contraste con pocos detalles finos, ya que la imagen aparece en una franja estrecha. Aloje ambos archivos en direcciones HTTPS estables que el navegador del usuario del editor pueda cargar.

También necesitas permisos de escritura en el servidor, el código que configura el editor y un documento de prueba. Para Docker, identifica el nombre o ID del contenedor en ejecución. Prueba primero el cambio en un entorno que no sea de producción.

1. Crea un archivo JSON de tema para tus colores.

Un archivo JSON de tema es un archivo de configuración que asigna tokens de color de interfaz con nombre a valores de color. idDebe ser único y comenzar con theme-; es namelo que los usuarios ven en el selector de temas. Elija una base clara u oscura que coincida con la interfaz general que desea, luego reemplace los colores del encabezado y los acentos seleccionados. El ejemplo a continuación mantiene el fondo del editor claro, usa índigo para cada encabezado del editor y usa coral para el botón de acento del editor de documentos.

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

Guárdalo como acme-brand-light.json. Los tokens de color del encabezado son independientes para documentos, hojas de cálculo, presentaciones y PDF; configura cada uno si deseas una marca coherente en todos los tipos de archivo. El token de acento que se muestra aquí afecta al botón de acento del editor de documentos de texto, no a todos los elementos de color en Docs. ONLYOFFICE documenta tokens de color adicionales para fondos, bordes, estados de desplazamiento, iconos, texto y el lienzo de edición, así que amplía la paleta solo cuando necesites esas áreas. Comprueba el contraste del texto y los iconos con los fondos elegidos antes de la publicación; un color de marca por sí solo no garantiza controles legibles.

Para consultar la lista completa de tokens compatibles y los campos JSON necesarios, utilice la referencia oficial de temas personalizados de ONLYOFFICE .

2. Instala el tema en el servidor de Docs.

Copia el archivo JSON en el directorio de temas del servidor. La documentación oficial de Linux y Docker indica esta ruta:

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

Para una implementación de Docker, coloque el archivo en el directorio desde el que ejecutará el comando y luego reemplácelo CONTAINER_IDcon el nombre o ID del contenedor Docs en ejecución:

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

En Linux, copie el archivo a esa ruta con una cuenta con permisos de escritura. En Windows, use el directorio de temas en %ProgramFiles%\ONLYOFFICE\DocumentServer; consulte la guía de instalación para conocer su ruta completa. Un tema personalizado es un archivo JSON añadido, no una modificación de los archivos de la aplicación.

ONLYOFFICE indica que la caché de temas se actualiza cada cinco minutos. Actualice el editor después de copiar el archivo; si aún no aparece, siga las instrucciones de solución de problemas de caché de Docker o Linux y reinicie los servicios solo si es necesario. Para contenedores de producción, incluya el archivo en su imagen o automatización de implementación para que al reemplazar un contenedor no se elimine.

3. Aplica el tema y configura el logotipo del editor.

Una vez descubierto el tema, los usuarios pueden seleccionarlo en Ver > Tema de interfaz . Para que el editor integrado se inicie con ese tema, añada su ID al objeto de configuración que su aplicación pasa a la API de Docs. Configure el logotipo dentro del mismo editorConfig.customizationobjeto:

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

Reemplace las URL de ejemplo con sus URL de destino y recursos públicos reales. logo.imagees la ruta estándar del logotipo para los modos de editor comunes; los campos oscuro y claro separados le permiten elegir la imagen para un encabezado oscuro o claro. La URL es a dónde debe dirigirse un clic en el logotipo. La API enumera esta configuración de logotipo de encabezado como una característica de Docs Developer y especifica el tamaño 300 × 20. No lo confunda con customer.logo, que es una imagen más grande utilizada en la información Acerca de del editor.

Si su integración firma las configuraciones del editor con JWT, vuelva a generar la firma después de agregar o modificar estos campos firmados y mantenga el secreto de firma en el servidor. El ejemplo oficial de integración de ONLYOFFICE explica que el token debe coincidir con la configuración y regenerarse cuando cambien los parámetros firmados. Tenga en cuenta también que el tema seleccionado previamente por el usuario puede tener prioridad uiTheme; pruebe con un perfil de navegador nuevo o restablezca la preferencia de tema guardada del usuario si no se muestra el tema predeterminado solicitado.

Para conocer los tamaños de las propiedades del logotipo y la disponibilidad de ediciones, consulte la referencia oficial de configuración de marca estándar .

Verifica el resultado antes del lanzamiento.

Abra los tipos de archivo que sus usuarios necesitan. Confirme los colores del encabezado, el texto legible y los iconos, el logotipo correcto en los encabezados claros y oscuros, y el destino del clic del logotipo. Verifique los modos de edición y visualización en el diseño incrustado.

Si falta el tema, valide el JSON y el ID, revise el directorio de temas del servidor activo y espere a que se actualice la caché. Si falta el logotipo, verifique el requisito de la edición para desarrolladores, el acceso del navegador a la URL de la imagen y si la configuración de inicialización incluye logo. Regenere el JWT en el backend si modificó los campos firmados.