如何在 2026 年自訂 Element 網頁主題和 UI 品牌

Element Web 為自架用戶提供了多種實用方式，讓客戶感受到自己是組織的一部分，但其支援路徑已變更。對於目前部署而言，重要的更新是 Element Web v1.12.30（於 2026 年 9 月下旬發布）移除了舊版模組和自訂 API 路徑，舊版指南中可能仍會引用這些路徑。同時，官方配置和主題文件仍然支援透過config.json自訂主題、品牌身份驗證資源、嵌入式頁面以及用於更深層行為更改的新模組 API 進行品牌化。

這種區別很重要。如果您只需要組織名稱、登入標誌、登入背景、頁腳連結、預設顏色以及品牌化的首頁或歡迎頁面，通常無需 fork Element Web。但如果您想要重新排列核心 UI 元件或註入自訂應用程式邏輯，僅靠配置是不夠的。

以下範例使用 Element 建議的目前 snake_case 配置樣式。官方配置參考文件警告說，舊的 camelCase 相容性將被移除，因此新的部署應避免圍繞舊版鍵名建立新的品牌標誌。請參閱Element Web 官方配置文件、官方主題文件和官方發布歷史記錄。

無需重建 Element Web 即可自訂的內容

Element 支援的配置涵蓋的品牌識別功能遠超過許多管理員的實際需求。主要控制項包括：

在變更部署品牌之前，請記錄目前 Element Web 外觀，以便在重新載入新配置後進行比較。

步驟 1：從部署的 config.json 檔案開始。

config.jsonElement Web 從 `<configuration>` 檔案或名為 `<domain_file>` 的特定網域檔案中讀取設定config.$domain.json。根據官方文檔，系統會先嘗試使用特定網域的文件，並且不會將其與備用文件合併：系統只會使用其中一個完整的配置。

如果您自行建立 Element Web，專案文件建議您複製config.sample.json並自訂副本。對於打包或容器化部署，請根據您使用的打包方式編輯或掛載設定檔。修改前請務必備份。

首先，從最小的品牌改動開始：

{
  "brand": "Acme Chat",
  "default_theme": "light"
}

該brand值會替換多個應用程式字串和位置中的“Element”。但它並不會將 Element Web 變成完全的白標產品；Element 本身的文檔明確指出，僅透過這些配置選項無法實現完整的品牌重塑/私人品牌化。

步驟 2：打造品牌化的登入與歡迎體驗

身分驗證介面是讓自託管部署顯得更用心、最直覺的地方。 Element 目前提供了四個品牌屬性：背景圖片、指向品牌標誌的連結目標、身份驗證頁首標誌和頁腳連結。

{
  "brand": "Acme Chat",
  "branding": {
    "welcome_background_url": "https://chat.example.com/assets/login-background.jpg",
    "logo_link_url": "https://www.example.com/",
    "auth_header_logo_url": "https://chat.example.com/assets/acme-logo.svg",
    "auth_footer_links": [
      {
        "text": "Privacy",
        "url": "https://www.example.com/privacy"
      },
      {
        "text": "Support",
        "url": "https://www.example.com/support"
      }
    ]
  }
}

使用穩定的 HTTPS URL，確保您的 Element Web 使用者無需身份驗證即可存取。如果標誌或背景圖片託管在其他登入頁面之後，則在 Matrix 使用者登入之前可能無法載入。此外，請確保標誌在高解析度螢幕和小螢幕上都清晰可讀，而不是上傳巨大的柵格檔案並依賴瀏覽器進行縮放。

品牌化的身份驗證頁面可以更改頁眉徽標、背景和頁腳鏈接，同時保持底層 Element Web 登入流程不變。

步驟 3：建立受支援的自訂主題

對於客戶端內部的顏色和字體，請使用 Element 的自訂主題格式，而不是維護一組脆弱的 CSS 選擇器。主題文檔支援運行時自訂主題setting_defaults.custom_themes。自訂主題會接收一個內部名稱，格式為 `<name>` custom-{theme.name}；該名稱是要在 `<name>` 中使用的值default_theme。

這個簡潔的範例使用 Element 文件中記錄的鍵來更改主強調色、側邊欄、房間清單和時間軸的顏色：

{
  "default_theme": "custom-Acme Light",
  "setting_defaults": {
    "custom_themes": [
      {
        "name": "Acme Light",
        "is_dark": false,
        "colors": {
          "accent-color": "#2563eb",
          "primary-color": "#1d4ed8",
          "warning-color": "#dc2626",
          "sidebar-color": "#0f172a",
          "roomlist-background-color": "#f8fafc",
          "roomlist-text-color": "#172033",
          "roomlist-text-secondary-color": "#64748b",
          "roomlist-highlights-color": "#ffffff",
          "roomlist-separator-color": "#e2e8f0",
          "timeline-background-color": "#ffffff",
          "timeline-text-color": "#172033",
          "timeline-text-secondary-color": "#64748b",
          "timeline-highlights-color": "#f1f5f9"
        }
      }
    ]
  }
}

