Cum să personalizezi tema web Element și brandingul UI în 2026

Element Web oferă furnizorilor de auto-găzduire mai multe modalități utile de a face clientul să se simtă ca parte a organizației lor, dar calea acceptată s-a schimbat. Actualizarea importantă pentru implementările actuale este că Element Web v1.12.30, lansată la sfârșitul lunii septembrie 2026, a eliminat calea API Module și Customization la care ghidurile mai vechi ar putea face încă referire. În același timp, documentația oficială de configurare și tematizare continuă să ofere suport pentru branding prin config.json, teme personalizate, resurse de autentificare de marcă, pagini încorporate și noul API Module pentru modificări mai profunde ale comportamentului.

Această distincție contează. Dacă aveți nevoie doar de numele organizației, logo-ul de conectare, fundalul de conectare, link-urile din subsol, culorile implicite și o pagină principală sau de bun venit personalizată, de obicei nu este nevoie să creați o bifurcație în Element Web. Dacă doriți să rearanjați componentele principale ale interfeței utilizator sau să injectați logică personalizată a aplicației, configurarea în sine nu este suficientă.

Exemplele de mai jos utilizează stilul actual de configurare snake_case recomandat de Element. Referința oficială de configurare avertizează că este intenționat camelCase compatibilitate mai veche să dispară, așadar noile implementări ar trebui să evite construirea de noi brandinguri în jurul numelor cheilor vechi. Consultați documentația oficială de configurare Element Web , documentația oficială de teme și istoricul oficial al lansărilor .

Ce puteți personaliza fără a reconstrui Element Web

Configurația acceptată de Element acoperă mai multe aspecte legate de branding decât au nevoie mulți administratori. Principalele controale sunt:

Înainte de a schimba branding-ul implementării, înregistrați aspectul curent al Element Web pentru a putea compara rezultatul după reîncărcarea noii configurații.

Pasul 1: Începeți de la fișierul config.json al implementării

Element Web citește configurația din config.json, sau dintr-un fișier specific domeniului numit config.$domain.json. Conform documentației oficiale, fișierul specific domeniului este încercat mai întâi și nu este îmbinat cu fișierul de rezervă: se folosește una sau cealaltă configurație completă.

Dacă construiți singur Element Web, documentația proiectului recomandă copierea config.sample.jsonși personalizarea copiei. Pentru o implementare împachetată sau containerizată, editați sau montați fișierul de configurare în funcție de metoda de împachetare pe care o utilizați deja. Păstrați o copie de rezervă înainte de a o modifica.

Începeți cu cea mai mică schimbare de branding posibilă:

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

Valoarea brandînlocuiește „Element” într-o serie de șiruri de caractere și locații ale aplicației. Nu transformă Element Web într-un produs complet white-label; documentația proprie a Element precizează explicit că rebrandingul complet/etichetarea privată nu este acceptată doar prin aceste opțiuni de configurare.

Pasul 2: Creați un brand pentru experiența de conectare și de bun venit

Ecranul de autentificare este cel mai vizibil loc pentru a face ca o implementare auto-găzduită să pară intenționată. Element documentează în prezent patru proprietăți de branding: o imagine de fundal, o țintă de link pentru un logo de brand conectat, logo-ul antetului de autentificare și link-uri de subsol.

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

Folosește adrese URL HTTPS stabile pe care utilizatorii Element Web le pot accesa fără autentificare. O siglă sau un fundal găzduit în spatele unui alt perete de conectare s-ar putea să nu se încarce înainte ca utilizatorul Matrix să se conecteze. De asemenea, păstrează sigla lizibilă atât pe ecrane de mare densitate, cât și pe ecrane mai mici, în loc să încarci un fișier raster imens și să te bazezi pe browser pentru a-l micșora.

O pagină de autentificare personalizată poate schimba sigla din antet, fundalul și linkurile din subsol, păstrând intact fluxul de conectare Element Web subiacent.

Pasul 3: Creați o temă personalizată acceptată

Pentru culori și fonturi în interiorul clientului, utilizați formatul temei personalizate al Element, în loc să mențineți o colecție de selectori CSS fragili. Documentația temelor acceptă teme personalizate în timpul rulării prin setting_defaults.custom_themes. O temă personalizată primește un nume intern de forma custom-{theme.name}; aceasta este valoarea de utilizat în default_theme.

Acest exemplu compact modifică culorile principale pentru accentul, bara laterală, lista de camere și cronologia folosind chei documentate de 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"
        }
      }
    ]
  }
}

Același obiect temă poate defini și fonturi. Documentația actuală de tematizare a Element expune suplimentar un compoundobiect pentru suprascrierea token-urilor semantice din sistemul de design Compound. Această rută este utilă atunci când componentele mai noi ale interfeței utilizează token-uri Compound în loc de variabile de culoare mai vechi, dar ar trebui abordată conservator: suprascrieți doar token-urile semantice documentate și retestați după actualizări.

