如何自訂 ownCloud Web UI 品牌和主題顏色

自訂目前 ownCloud Web 介面的最可靠方法是建立一個受支援的主題 JSON 文件，並將 ownCloud Infinite Scale 指向該主題。您無需重新建立 Web 前端即可變更品牌名稱、徽標、網站圖示、登入背景或常用介面顏色。在目前的 Infinite Scale 主題模型中，這些元素透過主題定義提供，而設計代幣則控制顏色和其他視覺值。

本指南適用於 ownCloud Infinite Scale (oCIS) 及其現代 ownCloud Web 前端。它不適用於舊版 ownCloud Server 10/11 PHP 主題系統，後者採用基於應用程式的主題結構和不同的配置。 ownCloud 穩定版 Infinite Scale 8.2 文件和 9.0 開發文件都描述了相同的執行階段方法：提供一個自訂主題目錄WEB_ASSET_THEMES_PATH，然後選擇一個主題 JSON 檔案WEB_UI_THEME_PATH。請參閱官方ownCloud Web 自訂主題文件。

無需重新建置 ownCloud Web 即可自訂的內容

標準的組織主題可以滿足大多數管理員實際需要的視覺變更。主題 JSON 檔案可以定義產品名稱和標語、標誌和網站圖示的路徑、登入頁面背景以及品牌、主色、背景色、文字色、邊框色和檔案類型顏色等網頁設計元素。這比編輯已編譯的前端檔案更可取，因為主題仍然是一個獨立的部署資源，可以與伺服器設定一起管理。

品牌目標	它屬於哪裡？	典型值
產品名稱和標語	`common`	公司雲，公司標語
頂部欄、登入介面和網站圖標	`clients.web.defaults.logo`	主題資源資料夾下的路徑
登入背景	`clients.web.defaults.loginPage.backgroundImg`	JPEG 或其他瀏覽器支援的圖像資源
品牌和使用者介面顏色	`clients.web.themes[].designTokens.colorPalette`	十六進位、RGB/RGBA 或其他主題使用的有效值

步驟 1：建立單獨的主題目錄和資源資料夾

首先，請確保您的自訂主題與 ownCloud 內建資源分開。一個簡單的佈局是：一個主題目錄，其中包含themes.json一個assets資料夾，用於存放您的商標、網站圖示和登入圖片。具體的路徑由您決定；重要的是，目錄必須掛載或以其他方式透過 . 暴露給 oCIS Web 服務WEB_ASSET_THEMES_PATH。

檔案管理器示意圖，展示了一個自訂的 ownCloud 主題資料夾，其中包含 assets 目錄、徽標、網站圖示、登入背景和 themes.json 檔案。

這是一個自訂 ownCloud Web 主題的範例文件佈局。主題定義和圖像資源都保存在一個專門的目錄中。

例如，主機端結構可能如下所示：

/srv/owncloud/themes/
└── acme/
    ├── themes.json
    └── assets/
        ├── logo.svg
        ├── logo-white.svg
        ├── favicon.png
        └── login-background.jpg

使用在特定環境下仍能保持清晰可辨的圖片素材。例如，一個在白色背景上清晰可見的深色徽標，在深色的頂部欄背景下可能會變得難以辨認，因此提供淺色和深色兩種版本的徽標通常很有幫助。此外，登入控制項後面的登入背景也應保持簡潔。品牌識別應在提升品牌識別度的同時，避免降低清晰度。

步驟 2：定義品牌名稱、商標路徑、網站圖示和登入背景

主題 JSON 是自訂的核心。此common部分包含共享品牌文本，例如名稱和標語。在 `<body>` 下，您可以定義預設的 Web 標誌和登入背景。 ownCloud 文件中的架構為 `<body>` 、`<logo>` 和`<logo> clients.web.defaults` 分別使用單獨的徽標鍵。topbarfaviconlogin

程式碼編輯器範例，展示了一個包含通用品牌值、網站標誌素材、網站圖示和登入背景條目的 themes.json 檔案。

這是主題檔案中品牌元素部分的編輯器風格插圖。請使用下方範例中記錄的物件結構，而不是將插圖視為可複製貼上的程式碼。

一個最小的起點可以基於以下支援的結構。請保持路徑與 Web 服務公開主題資源的 URL 路徑一致：

