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

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

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

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

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

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

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

如何知道自訂設定是否生效

當配置的標誌始終顯示，正確的標誌變體在活動標題上仍然清晰可辨，自訂主題出現在主題選擇器中，品牌顏色渲染時不會破壞文字或圖示對比度，並且在使用者實際開啟的編輯器類型中體驗仍然可用時，您可以認為實作成功。

如果配置物件傳遞正確但標誌始終不變，請先確認版本和許可證，因為 API 文件將標誌參數標記為「僅限開發者使用」。如果顏色主題始終未顯示，請檢查 JSON ID 和語法、檔案位置、容器持久性、快取時間以及服務狀態。如果主題載入但顯示錯誤，請將自訂項目減少到一組已記錄的變量，並逐步新增顏色。

常見的界限和錯誤

為編輯器打造品牌與為 DocSpace 或 Workspace 打造品牌並不相同。

ONLYOFFICE 擁有獨立的自訂介面。本指南專門介紹 ONLYOFFICE 文件編輯器的品牌設定。入口網站品牌控制項、租用戶名稱、入口網站圖示和周圍導覽屬於文件空間或工作區設置，而非文件 API 標頭標誌物件。

文檔配色方案並非介面主題

文件配色方案會影響文字、表格、圖表和形狀等內容。自訂介面主題可以控制編輯器使用者介面元素，例如工具列、面板、按鈕、圖示、邊框和標籤。選擇與您要變更的介面相符的機制。

不要以為每個白標控制都包含標準品牌識別。

ONLYOFFICE 將標準品牌識別與擴展的白標參數分開。如果您需要對介面字體、佈局可見性或「關於」相關元素等項目進行更廣泛的控制，請在實施計劃之前，先查閱官方白標參考文檔，確認當前的許可要求。

實際部署檢查清單

• 如果您需要此處所述的頁首標誌自訂功能，請與 ONLYOFFICE Docs 開發人員確認。
• 建立 300×20 像素的 logo 素材，包括對比度需要時的淺色和深色版本。
• editorConfig.customization.logo在整合層進行配置。
• 建立一個有效的自訂主題 JSON，其 ID 以 . 開頭theme-。
• 將主題文件放置在文件中指定的文檔伺服器主題目錄中。
• 對於 Docker 或不可變部署，請確保主題安裝可重複且持久。
• 請等待規定的快取延遲時間，然後刷新並選擇主題。
• 在全面推廣之前，測試對比度、狀態、編輯器類型以及明亮和黑暗條件。

當您將標誌品牌、介面主題和擴展的白標控制在概念上分開時，ONLYOFFICE Docs 的自訂就變得更加容易，也更易於預測。首先進行能夠實現所需品牌契合度的最小改動，在實際編輯環境下進行驗證，然後再擴展主題。

官方參考資料

• ONLYOFFICE Docs API：自訂 – 標準品牌
• ONLYOFFICE 幫助中心：更改 ONLYOFFICE Docs 中的介面主題
• ONLYOFFICE Docs API：客製化 – 白標