使用您的商標和主題顏色打造 ONLYOFFICE Docs 品牌

若要自訂嵌入式 ONLYOFFICE Docs 編輯器，請為編輯器指定品牌顏色主題，並在其初始化配置中傳遞您的標誌 URL。主題是一個安裝在 Docs 伺服器上的 JSON 檔案；徽標由嵌入編輯器的應用程式進行配置。文件中提到的 header-logo 選項僅在 ONLYOFFICE Docs Developer 中可用，因此請在準備素材之前確認您的版本。

這適用於自架的 Docs 集成，不適用於 DocSpace 品牌或桌面編輯器的本機主題選擇器。 ONLYOFFICE 文件僅支援 Docs v7.0 中的自訂主題。這些設定會影響嵌入式編輯器介面，不會影響文件內容或您的網站導覽。

首先該準備什麼？

準備兩個版本的標誌檔案：一個版本適用於淺色頁眉，另一個版本適用於深色或彩色頁眉。 Docs API 規定編輯器頁首標誌的圖片尺寸為 300 × 20 像素。如果透明 PNG 格式更適合您的設計，請使用透明 PNG 格式，並保持徽標對比度高、細節少，因為徽標會顯示在較窄的區域內。將這兩個檔案託管在編輯器使用者瀏覽器可以存取的穩定 HTTPS 位址上。

您還需要伺服器寫入權限、用於建立編輯器配置的程式碼以及測試文件。對於 Docker，請確定正在執行的容器名稱或 ID。請先在非生產環境中測試變更。

準備一個淺色標題圖標和一個深色標題圖標，尺寸均為 300 × 20 像素，符合編輯器標題的文件要求。

1. 建立一個用於定義顏色的主題 JSON 文件

主題 JSON 文件是一個設定文件，它將命名的介面顏色標記映射到顏色值。這些標記id必須唯一，並以 `<color_name>` 開頭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 還提供了背景、邊框、懸停狀態、圖標、文字和編輯畫布的其他顏色標記，因此僅在需要這些區域時才擴展調色板。發布前，請檢查文字和圖示與所選背景的對比；僅使用品牌顏色並不能保證控制項清晰易讀。

主題檔案將名為 ONLYOFFICE 的顏色標記對應到您希望在介面中顯示的顏色。

有關完整的受支援令牌列表和所需的 JSON 字段，請使用ONLYOFFICE 官方自訂主題參考。

2. 在文件伺服器上安裝主題

將 JSON 檔案複製到伺服器的主題目錄中。官方 Linux 和 Docker 文件給出了以下路徑：

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

對於 Docker 部署，請將該檔案放在您將執行命令的目錄中，然後將 `<container_name>` 替換CONTAINER_ID為正在執行的 Docs 容器的名稱或 ID：

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

在 Linux 系統中，使用具有寫入權限的帳戶將檔案複製到指定路徑。在 Windows 系統中，使用 `<path>` 目錄下的 `themes` 目錄%ProgramFiles%\ONLYOFFICE\DocumentServer；請參閱安裝指南以取得完整路徑。自訂主題是一個新增的 JSON 文件，而不是對應用程式自帶文件的編輯。

將主題 JSON 複製到伺服器端主題目錄中；容器識別碼必須與您正在執行的文件服務相符。

ONLYOFFICE 提示主題快取每五分鐘刷新一次。複製文件後請重新整理編輯器；如果仍然找不到該文件，請按照 Docker 或 Linux 快取故障排除說明進行操作，並僅在必要時重新啟動服務。對於生產環境容器，請將該檔案包含在鏡像或部署自動化流程中，以避免容器替換時將其刪除。

3. 套用主題並設定編輯器徽標

主題被發現後，使用者可以從“視圖”>“介面主題”中選擇它。若要讓嵌入式編輯器使用該主題，請將其 ID 新增至應用程式傳遞給文件 API 的配置物件中。在同一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您要求的預設主題；如果未顯示，請使用全新的瀏覽器設定檔進行測試，或重設該使用者儲存的主題首選項。

有關標誌屬性尺寸和版本可用性，請參閱官方標準品牌配置參考。