로고와 색상을 사용하여 ONLYOFFICE 문서를 맞춤 브랜딩하는 방법

가장 간단한 답변은 다음과 같습니다. 로고에는 Docs API 브랜딩을 사용하고, 색상은 사용자 지정 인터페이스 테마를 사용하세요.

ONLYOFFICE Docs 편집기를 자사 제품의 일부처럼 보이게 하려면 두 단계의 사용자 정의 설정이 가장 깔끔합니다. 먼저 editorConfig.customization.logoDocs API 통합에서 헤더 로고를 구성한 다음, 문서 서버에 편집기 색상을 위한 사용자 정의 테마 JSON 파일을 추가하세요. 이 두 가지 방법은 별개이며, 각각 사용 가능 여부에 대한 규칙이 다릅니다.

2026년 10월 7일 ONLYOFFICE 문서에서 확인한 결과, editor-header 매개변수는 ONLYOFFICE Docs Developer 버전에서만 사용할 수 있습니다. 공식 API에서는 <header>, <body>, <body> logo이미지에 대해 300x20 크기의 이미지를 권장하며, 로고 높이는 20픽셀로 설정했습니다. 사용자 지정 인터페이스 테마는 ONLYOFFICE Docs v7.0부터 지원되며, 문서 서버에 JSON 테마 파일로 설치됩니다. 현재 공식 참조 문서는 ONLYOFFICE Docs 표준 브랜딩 문서 이며, 테마 파일 워크플로는 ONLYOFFICE Docs에서 인터페이스 테마 변경 문서 에 설명되어 있습니다 .imageimageDarkimageLight

이 접근 방식은 ONLYOFFICE Docs를 자체 웹 애플리케이션에 통합하고 문서 서버를 관리하는 팀에 적합합니다. DocSpace 또는 Workspace 포털 테마를 변경하는 것과는 다릅니다. 편집기 자체가 아닌 주변 포털을 대상으로 하는 경우 해당 제품의 브랜딩 설정을 사용하십시오.

1단계: 실제로 브랜딩해야 할 사항을 확인합니다.

파일을 편집하기 전에 브랜딩 영역을 세 가지 질문으로 구분하세요. 편집기 헤더에 로고만 필요한가요? 툴바, 버튼, 텍스트, 테두리, 패널 전체에 브랜드 색상을 적용하고 싶으신가요? 아니면 인터페이스의 다른 요소들도 변경하는 심층적인 화이트 라벨 환경이 필요한가요?

• 헤더 로고: 사용 editorConfig.customization.logo. ONLYOFFICE는 이 매개변수를 개발자 전용으로 표시합니다.
• 인터페이스 색상: 문서 서버에 사용자 지정 테마 JSON 파일을 설치하세요. 이것이 브랜드 색상을 구현하는 올바른 방법입니다.
• 더욱 세밀한 화이트 라벨 제어: 확장된 화이트 라벨 문서를 확인하세요 . ONLYOFFICE는 이러한 매개변수를 사용하려면 Docs Developer용 확장 화이트 라벨 라이선스가 필요하다고 명시하고 있습니다.

이러한 구분은 중요합니다. 테마 파일을 변경해도 헤더 로고가 자동으로 바뀌지 않고, 로고 객체를 설정해도 편집기의 나머지 부분이 변경되지 않기 때문입니다.

2단계: 밝은 색 헤더와 어두운 색 헤더에 사용할 로고 파일을 준비합니다.

20픽셀 높이의 헤더에서도 가독성이 유지되는 넓고 단순한 로고를 준비하세요. API 문서에서는 표준 헤더 이미지 변형에 300x20 픽셀 크기의 이미지를 권장합니다. 브랜드 마크가 어두운 배경과 밝은 배경에서 대비가 약해지는 경우, 각각 다른 이미지를 사용하세요. 예를 들어, 진한 남색 워드마크는 밝은 헤더에서는 잘 보이지만 어두운 테마에서는 잘 보이지 않을 수 있습니다. 이럴 때는 흰색이나 밝은 색 변형을 사용하면 문제를 해결할 수 있습니다.

편집기가 로드할 수 있는 안정적인 HTTPS URL에 이미지를 호스팅하세요. 로고를 지속적으로 사용해야 하는 경우, 수명이 짧은 서명된 URL은 사용하지 마세요. 또한 실제 사용자가 사용하는 것과 동일한 네트워크 경로 및 브라우저 보안 정책을 통해 에셋을 테스트하세요.

3단계: Docs API 구성에 로고를 추가합니다.

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

