Per un'installazione self-hosted di Element Web, imposta il nome dell'app e il tema predefinito nel suo file config.json, quindi utilizza le brandingopzioni documentate per il logo di accesso, lo sfondo, il link al logo e i link del piè di pagina. Per i colori personalizzati, definisci un tema in setting_defaults.custom_themese specifica default_themeil suo custom-nome. Queste impostazioni personalizzano Element, ma non lo trasformano in un prodotto completamente white-label.
Scopri quali controlli di branding ti servono
La configurazione di Element separa l'identità del prodotto, i temi di colore e le risorse della pagina. Scegli la modifica più piccola che ti permetta di raggiungere il tuo obiettivo:
| Obiettivo | Configurazione | Cosa cambia |
| Mostra il nome del tuo servizio | brand | Nome dell'app in varie stringhe e posizioni |
| Imposta un tema iniziale chiaro, scuro o personalizzato | default_theme | Tema di colori predefinito per la distribuzione |
| Modifica l'aspetto della schermata di accesso e di benvenuto | branding | Logo della pagina di autenticazione, sfondo, link al logo e link a piè di pagina |
| Imposta colori e caratteri personalizzati | setting_defaults.custom_themes | Opzioni del tema come token di colore e famiglie di caratteri |
Verificato: la documentazione di Element afferma che supporta alcune personalizzazioni, ma non il rebranding completo o l'etichettatura privata. Implicazione pratica: le modifiche brandnon sostituiranno ogni logo, icona, immagine o riferimento al prodotto. Se è necessario modificare ogni elemento visivo e stringa, è consigliabile mantenere una build personalizzata e ricontrollarla dopo gli aggiornamenti. Iniziate elencando gli elementi dell'interfaccia utente che i vostri utenti devono visualizzare prima di optare per un approccio basato esclusivamente sulla configurazione.
Aggiornare la configurazione distribuita in modo sicuro
Element Web viene letto config.jsonall'avvio. Esegui un backup del file corrente e modificalo direttamente per mantenere le impostazioni necessarie, come ad esempio il server home predefinito. Per un tarball di rilascio, il file si trova nella directory web distribuita; il pacchetto Debian utilizza /etc/element-web/config.json. Con Docker, monta la tua configurazione in /app/config.json. La posizione corretta dipende da come hai installato Element, quindi verifica il tuo metodo di distribuzione prima di modificarlo.
Aggiungi le seguenti chiavi all'oggetto JSON esistente, combinandole con le impostazioni già presenti. Non incollare questo testo in sostituzione dell'intera configurazione:
{
"brand": "Northstar Chat",
"default_theme": "dark",
"permalink_prefix": "https://chat.example.org",
"branding": {
"logo_link_url": "https://example.org",
"auth_header_logo_url": "https://chat.example.org/assets/logo.svg",
"welcome_background_url": "https://chat.example.org/assets/welcome.jpg",
"auth_footer_links": [
{ "text": "Help", "url": "https://example.org/help" },
{ "text": "Privacy", "url": "https://example.org/privacy" }
]
}
}
Sostituisci il nome di esempio, i nomi host e le risorse con i tuoi. brandModifica il nome dell'app in vari punti; permalink_prefixfa sì che i permalink condivisi puntino alla tua distribuzione Element anziché matrix.toa . Il logo e le voci di sfondo sono URL caricati dal browser. Servili tramite HTTPS da una posizione raggiungibile dai tuoi utenti e verifica che i controlli di accesso, la policy di sicurezza dei contenuti e la cache non li blocchino. La documentazione non specifica una dimensione universale per l'immagine del logo di autenticazione, quindi visualizza in anteprima la risorsa effettiva anziché presumere una dimensione fissa.
Dipende dall'implementazione: un file di configurazione influisce sull'istanza di Element Web che lo gestisce. Non modifica il app.element.ioservizio ufficiale né cambia automaticamente le app separate di Element per dispositivi mobili o desktop. Apporta la modifica sull'host o sul container che ospita la tua istanza.
Aggiungi un tema di colori personalizzato
Per un tema semplice di colori e caratteri, Element documenta le definizioni del tema personalizzato all'interno di setting_defaults.custom_themes. Il nome interno del tema è preceduto da custom-; usa quel nome completo in default_theme. Questo esempio mostra un tema personalizzato compatto. È un punto di partenza, non una tavolozza completa:
{
"default_theme": "custom-Northstar",
"setting_defaults": {
"custom_themes": [
{
"name": "Northstar",
"is_dark": false,
"fonts": {
"general": "Inter, sans-serif",
"monospace": "'Courier New'"
},
"colors": {
"accent-color": "#3157A4",
"primary-color": "#3157A4",
"warning-color": "#B5473C",
"sidebar-color": "#202A3B",
"roomlist-background-color": "#F3F5F8",
"roomlist-text-color": "#202938",
"timeline-background-color": "#FFFFFF",
"timeline-text-color": "#202938"
}
}
]
}
}
Integra queste chiavi nel tuo JSON esistente anziché creare un secondo setting_defaultsoggetto. Mantieni un contrasto leggibile tra testo, sfondi e controlli sia in modalità normale che evidenziata. Il riferimento al tema di Element include colori opzionali aggiuntivi, array di colori per nome utente e avatar, font personalizzati e token di progettazione Compound. Aggiungi solo i valori che hai esaminato nel riferimento corrente; una tavolozza incompleta potrebbe lasciare alcune parti dell'interfaccia con i valori predefiniti.
Un malinteso comune: l'impostazione default_themesceglie il valore predefinito per la distribuzione; la documentazione non la descrive come una policy che blocca le impostazioni di aspetto di ogni utente. Se hai bisogno di un tema rigorosamente applicato, verifica questo comportamento con la versione esatta di Element Web che utilizzi, invece di presumere che l'impostazione predefinita sia un blocco.
Applica la modifica e verifica il risultato
- Prima di distribuire il file, convalida la sintassi JSON. Una virgola mancante o un apice non corrispondente possono impedire il caricamento della configurazione. Assicurati che il JSON sia valido: i commenti non sono supportati.
- Dopo aver pubblicato il file, ricarica la pagina web. Se il browser mostra ancora il vecchio logo, prova ad aggiornare la pagina forzatamente o ad aprire una finestra di navigazione in incognito e verifica che il browser riesca a caricare correttamente l'URL di ciascuna risorsa.
- Esamina sia la schermata di accesso che l'interfaccia dopo aver effettuato l'accesso. Verifica che il nome dell'app, il tema scelto, la destinazione del logo, lo sfondo e i link nel piè di pagina siano corretti e controlla il contrasto del testo nell'elenco delle stanze e nella cronologia.
- Controlla gli strumenti per sviluppatori del browser e i log del server web per individuare eventuali richieste di configurazione o di risorse non riuscite. Se utilizzi una CDN o un proxy inverso, cancella o attendi il ripristino delle copie di configurazione e delle risorse memorizzate nella cache, a seconda della tua configurazione.
Per un test del tema in fase di esecuzione, le note di Element relative ai temi descrivono il caricamento di un URL di tema JSON dalla /devtoolssezione "Temi personalizzati". Consideratelo un flusso di lavoro di test o lato utente, non un sostituto per la distribuzione della configurazione desiderata a tutti i client. Per una distribuzione gestibile, mantenete la configurazione e le risorse sotto controllo di versione e ripetete questo controllo durante l'aggiornamento di Element Web.
Il comportamento qui descritto è conforme alla documentazione ufficiale di Element Web relativa alla configurazione e alla personalizzazione dei temi, verificata il 10 ottobre 2026. Prima di fare affidamento su un'impostazione, consultare i riferimenti relativi alla versione installata: documentazione di Element Web sulla configurazione , documentazione di Element Web sulla personalizzazione dei temi e documentazione di installazione di Element Web .