Jak dostosować motyw internetowy Element i branding interfejsu użytkownika w 2026 roku

Element Web oferuje firmom hostingowym kilka przydatnych sposobów, aby klient poczuł się częścią swojej organizacji, ale obsługiwana ścieżka uległa zmianie. Ważną aktualizacją dla obecnych wdrożeń jest to, że Element Web v1.12.30, wydany pod koniec września 2026 roku, usunął starszą ścieżkę API modułów i dostosowywania, do której mogą nadal odwoływać się starsze przewodniki. Jednocześnie oficjalna dokumentacja konfiguracji i motywów nadal obsługuje branding poprzez config.jsonniestandardowe motywy, zasoby uwierzytelniania z marką, osadzone strony oraz nowszy API modułów, umożliwiający głębsze zmiany w zachowaniu.

To rozróżnienie ma znaczenie. Jeśli potrzebujesz tylko nazwy organizacji, logo logowania, tła logowania, linków stopki, domyślnych kolorów i firmowej strony głównej lub powitalnej, zazwyczaj nie musisz rozdzielać Element Web. Jeśli chcesz zmienić układ głównych komponentów interfejsu użytkownika lub dodać niestandardową logikę aplikacji, sama konfiguracja nie wystarczy.

Poniższe przykłady wykorzystują aktualny styl konfiguracji snake_case, zalecany przez Element. Oficjalny dokument referencyjny konfiguracji ostrzega, że ​​zgodność ze starszą wersją camelCase zostanie utracona, dlatego nowe wdrożenia powinny unikać tworzenia nowego brandingu wokół starszych nazw kluczy. Zapoznaj się z oficjalną dokumentacją konfiguracji sieciowej Element , oficjalną dokumentacją motywów oraz oficjalną historią wydań .

Co można dostosować bez przebudowy Element Web

Obsługiwana konfiguracja Elementu obejmuje więcej opcji brandingu, niż potrzebuje wielu administratorów. Główne elementy sterujące to:

Przed zmianą marki wdrożenia zapisz bieżący wygląd Element Web, aby móc porównać wynik po ponownym załadowaniu nowej konfiguracji.

Krok 1: Rozpocznij od pliku config.json wdrożenia

Element Web odczytuje konfigurację z pliku config.json, lub z pliku specyficznego dla domeny o nazwie config.$domain.json. Zgodnie z oficjalną dokumentacją, plik specyficzny dla domeny jest sprawdzany jako pierwszy i nie jest scalany z plikiem zapasowym: używana jest jedna kompletna konfiguracja lub inna.

Jeśli samodzielnie tworzysz Element Web, dokumentacja projektu zaleca skopiowanie config.sample.jsoni dostosowanie kopii. W przypadku wdrożenia w pakiecie lub kontenerze, edytuj lub zamontuj plik konfiguracyjny zgodnie z używaną metodą pakowania. Przed wprowadzeniem zmian należy wykonać kopię zapasową.

Zacznij od najmniejszej możliwej zmiany marki:

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

Wartość brandzastępuje „Element” w szeregu ciągów znaków i lokalizacji aplikacji. Nie zmienia to Element Web w produkt w pełni z białą etykietą; dokumentacja Element wyraźnie wskazuje, że pełne rebranding/prywatne etykietowanie nie jest obsługiwane wyłącznie za pomocą tych opcji konfiguracji.

Krok 2: Stwórz markę dla procesu logowania i powitania

Ekran uwierzytelniania to najbardziej widoczne miejsce, które sprawia, że ​​wdrożenie z własnym hostingiem wydaje się celowe. Element dokumentuje obecnie cztery właściwości brandingowe: obraz tła, miejsce docelowe linku dla powiązanego logo marki, logo nagłówka uwierzytelniania oraz linki w stopce.

{
  "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"
      }
    ]
  }
}