image는 일반적인 작업 모드 로고입니다. imageDark는 어둡거나 색상이 있는 헤더에 사용되며, 는 imageLight회색 테마와 같은 밝은 헤더에 사용됩니다. 는 로고를 클릭했을 때 이동할 위치를 제어합니다. 로고를 클릭할 수 없도록 하려면 url빈 문자열로 설정하거나 를 사용하지 마십시오 . 는 로고 표시 여부를 제어합니다.nullvisible

4단계: 밝은 환경과 어두운 환경 모두에서 로고를 확인합니다.

연동 기능을 통해 실제 문서를 열고 브라우저의 일반적인 확대/축소 수준에서 헤더를 확인하세요. 단순히 "파일이 로드되었다"는 것만으로는 성공적인 결과가 아닙니다. 로고는 선명하고, 세로로 중앙에 위치해야 하며, 압축된 헤더 높이에서도 읽기 쉬워야 하고, 예상치 못한 배경 상자가 없어야 합니다. 또한 클릭 동작이 의도한 대로 작동하는지도 확인하세요.

그다음 어두운 인터페이스 환경으로 전환하고 다시 확인하세요. 로고의 대비가 낮아지면 imageDark하나의 그래픽을 모든 곳에 적용하려고 하기보다는 전용 에셋을 사용하는 것이 좋습니다.

5단계: 사용자 지정 색상 테마 JSON 생성

id인터페이스 색상을 변경 하려면 theme-.ONLYOFFICE 문서 light만 유효한 테마 유형으로 지원하고 16진수 또는 RGBA 표기법으로 색상을 지원하는 테마 파일을 생성하세요 dark. 이 파일을 문서 색 구성표와 혼동하지 마세요. 이 JSON 파일은 편집기 테두리 자체를 변경하는 것이지 DOCX, XLSX 또는 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"
  }
}

위의 값들은 예시 팔레트일 뿐이며, ONLYOFFICE에서 지정한 테마 설정이 아닙니다. 매개변수 이름은 테마 변수로 문서화되어 있습니다. 실제 사용 환경에서는 효과가 큰 소수의 값으로 시작하여 결과를 미리 보고 필요에 따라 값을 확장하십시오. 이렇게 하면 대비가 부족하거나 일관성이 없는 상태를 쉽게 파악할 수 있습니다.

6단계: 테마 파일을 문서 서버의 테마 디렉터리에 배치합니다.

ONLYOFFICE는 사용자 지정 테마 파일의 위치를 ​​다음과 같이 안내합니다.

• 리눅스: /var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes
• 윈도우: %ProgramFiles%\ONLYOFFICE\DocumentServer\web-apps\apps\common\main\resources\themes
• Docker: JSON 파일을 Docs 컨테이너 내부의 동일한 경로에 복사합니다.

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

컨테이너 이름이나 ID를 실제 값으로 바꾸세요 onlyoffice. 배포를 자주 재구축하는 경우, 일회성 복사본을 유일한 원본 소스로 사용하지 마세요. 업그레이드 및 컨테이너 교체 시 테마가 자동으로 제거되지 않도록 배포 프로세스, 이미지 사용자 지정 또는 환경에 적합한 다른 영구적인 메커니즘에 테마를 포함시키세요.

7단계: 새로 고침하고 캐시가 적용될 때까지 기다린 후 사용자 지정 테마를 선택합니다.

공식 가이드에 따르면 테마 요청에 대한 서버 캐시는 5분 동안 유지됩니다. 파일을 배치한 후 해당 시간 동안 기다린 다음 편집기를 새로 고치십시오. 경우에 따라 테마가 표시되지 않으면 ONLYOFFICE에서 서비스를 재시작하고 캐시를 삭제하는 것을 권장합니다.

테마가 로드되면 고급 설정의 인터페이스 테마 목록에 나타납니다. 해당 테마를 선택하고 헤더뿐만 아니라 메뉴, 대화 상자, 선택된 탭, 마우스 오버 상태, 비활성화된 컨트롤, 아이콘, 알림 배지 및 텍스트 대비를 검사하십시오.

8단계: 완성된 브랜드를 단순한 스크린샷이 아닌 시스템으로서 검증합니다.

효과적인 사용자 지정 브랜드 디자인은 일반적인 편집기 사용 환경에서도 잘 유지되어야 합니다. 문서, 스프레드시트, 프레젠테이션, PDF 편집기(해당되는 경우)를 열어보고, 자주 사용하는 대화 상자와 공동 작업 컨트롤을 확인해 보세요. 밝은 환경과 어두운 환경 모두 지원하는 경우 두 환경 모두에서 브랜드 디자인을 검증합니다. 키보드 포커스, 비활성화 상태, 마우스 오버 시 대비, 긴 파일 이름 등도 확인합니다. 헤더에서 보기 좋은 색상이라도 선택된 탭이나 보조 텍스트에서는 읽기 어려울 수 있기 때문입니다.

