如何使用您的商標和顏色自訂 ONLYOFFICE Docs 品牌

最簡潔的答案：使用 Docs API 的品牌識別作為徽標，並使用自訂介面主題來設定顏色。

如果您希望 ONLYOFFICE Docs 編輯器看起來像是您自己的產品的一部分，最簡潔的設定方法是採用兩層自訂：首先editorConfig.customization.logo在 Docs API 整合中配置頁眉徽標，然後在文件伺服器上新增自訂主題 JSON 檔案來設定編輯器顏色。這兩種機制是獨立的，並且具有不同的可用性規則。

經2026年10月7日查閱ONLYOFFICE官方文件確認，editor-headerlogo參數僅適用於ONLYOFFICE Docs Developer版本。官方API規定，<header>、<header>和<header>圖片尺寸為300×20像素image，imageDark建議imageLightlogo高度為20像素。同時，ONLYOFFICE Docs自v7.0版本起支援自訂介面主題，這些主題以JSON格式檔案的形式安裝在文件伺服器上。目前的官方參考文檔是ONLYOFFICE Docs標準品牌文檔，主題文件的工作流程請參閱ONLYOFFICE Docs中的「更改介面主題」文件。

這種方法適用於將 ONLYOFFICE Docs 嵌入到自身 Web 應用程式並控製文件伺服器的團隊。它與更改 DocSpace 或 Workspace 入口網站主題不同。如果您的目標是外部入口網站而非編輯器本身，請改用該產品的品牌設定。

首先確認您的版本和整合模型是否支援您計劃使用的編輯器品牌。

第一步：確認你實際上需要打造哪些品牌形象。

在編輯文件之前，請將品牌化介面分解為三個問題。您是否只需要在編輯器標題列中使用徽標？您是否也希望在工具列、按鈕、文字、邊框和麵板中使用品牌顏色？或者您需要更深入的白標體驗，以更改其他介面元素？

頁眉標誌：使用editorConfig.customization.logo. ONLYOFFICE 將此參數標記為僅限開發人員使用。
介面顏色：在文件伺服器上安裝自訂主題 JSON 檔案。這是實現品牌顏色的正確方法。
更深入的白標控制：請查看擴充白標文件。 ONLYOFFICE 指出，這些參數需要 Docs Developer 的擴展白標許可證。

這種區別很重要，因為更改主題檔案不會自動替換標題徽標，設定徽標物件也不會重新著色編輯器的其餘部分。

步驟二：準備淺色和深色標題的標誌文件

準備一個寬大簡潔的徽標，確保在 20 像素高的頁眉中仍然清晰可辨。 API 文件規定標準頁首影像的尺寸為 300×20 像素。如果品牌標誌在深色和淺色背景下對比度降低，請使用不同的影像素材。例如，深藍色文字標誌在淺色頁眉中可能效果不錯，但在深色主題下則會變得難以辨認；使用白色或淺色版本即可解決這個問題。

將圖片託管在編輯器可以載入的穩定 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控制點擊徽標後跳到的位置；將其設為空字串，或null設定為「不可點擊」。visible控制徽標是否顯示。

將徽標物件新增至應用程式建立文件編輯器時傳遞的配置中。

步驟 4：在明亮和黑暗兩種條件下驗證標誌。

透過整合開啟一個實際文檔，並在瀏覽器正常縮放等級下檢查頁首。成功加載的不僅僅是“文件已加載”。標誌應該清晰、垂直居中、在緊湊的頁眉高度下清晰可辨，並且沒有意外的背景框。同時，檢查點擊操作是否符合預期。

在淺色或彩色標題中驗證徽標，並確保其在正常編輯器縮放比例下仍然清晰可讀。

然後切換到深色介面，重複檢查。如果徽標對比度降低，請使用專用imageDark素材，而不是試圖讓圖形在所有情況下都有效。

單獨的淺色標誌版本使品牌在深色編輯器標題列中清晰可見。

步驟 5：建立自訂顏色主題 JSON

對於介面顏色，請建立id以 `.` 開頭的主題檔案。此主題文件僅支援theme-ONLYOFFICE 文檔，並且支援十六進位或 RGBA 表示法的顏色。請勿將其與文件配色方案混淆：此 JSON 檔案變更的是編輯器本身的介面顏色，而不是儲存在 DOCX、XLSX 或 PPTX 檔案中的主題顏色。lightdark

{
  "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 預設主題。參數名稱均為已記錄的主題變數。在實際應用中，建議先使用少量影響較大的數值，預覽效果，然後根據需要逐步擴展。這樣可以更輕鬆地發現對比度不足或狀態不一致的問題。

建立一個主題 JSON 文件，其中包含唯一的以主題為前綴的 ID 和精心選擇的介面顏色變數。

步驟 6：將主題檔案放置在文件伺服器主題目錄中

ONLYOFFICE 文件中記錄了自訂主題檔案的存放位置：

Linux： /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/

替換onlyoffice為您實際的容器名稱或 ID。如果您的部署經常重建，請勿依賴一次性副本作為唯一的資料來源。請將主題新增至您的部署流程、鏡像定製或其他適合您環境的持久化機制中，以避免升級和容器替換時將其靜默刪除。

對於 Docker 部署，請將自訂主題 JSON 複製到 Docs 容器內的文件主題目錄中。

步驟 7：重新整理頁面，等待快取載入完畢，然後選擇自訂主題

官方指南指出，主題請求的伺服器快取有效期限為五分鐘。上傳檔案後，請等待五分鐘後再重新整理編輯器。如果主題仍然沒有顯示，ONLYOFFICE 也建議重新啟動服務並清除快取。

主題載入完成後，應該會出現在進階設定的介面主題清單中。選取該主題，並檢查標題列之外的其他內容。檢查選單、對話方塊、選取的標籤、懸停狀態、停用控制項、圖示、通知徽章和文字對比。

識別出主題後，應該可以從編輯器的介面主題清單中選擇它。

步驟 8：驗證最終品牌形像是否為一個完整的系統，而不僅僅是一個螢幕截圖。

一個好的自訂品牌應該能夠經得起日常編輯器的使用。開啟文件、電子表格、簡報和 PDF 文件（如果這些編輯器都在測試範圍內）。嘗試常用的對話方塊和協作控制項。如果提供了淺色和深色兩種模式，請分別測試。檢查鍵盤焦點、停用狀態、懸停對比以及長檔名。即使在標題列中看起來很漂亮的顏色，也可能導致選取的標籤頁或輔助文字難以閱讀。