Używaj stabilnych adresów URL HTTPS, do których użytkownicy Element Web mogą uzyskać dostęp bez uwierzytelniania. Logo lub tło hostowane za inną ścianą logowania może nie załadować się przed zalogowaniem użytkownika Matrix. Zadbaj również o czytelność logo zarówno na ekranach o wysokiej rozdzielczości, jak i na mniejszych, zamiast przesyłać ogromny plik rastrowy i polegać na przeglądarce, która go zmniejszy.

Strona uwierzytelniania marki może zmieniać logo nagłówka, tło i łącza stopki, nie naruszając przy tym podstawowego procesu logowania Element Web.

Krok 3: Utwórz obsługiwany motyw niestandardowy

W przypadku kolorów i czcionek w kliencie należy użyć formatu motywu niestandardowego Element zamiast utrzymywać zbiór nietrwałych selektorów CSS. Dokumentacja motywów obsługuje motywy niestandardowe w czasie wykonywania za pośrednictwem setting_defaults.custom_themes. Motyw niestandardowy otrzymuje nazwę wewnętrzną w postaci custom-{theme.name}; jest to wartość do użycia w default_theme.

Ten kompaktowy przykład zmienia kolory głównego akcentu, paska bocznego, listy pomieszczeń i osi czasu przy użyciu kluczy udokumentowanych przez 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"
        }
      }
    ]
  }
}

Ten sam obiekt motywu może również definiować czcionki. Aktualna dokumentacja motywów Elementu dodatkowo udostępnia compoundobiekt do nadpisywania tokenów semantycznych z systemu projektowania Compound. Ta opcja jest przydatna, gdy nowsze komponenty interfejsu używają tokenów Compound zamiast starszych zmiennych kolorów, ale należy do niej podchodzić ostrożnie: nadpisywać tylko udokumentowane tokeny semantyczne i ponownie testować po aktualizacjach.

Jeśli tworzysz zarówno jasny, jak i ciemny motyw, nadaj im różne nazwy i ustaw je is_darkpoprawnie. Ciemnego motywu nie należy tworzyć, po prostu obniżając każdą wartość RGB; sprawdź kontrast tekstu, wybrane stany pomieszczeń, tekst dodatkowy, kolory ostrzeżeń, kontury fokusu, elementy sterujące tworzeniem wiadomości i plakietki powiadomień.

Lekki, niestandardowy motyw może dopasować listę pomieszczeń, wyróżnienia i identyfikację aplikacji do wizualnego systemu organizacji bez konieczności zastępowania głównych ekranów Element Web.

Krok 4: Dostosuj zawartość strony głównej, a następnie załaduj ją ponownie i zweryfikuj

Element Web może również wskazywać na zewnętrznie hostowany kod HTML w interfejsie powitalnym i głównym. Udokumentowany embedded_pagesobiekt obsługuje welcome_urli home_url. Osobna login_for_welcomeflaga może sprawić, że formularz logowania będzie działał jako strona powitalna; gdy ta flaga jest ustawiona na true, normalna welcome_urlścieżka jest wyłączona.

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

Używaj osadzonych stron do wprowadzania danych specyficznych dla organizacji, informacji o dopuszczalnym użytkowaniu, linków do dokumentacji wewnętrznej lub zwięzłego komunikatu o stanie usługi. Traktuj je jak treść internetową: minimalizuj zależności, serwuj je bezpiecznie i upewnij się, że są dostępne niezależnie od serwera domowego Matrix.

Po zmianie config.json, przeładuj Element Web. Oficjalna dokumentacja stwierdza, że ​​odświeżenie przeglądarki jest wystarczające w przypadku wdrożeń webowych, natomiast Element Desktop wymaga całkowitego zamknięcia – łącznie z procesami zasobnika – i ponownego uruchomienia. Jeśli zmiany pojawiają się niespójnie, sprawdź buforowanie, zanim założysz, że JSON jest błędny. Plik README wdrożenia webowego Element wyraźnie wskazuje /config.*.json, że /i18n, /version, i /index.htmlnie powinny być buforowane, i zaleca ponowną walidację strony głównej. Zobacz oficjalny plik README wdrożenia webowego Element .