맞춤 설정이 제대로 작동하는지 어떻게 알 수 있을까요?

구성된 로고가 일관되게 표시되고, 활성 헤더에서 올바른 로고 변형이 읽기 쉬운 상태로 유지되며, 사용자 지정 테마가 테마 선택기에 나타나고, 브랜드 색상이 텍스트나 아이콘의 대비를 깨뜨리지 않고 렌더링되며, 사용자가 실제로 여는 모든 편집기 유형에서 사용 가능한 환경을 유지할 때 구현이 성공적이라고 볼 수 있습니다.

구성 객체가 올바르게 전달되었는데도 로고가 변경되지 않으면 먼저 에디션과 라이선스를 확인하십시오. API 참조에서 로고 매개변수가 문서 개발자 전용으로 표시되어 있기 때문입니다. 색상 테마가 전혀 나타나지 않으면 JSON ID 및 구문, 파일 위치, 컨테이너 지속성, 캐시 타이밍 및 서비스 상태를 확인하십시오. 테마는 로드되지만 제대로 표시되지 않으면 문서화된 변수 집합으로 사용자 지정을 줄이고 색상을 점진적으로 추가하십시오.

흔히 저지르는 실수와 한계

편집기 브랜딩은 DocSpace 또는 Workspace 브랜딩과는 다릅니다.

ONLYOFFICE는 별도의 사용자 지정 인터페이스를 제공합니다. 이 가이드는 ONLYOFFICE Docs 편집기 브랜딩에 관한 것입니다. 포털 브랜딩 컨트롤, 테넌트 이름, 포털 파비콘 및 주변 탐색 메뉴는 Docs API 헤더 로고 객체가 아닌 DocSpace 또는 Workspace 설정에 속합니다.

문서 색 구성표는 인터페이스 테마가 아닙니다.

문서 색 구성표는 텍스트, 표, 차트 및 도형과 같은 콘텐츠에 영향을 미칩니다. 사용자 지정 인터페이스 테마는 도구 모음, 패널, 버튼, 아이콘, 테두리 및 레이블과 같은 편집기 UI 요소를 제어합니다. 변경하려는 인터페이스에 맞는 방식을 선택하십시오.

모든 화이트 라벨 컨트롤이 표준 브랜딩에 포함되어 있다고 가정하지 마십시오.

ONLYOFFICE는 표준 브랜딩과 확장된 화이트 라벨 매개변수를 분리합니다. 인터페이스 글꼴, 레이아웃 표시 여부 또는 정보 관련 요소와 같은 항목을 보다 폭넓게 제어해야 하는 경우, 구현을 계획하기 전에 공식 화이트 라벨 참조 에서 현재 라이선스 요구 사항을 확인하십시오.

실제 배포 체크리스트

• 여기에 설명된 헤더 로고 사용자 지정이 필요한 경우 ONLYOFFICE Docs 개발자에게 확인하십시오.
• 명암 대비가 필요한 경우 밝은 버전과 어두운 버전을 포함하여 300x20 크기의 로고 에셋을 제작하세요.
• editorConfig.customization.logo통합 계층에서 구성합니다 .
• ID가 .으로 시작하는 유효한 사용자 지정 테마 JSON을 생성합니다 theme-.
• 해당 테마 파일을 문서화된 문서 서버 테마 디렉터리에 배치하십시오.
• Docker 또는 변경 불가능한 배포 환경의 경우, 테마 설치를 반복 가능하고 영구적으로 유지하십시오.
• 명시된 캐시 지연 시간을 기다린 후 새로 고침하고 테마를 선택하세요.
• 광범위하게 배포하기 전에 대비, 상태, 편집기 유형, 밝은 조건 및 어두운 조건을 모두 테스트하십시오.

로고 브랜딩, 인터페이스 테마, 확장된 화이트 라벨 컨트롤을 개념적으로 분리하면 ONLYOFFICE Docs를 훨씬 더 예측 가능하게 맞춤 설정할 수 있습니다. 원하는 브랜드 이미지를 구현하는 데 필요한 가장 작은 변경 사항부터 시작하고, 실제 편집 환경에서 검증한 다음 테마를 확장하세요.

공식 참고 자료

• ONLYOFFICE Docs API: 사용자 지정 - 표준 브랜딩
• ONLYOFFICE 도움말 센터: ONLYOFFICE Docs에서 인터페이스 테마 변경하기
• ONLYOFFICE Docs API: 사용자 지정 - 화이트 라벨