로고와 테마 색상으로 ONLYOFFICE Docs를 브랜드화하세요.

내장된 ONLYOFFICE Docs 편집기를 사용자 지정하려면 편집기에 브랜드 색상 테마를 지정하고 초기화 구성에 로고 URL을 전달하세요. 테마는 Docs 서버에 설치된 JSON 파일이며, 로고는 편집기를 내장하는 애플리케이션에서 구성합니다. 문서에 설명된 헤더 로고 옵션은 ONLYOFFICE Docs Developer에서만 사용할 수 있으므로 자산을 준비하기 전에 버전을 확인하세요.

이 설정은 자체 호스팅 Docs 통합에 적용되며, DocSpace 브랜딩이나 데스크톱 편집기의 로컬 테마 선택기에는 적용되지 않습니다. ONLYOFFICE 문서는 Docs v7.0의 사용자 지정 테마를 사용합니다. 이러한 설정은 내장된 편집기 인터페이스에 영향을 미치며, 문서 콘텐츠나 웹사이트 탐색에는 영향을 주지 않습니다.

무엇을 먼저 준비해야 할까요?

로고 파일은 두 개 준비하세요. 하나는 밝은 헤더 배경에서 잘 보이는 버전이고, 다른 하나는 어두운 헤더나 색상이 있는 헤더에 사용할 반전 버전입니다. Docs API에서는 에디터 헤더 로고에 300 × 20 픽셀 크기의 이미지를 지정하고 있습니다. 투명 PNG 형식이 적합하다면 투명 PNG 파일을 사용하고, 이미지가 좁은 영역에 표시되므로 세부적인 묘사는 최소화하고 대비가 높은 이미지를 사용하는 것이 좋습니다. 두 파일 모두 에디터 사용자의 브라우저에서 로드할 수 있는 안정적인 HTTPS 주소에 호스팅하세요.

서버 쓰기 권한, 편집기 구성을 생성하는 코드, 그리고 테스트 문서도 필요합니다. Docker를 사용하는 경우 실행 중인 컨테이너 이름 또는 ID를 확인하세요. 변경 사항은 먼저 비운영 환경에서 테스트하십시오.

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. Docs 서버에 테마를 설치합니다.

JSON 파일을 서버의 테마 디렉터리에 복사하세요. 공식 Linux 및 Docker 문서에는 다음과 같은 경로가 나와 있습니다.

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

Docker 배포의 경우, 해당 파일을 명령을 실행할 디렉터리에 넣은 다음, CONTAINER_ID<docs 컨테이너 이름 또는 ID>를 실행 중인 Docs 컨테이너의 이름 또는 ID로 바꾸십시오.

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

Linux에서는 쓰기 권한이 있는 계정으로 해당 경로에 파일을 복사하십시오. Windows에서는 %ProgramFiles%\ONLYOFFICE\DocumentServer설치 가이드를 참조하여 전체 경로가 표시된 'themes' 디렉터리를 사용하십시오. 사용자 지정 테마는 기본 제공되는 애플리케이션 파일을 수정하는 것이 아니라 추가하는 JSON 파일입니다.

ONLYOFFICE에 따르면 테마 캐시는 5분마다 새로 고쳐집니다. 파일을 복사한 후 편집기를 새로 고치십시오. 그래도 파일이 없으면 Docker 또는 Linux 캐시 문제 해결 지침을 따르고 필요한 경우에만 서비스를 다시 시작하십시오. 프로덕션 컨테이너의 경우, 컨테이너를 교체해도 파일이 삭제되지 않도록 이미지 또는 배포 자동화에 파일을 포함하십시오.

3. 테마를 적용하고 에디터 로고를 설정하세요.

테마가 검색되면 사용자는 보기 > 인터페이스 테마 에서 해당 테마를 선택할 수 있습니다 . 내장 편집기가 해당 테마로 시작하도록 하려면 애플리케이션이 Docs API에 전달하는 구성 객체에 해당 테마의 ID를 추가하세요. 로고도 같은 객체 안에 설정합니다 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로 바꾸세요. logo.image는 일반적인 편집기 모드에서 사용되는 표준 로고 경로입니다. 별도의 어두운 색상 및 밝은 색상 필드를 사용하여 어두운 헤더 또는 밝은 헤더에 사용할 이미지를 선택할 수 있습니다. URL은 로고를 클릭했을 때 이동할 위치입니다. API는 이 헤더 로고 설정을 문서 개발자 기능으로 나열하고 300 × 20 크기를 지정합니다. customer.logo편집기의 정보 설명에 사용되는 더 큰 이미지인 와 혼동하지 마세요.

통합 기능이 JWT를 사용하여 편집기 구성을 서명하는 경우, 서명된 필드를 추가하거나 변경한 후에는 서명을 다시 생성하고 서명 비밀 키를 서버에 보관하십시오. ONLYOFFICE 공식 통합 예제에서는 토큰이 구성과 일치해야 하며 서명된 매개변수가 변경될 때마다 다시 생성해야 한다고 설명합니다. 또한 사용자가 이전에 선택한 테마가 우선 적용될 수 있으므로 uiTheme, 요청한 기본 테마가 표시되지 않으면 새 브라우저 프로필로 테스트하거나 해당 사용자의 저장된 테마 설정을 재설정하십시오.

로고 속성 크기 및 에디션 가용성에 대한 자세한 내용은 공식 표준 브랜딩 구성 참조 자료를 확인하세요 .

배포 전에 결과를 확인하십시오.

사용자가 필요로 하는 파일 형식을 엽니다. 헤더 색상, 읽기 쉬운 텍스트와 아이콘, 밝은 헤더와 어두운 헤더에 올바르게 표시된 로고, 로고를 클릭했을 때 나타나는 위치를 확인합니다. 실제 임베디드 레이아웃에서 편집 및 보기 모드를 확인합니다.

테마가 누락된 경우 JSON 및 ID를 검증하고 활성 서버의 테마 디렉터리를 확인한 후 캐시가 새로 고쳐질 때까지 기다리세요. 로고가 누락된 경우 개발자 에디션 요구 사항, 브라우저의 이미지 URL 접근 권한, 초기화 구성에 해당 항목이 포함되어 있는지 확인하세요 logo. 서명된 필드를 변경한 경우 백엔드에서 JWT를 다시 생성하세요.