{
  "common": {
    "name": "Acme Cloud",
    "slogan": "Your files. Your workspace.",
    "logo": "themes/acme/assets/logo.svg",
    "urls": {
      "accessDeniedHelp": "",
      "imprint": "",
      "privacy": "",
      "accessibilityStatement": "",
      "universalAccessEasyLanguage": "",
      "universalAccessSignLanguage": ""
    }
  },
  "clients": {
    "android": {},
    "desktop": {},
    "ios": {},
    "web": {
      "defaults": {
        "appBanner": {},
        "logo": {
          "topbar": "themes/acme/assets/logo-white.svg",
          "favicon": "themes/acme/assets/favicon.png",
          "login": "themes/acme/assets/logo-white.svg"
        },
        "loginPage": {
          "backgroundImg": "themes/acme/assets/login-background.jpg"
        },
        "icons": {
          "universalAccess": "",
          "universalAccessEasyLanguage": "",
          "universalAccessSignLanguage": ""
        }
      },
      "themes": []
    }
  }
}

不要因為 JSON 解析器接受檔案就認為所有鍵都可以安全地省略。 ownCloud 指出，一些必需的主題鍵會在執行時間注入，但語法上有效的主題在語義上仍然可能是錯誤的。良好的生產實踐是從您實際運行的 Infinite Scale 版本中自帶的主題模板開始，僅進行必要的品牌更改，並保持其餘結構與該版本一致。

步驟 3：使用設計令牌變更主題顏色

顏色自訂應在主題條目下進行clients.web.themes。每個主題都可以使用 `<color_name>` 標識其是否為深色isDark，提供易於理解的樣式表name，並覆蓋設計標記。colorPalette通常在此處調整可見的品牌顏色。

程式碼編輯器圖示展示了 ownCloud 網頁設計中的品牌、主色、背景色、文字和資料夾顏色標記。

ownCloud Web 使用的顏色標記類型範例。請先更改已聚焦的顏色集，然後在展開調色板之前驗證對比度和懸停狀態。

如果想要打造簡潔的企業主題，可以先從少量樣式開始，而不是更改所有可用的顏色：

{
  "isDark": false,
  "name": "Acme Light",
  "logo": {
    "topbar": "themes/acme/assets/logo-white.svg",
    "favicon": "themes/acme/assets/favicon.png",
    "login": "themes/acme/assets/logo-white.svg"
  },
  "designTokens": {
    "colorPalette": {
      "background-default": "#ffffff",
      "background-sidebar": "#f5f7fa",
      "background-hover": "#eef4fb",
      "border": "#d8e0e8",
      "swatch-brand-default": "#176B87",
      "swatch-brand-hover": "#12556C",
      "swatch-brand-contrast": "#ffffff",
      "swatch-primary-default": "#176B87",
      "swatch-primary-hover": "#12556C",
      "swatch-primary-contrast": "#ffffff",
      "text-default": "#102A33",
      "text-inverse": "#ffffff",
      "text-muted": "#526873",
      "icon-folder": "#176B87"
    }
  }
}

關鍵在於權衡一致性和完整性。僅僅更改某些屬性swatch-brand-default或許能快速帶來視覺效果，但懸停、對比、側邊欄、邊框和文字等屬性可能仍保留預設主題。另一方面，未經測試就覆蓋數十個屬性可能會導致難以辨認的組合。對於大多數部署場景，建議先從品牌、主色、對比、背景、文字和邊框值入手，然後僅在預設值與設計明顯衝突的地方再進行擴充。

務必注意對比度。如果選擇淺色品牌色，請搭配深色對比元素，而不是強行使用白色文字。測試鍵盤焦點、懸停狀態、停用控制、深色模式（如有提供）以及高對比模式（如果使用者重視這些功能）。

步驟 4：掛載自訂主題並將 ownCloud 指向 themes.json 文件

目錄和 JSON 檔案準備就緒後，配置 Web 服務使其能夠讀取它們。相關的兩個環境變數分別是 `<your-theme-root>` 和 `<your-theme-json>` 。 `<your-theme-root> WEB_ASSET_THEMES_PATH` 用於告知 ownCloud 自訂主題根目錄的位置，而 ` WEB_UI_THEME_PATH<your-theme-json>` 用於選擇要載入的主題 JSON 檔案。

程式碼編輯器範例：Docker Compose 服務定義了 WEB_ASSET_THEMES_PATH、WEB_UI_THEME_PATH 和一個已掛載的主題目錄

本圖以 Docker Compose 風格示範如何掛載自訂主題目錄並配置兩個 ownCloud Web 主題環境變數。請根據實際部署情況調整路徑。

Docker Compose 部署可能採用以下模式：

services:
  ocis:
    image: owncloud/ocis:<your-tested-version>
    environment:
      WEB_ASSET_THEMES_PATH: /etc/ocis/themes
      WEB_UI_THEME_PATH: /etc/ocis/themes/acme/themes.json
    volumes:
      - ./themes:/etc/ocis/themes:ro