Dacă creați teme personalizate atât pentru luminoase, cât și pentru întunecate, dați-le nume diferite și setați-le is_darkcorect. O temă întunecată nu ar trebui creată prin simpla reducere a fiecărei valori RGB; verificați contrastul textului, stările camerelor selectate, textul secundar, culorile de avertizare, contururile de focalizare, controalele compozitorului de mesaje și insignele de notificare.

O temă personalizată ușoară poate alinia lista de camere, elementele importante și identitatea aplicației cu sistemul vizual al unei organizații, fără a înlocui ecranele de bază ale Element Web.

Pasul 4: Personalizați conținutul paginii de pornire, apoi reîncărcați pagina și verificați

Element Web poate indica, de asemenea, HTML găzduit extern pentru experiențele sale de bun venit și de pornire. embedded_pagesObiectul documentat acceptă welcome_urlși home_url. Un login_for_welcomeindicator separat poate face ca formularul de conectare să acționeze ca pagină de bun venit; când acest indicator este true, calea normală welcome_urleste dezactivată.

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

Folosește pagini încorporate pentru onboarding specific organizației, informații despre utilizarea acceptabilă, linkuri către documentația internă sau un mesaj concis despre starea serviciului. Tratează-le ca și conținut web: menține dependențele la un nivel minim, servește-le în siguranță și asigură-te că rămân disponibile independent de serverul principal Matrix.

După modificare config.json, reîncărcați Element Web. Documentația oficială precizează că o reîmprospătare a browserului este suficientă pentru implementările web, în ​​timp ce Element Desktop trebuie închis complet - inclusiv orice proces din tavă - și repornit. Dacă modificările apar inconsistent, verificați memoria cache înainte de a presupune că JSON este greșit. Fișierul README al implementării web Element spune în mod specific că /config.*.json, /i18n, /version, și /index.htmlnu ar trebui memorate în cache și recomandă revalidarea paginii rădăcină. Consultați fișierul README oficial al implementării Element Web .

Testează ambele stări de branding, atât cea luminoasă, cât și cea întunecată, dacă le oferi pe amândouă. Verifică navigarea, evidențierea camerei, contrastul textului, atașamentele și instrumentul de redactare a mesajelor - nu doar ecranul de conectare.

Când config.json nu este suficient

Tutorialele mai vechi vă pot spune să înlocuiți modulele prin sau să vă bazați pe puncte de personalizare vechi. Aceasta nu mai este o bază sigură pentru o nouă implementare. Documentațiacustomisations.json oficială de personalizare marchează acel mecanism ca fiind perimat, iar notele de lansare v1.12.30 din septembrie 2026 consemnează eliminarea API-ului Module & Customization vechi.

Pentru un comportament mai profund al aplicației, lucrați cu sistemul de module actual al Element Web descris în fișierul README al proiectului sau mențineți un fork dacă modificarea necesită într-adevăr control la nivel de sursă. Un fork oferă libertate maximă, dar face ca fiecare actualizare Element Web să fie responsabilitatea dumneavoastră. Acest compromis este rareori util dacă cerința dumneavoastră este doar un logo, o culoare, o scriere, un conținut de bun venit sau o pagină principală.

Un caz limită similar este grafica de previzualizare a linkurilor sociale. Documentația oficială de configurare menționează că valoarea og:imagese află în static index.html, în loc de config.json. Dacă aveți nevoie să modificați acea imagine, aceasta devine o personalizare la momentul construirii sau a fișierului static în loc de o setare de branding la momentul execuției.

Listă de verificare

• Deschideți pagina de conectare într-o fereastră privată a browserului și confirmați încărcarea logo-ului de autentificare, a fundalului și a linkurilor din subsol fără o sesiune existentă.
• Confirmați că aplicația afișează brandvaloarea dorită după conectare.
• Verificați dacă tema implicită selectată se încarcă pentru un profil de browser nou, nu doar pentru un cont care și-a modificat anterior setările de aspect.
• Verificați textul listei de camere, camerele selectate, etichetele secundare, cronologiile, controalele compozitorului de mesaje, avertismentele și stările de focalizare pentru un contrast lizibil.
• Dacă utilizați o pagină principală sau o pagină de bun venit personalizată, testați-o atunci când pagina externă nu este disponibilă, astfel încât să înțelegeți modul de eroare.
• Inspectați panoul de rețea al browserului și confirmați că valoarea așteptată config.jsoneste preluată după implementare; reverse-proxy-ul sau cache-ul CDN învechit este un motiv frecvent pentru care o configurație corectă pare să nu funcționeze.
• După fiecare actualizare Element Web, retestați temele personalizate și orice integrări Module API cu noua versiune înainte de a le implementa pentru toți utilizatorii.

Concluzie

Pentru majoritatea branding-urilor Element Web găzduite în regim self-hosting, păstrați stratul de configurare acceptat: brand, branding, default_theme, setting_defaults.custom_themes, și embedded_pages. Acest lucru face ca actualizările să fie mult mai simple decât aplicarea de patch-uri pentru componentele React sau utilizarea hook-urilor de personalizare vechi. Treceți la API-ul Module sau la o bifurcație întreținută numai atunci când cerința dvs. modifică cu adevărat comportamentul aplicației, mai degrabă decât aspectul.