同一個主題物件還可以定義字體。 Element 目前的主題文件還提供了一個compound對象，用於覆蓋 Compound 設計系統中的語義標記。當新的介面元件使用 Compound 標記而不是舊的顏色變數時，這種方法非常有用，但應該謹慎使用：僅覆蓋文件中已記錄的語義標記，並在升級後重新測試。

如果您建立了淺色和深色自訂主題，請為它們指定不同的名稱並is_dark正確設定。建立深色主題不應只是簡單地降低所有 RGB 值；請檢查文字對比度、選取房間狀態、輔助文字、警告顏色、焦點輪廓、訊息撰寫控制和通知徽章。

輕量級的自訂主題可以將房間清單、亮點和應用程式識別與組織的視覺系統保持一致，而無需替換核心 Element Web 螢幕。

步驟 4：自訂主頁內容，然後重新載入並驗證

Element Web 也可​​以指向外部託管的 HTML 以提供歡迎頁面和首頁體驗。文件中所述的embedded_pages物件支援 `< input type="web" welcome_url>` 和`<input type="web home_url">`。一個單獨的login_for_welcome標誌可以讓登入表單充當歡迎頁面；當該標誌為真時，常規welcome_url路徑將被停用。

{
  "embedded_pages": {
    "welcome_url": "https://chat.example.com/assets/welcome.html",
    "home_url": "https://chat.example.com/assets/home.html"
  }
}

使用嵌入式頁面進行組織特定的入職培訓、提供可接受的使用資訊、新增內部文件連結或發佈簡潔的服務狀態訊息。將它們視為 Web 內容：盡量減少依賴項，確保其安全可靠，並確保它們獨立於 Matrix 主伺服器可用。

修改後config.json，請重新載入 Element Web。官方文件指出，對於 Web 部署，刷新瀏覽器即可；而 Element Desktop 則必須完全退出（包括所有托盤進程）並重新啟動。如果更改顯示不一致，請先檢查緩存，然後再判斷 JSON 是否錯誤。 Element 的 Web 部署 README 文件明確指出/config.*.json，` <head>` /i18n、` /version<body>`、`<body>` 和/index.html`<body>` 不應緩存，並建議重新驗證根頁面。請參閱Element Web 官方部署 README 文件。

如果同時提供了淺色和深色品牌標識，請分別進行測試。檢查導航、房間高亮顯示、文字對比、附件和郵件編輯器，而不僅僅是登入介面。

當 config.json 檔案不足以滿足需求時

較早的教學可能會指導您透過舊版自訂點替換模組customisations.json或依賴舊版自訂點。但這已不再是新部署的安全基礎。官方自訂文件已將該機制標記為已棄用，2026 年 9 月發布的 v1.12.30 版本說明也記錄了舊版模組和自訂 API 的移除。

若要實現更深層的應用行為，請使用 Element Web 專案 README 檔案中所述的現有模組系統；或者，如果變更確實需要原始程式碼層級的控制，則需要維護一個分支。分支可以提供最大的自由度，但也意味著您需要負責 Element Web 的每一次升級。如果您的需求只是標誌、顏色、文字、歡迎內容或首頁，那麼這種權衡通常並不值得。

一個相關的特殊情況是社交連結預覽圖。官方配置文件指出，該og:image值位於靜態文件中index.html，而config.json不是運行時文件中。如果您需要變更該映像，則需要進行建置時或靜態檔案自訂，而不是執行階段品牌設定。

核查清單

• 在隱私瀏覽器視窗中開啟登入頁面，確認在沒有現有會話的情況下，身份驗證標誌、背景和頁腳連結都能載入。
• brand登入後，請確認套用顯示的值是否正確。
• 驗證所選預設主題是否能為新的瀏覽器設定檔加載，而不僅僅是為先前已更改外觀設定的帳戶加載。
• 檢查房間清單文字、選定房間、輔助標籤、時間軸、訊息編輯器控制項、警告和焦點狀態，以確保對比度清晰易讀。
• 如果您使用自訂主頁或歡迎頁面，請在外部頁面不可用時進行測試，以便了解故障模式。
• 檢查瀏覽器網路面板，確認config.json部署後是否取得到預期內容；過時的反向代理或 CDN 快取是導致正確配置無法正常運作的常見原因。
• 每次 Element Web 升級後，在將自訂主題和任何模組 API 整合推廣到所有使用者之前，請針對新版本重新測試這些整合。

結論

對於大多數自架的 Element Web 品牌化項目，請堅持使用受支援的配置層：brand` <React>`、 ` <React>` branding、 `<React> `、`<React>` 和`<React>`。這樣可以大大簡化升級過程，比修補 React 元件或依賴舊版自訂鉤子要簡單得多。只有當您的需求真正改變應用程式的行為而非外觀時，才應遷移到模組 API 或維護良好的分支版本。default_themesetting_defaults.custom_themesembedded_pages