上面的圖片標籤僅為佔位符。在生產環境中，請使用您測試過的確切 oCIS 版本，而不是從範例複製浮動標籤。變更環境或掛載檔案後，請根據您的部署方式重新啟動或重新建立受影響的 oCIS 服務，以便讀取新設定。

ownCloud 文件中記錄了一個重要的備用方案：如果沒有提供自訂主題，或主題載入失敗，則會使用標準的 Infinite Scale 主題。這個備用方案很有用，因為缺少路徑並不一定會導致介面無法使用。但是，這也意味著重啟後看到 ownCloud 的預設外觀可能是診斷線索，表示您的自訂主題沒有載入。

如何驗證品牌識別是否已實際加載

登入頁面更改後不要停止檢查。全面的檢查應該涵蓋用戶實際會看到您品牌的所有位置。在新瀏覽器會話或隱私視窗中開啟網站，以降低快取資源遮擋目前狀態的可能性。

確認登入頁面使用了預期的徽標和背景。
登入後，請確認頂部欄標誌正確且在背景上清晰可辨。
請在瀏覽器標籤頁中查看自訂網站圖示。
開啟檔案區域，並驗證主按鈕、懸停狀態、側邊欄顏色、資料夾圖示和文字對比。
如果您提供淺色和深色主題，請在它們之間切換並分別進行驗證。
至少檢查一個較窄的瀏覽器寬度，以免寬大的標誌擠佔響應式頂部欄的空間。

當自訂主題不顯示時

預設的 ownCloud 主題仍然會載入。

首先驗證正在運行的容器或服務內部的路徑，而不僅僅是主機上的路徑。路徑WEB_ASSET_THEMES_PATH必須指向 Web 服務所識別的主題根目錄，並且WEB_UI_THEME_PATH必須指向該環境中的實際 JSON 檔案。 ownCloud 無法讀取從未掛載到容器中的主機路徑。

JSON 資料已加載，但缺少一張圖片。

檢查資源路徑（包括themes.json檔案名稱大小寫），以及該檔案是否存在於自訂主題目錄下。瀏覽器開發者工具可以幫助區分資源請求錯誤和主題問題。如果主題顏色載入正常，但某個標誌無法顯示，主題本身可能有效，只是該資源路徑錯誤。

頁面帶有品牌標識，但顏色看起來不一致。

這通常意味著只有部分調色板被覆蓋。添加相關的懸停和對比度標記，然後再次測試。不要透過大幅更改不相關的文字或背景標記來解決單一按鈕難以辨認的問題；進行最小的、一致的更改，並在整個介面上進行驗證。

主題在一個版本中運作正常，但升級後看起來就不對了。

主題令牌和前端行為可能會改變。在升級生產環境之前，請將您的自訂主題與目標 oCIS 版本的範本和文件進行比較。 ownCloud 的Web 自訂設定文件也解釋了受支援的配置/自訂資源與提供完全自訂編譯的 Web 資源之間的差異。

是否應該改為編輯已編譯的 Web 資源？

通常情況下，自訂主題並不適用於普通的品牌推廣。如果您希望在保持與官方 Web UI 風格一致的前提下，更改名稱、徽標、背景和設計元素，那麼自訂主題是更合適的選擇。只有當您開發或分發一個真正經過修改、無法透過主題或官方資源覆蓋實現的前端時，完全自訂編譯的資源才有意義。這種方法的維護成本更高，因為您需要負責確保自訂版本與 ownCloud Web 的未來更新相容。

一份實用的生產檢查清單

將自訂主題檔案放在內建應用程式目錄之外。
從已安裝的 oCIS 版本所記錄的主題結構開始。
當淺色和深色表面需要使用不同的標誌版本時，請使用不同的標誌變體。
首先覆蓋一組特定的設計標記，包括懸停和對比值。
盡可能以唯讀方式掛載主題目錄。
將兩者WEB_ASSET_THEMES_PATH都設定WEB_UI_THEME_PATH為服務內部可見的路徑。
部署變更後，重新啟動或重新建立 Web/oCIS 服務。
請驗證登入介面、頂部欄、網站圖示、文件區域、響應式佈局以及您展示的任何深色/高對比主題。
在每次 ownCloud Infinite Scale 重大升級之前，請重新測試主題。

對於目前的 Infinite Scale 部署，這種主題檔案方法使管理員能夠清晰地將應用程式程式碼和視覺標識分開。關鍵在於將主題視為版本化的部署資產：使用 ownCloud 版本支援的架構，保持圖像路徑的可預測性，透過設計令牌更改顏色而不是臨時編輯前端，並在整個 Web 介面上驗證結果，而不是僅從單個螢幕判斷是否成功。