Przetestuj zarówno jasny, jak i ciemny stan brandingu, jeśli udostępniasz oba. Sprawdź nawigację, wyróżnienia pokoi, kontrast tekstu, załączniki i edytor wiadomości – nie tylko ekran logowania.

Kiedy plik config.json nie wystarcza

Starsze samouczki mogą zalecać zastępowanie modułów za pomocą customisations.jsonstarszych punktów dostosowywania lub poleganie na nich. Nie stanowi to już bezpiecznej podstawy dla nowego wdrożenia. Oficjalna dokumentacja dotycząca dostosowywania oznacza ten mechanizm jako przestarzały, a informacje o wydaniu wersji 1.12.30 z września 2026 roku odnotowują usunięcie starszego interfejsu API modułów i dostosowywania.

Aby uzyskać bardziej szczegółowe informacje o działaniu aplikacji, należy korzystać z aktualnego systemu modułów Element Web opisanego w pliku README projektu lub utworzyć fork, jeśli zmiana rzeczywiście wymaga kontroli na poziomie kodu źródłowego. Fork daje maksymalną swobodę, ale jednocześnie sprawia, że ​​każda aktualizacja Element Web leży po Twojej stronie. Ten kompromis rzadko jest opłacalny, jeśli potrzebujesz jedynie logo, koloru, sformułowania, treści powitalnej lub strony głównej.

Jednym z powiązanych przypadków skrajnych jest podgląd grafiki z linkami społecznościowymi. Oficjalna dokumentacja konfiguracji informuje, że og:imagewartość ta znajduje się w zmiennej static index.html, a nie config.json. Jeśli chcesz zmienić ten obraz, staje się on dostosowaniem w czasie kompilacji lub pliku statycznego, a nie ustawieniem brandingu w czasie wykonywania.

Lista kontrolna weryfikacji

• Otwórz stronę logowania w prywatnym oknie przeglądarki i sprawdź, czy łącza uwierzytelniania, tło i stopka ładują się bez konieczności otwierania sesji.
• Sprawdź, czy aplikacja wyświetla właściwą brandwartość po zalogowaniu.
• Sprawdź, czy wybrany domyślny motyw zostanie załadowany w nowym profilu przeglądarki, a nie tylko w przypadku konta, na którym wcześniej zmieniono ustawienia wyglądu.
• Sprawdź czytelny kontrast tekstu na liście pomieszczeń, wybranych pomieszczeń, etykiet drugorzędnych, osi czasu, elementów sterujących tworzeniem wiadomości, ostrzeżeń i stanów fokusu.
• Jeśli używasz niestandardowej strony głównej lub powitalnej, przetestuj ją, gdy strona zewnętrzna jest niedostępna, aby zrozumieć tryb awarii.
• Sprawdź panel sieciowy przeglądarki i upewnij się, że oczekiwane dane config.jsonzostały pobrane po wdrożeniu; nieaktualny odwrotny serwer proxy lub buforowanie CDN to częsty powód, dla którego poprawna konfiguracja wydaje się nie działać.
• Po każdej aktualizacji Element Web należy ponownie przetestować niestandardowe motywy i wszelkie integracje z modułami API pod kątem nowej wersji, zanim udostępni się je wszystkim użytkownikom.

Podsumowanie

W przypadku większości samodzielnie hostowanych brandingów Element Web należy korzystać z obsługiwanej warstwy konfiguracji: brand, branding, default_theme, setting_defaults.custom_themesi embedded_pages. Dzięki temu aktualizacje są znacznie prostsze niż łatanie komponentów React lub poleganie na starszych hakach dostosowywania. Przechodź na API modułu lub fork utrzymany tylko wtedy, gdy Twoje wymagania faktycznie zmieniają zachowanie aplikacji, a nie jej wygląd.