Aggiungere fogli di stile (CSS) e JavaScript (JS) al tema in Drupal 8

03/10/2025, by Ivan

Questa documentazione è per i temi. Per informazioni sui moduli consulta Aggiungere fogli di stile (CSS) e JavaScript (JS) in un modulo Drupal 8.

In Drupal 8 i fogli di stile (CSS) e JavaScript (JS) vengono caricati tramite lo stesso sistema sia per i moduli (codice) che per i temi: le librerie di risorse.

Per chiarezza, queste istruzioni sono destinate SOLO ai temi e non si applicano ai moduli.

Drupal utilizza un principio di alto livello: le risorse (CSS o JS) vengono caricate solo se dichiari a Drupal di caricarle. Drupal non carica tutte le risorse su ogni pagina perché questo ridurrebbe le prestazioni.

Differenze rispetto a Drupal 7

Sei differenze principali rispetto a Drupal 7:

Il file THEME.info.yml sostituisce THEME.info (con le stesse informazioni).
La proprietà stylesheets (per aggiungere CSS) in THEME.info è stata rimossa e sostituita da *.libraries.yml, dove * è il nome del tema o modulo.
La proprietà scripts (per aggiungere JS) in THEME.info è stata rimossa e anch’essa sostituita da *.libraries.yml.
Verranno caricati solo i CSS/JS richiesti. Ad esempio, jQuery non viene più caricato automaticamente: deve essere dichiarato in *.libraries.yml. Se la tua tema ha bisogno di jQuery o altre risorse su tutte le pagine, dichiarale lì e poi includi la libreria in THEME.info.yml.
In Drupal 7 le librerie venivano definite tramite hook_library_info(). Ora sono definite in *.libraries.yml.
Le funzioni drupal_add_css(), drupal_add_js() e drupal_add_library() sono state rimosse, sostituite da #attached.

Procedura

Per caricare CSS o JS:

Salva il CSS o JS in un file seguendo le convenzioni di naming e organizzazione.
Definisci una “libreria” nel file *.libraries.yml della tua tema.
Allega la libreria a tutte le pagine, a template Twig specifici oppure a subset di pagine tramite preprocess.

Definire una libreria

Tutte le librerie vanno definite nel file *.libraries.yml della tua tema. Se la tua tema si chiama fluffiness, il file sarà fluffiness.libraries.yml:

# fluffiness.libraries.yml
cuddly-slider:
  version: 1.x
  css:
    theme:
      css/cuddly-slider.css: {}
  js:
    js/cuddly-slider.js: {}

Aggiungere jQuery alla libreria

cuddly-slider:
  version: 1.x
  css:
    theme:
      css/cuddly-slider.css: {}
  js:
    js/cuddly-slider.js: {}
  dependencies:
    - core/jquery

Allegare librerie globali

Esempio con global-styling e global-scripts in fluffiness.info.yml:

libraries:
  - fluffiness/global-styling
  - fluffiness/global-scripts

Allegare da un template Twig

{{ attach_library('fluffiness/cuddly-slider') }}
<div>Some fluffy markup {{ message }}</div>

Allegare a subset di pagine

function fluffiness_preprocess_page(&$variables) {
  $variables['#attached']['library'][] = 'fluffiness/cuddly-slider';
}

Proprietà CSS/JS

Puoi aggiungere attributi, media, preprocess, weight e altro alle risorse definite nelle librerie. Ad esempio:

{ attributes: { crossorigin: anonymous } }
{ media: print }
{ preprocess: false }
{ type: external, minified: true }
{ weight: 1 }

Pannello libraries-override

Puoi usare libraries-override in THEME.info.yml per rimuovere o sostituire risorse ereditate:

libraries-override:
  core/modernizr: false

Pannello libraries-extend

Permette di estendere librerie core con ulteriori risorse:

libraries-extend:
  core/drupal.user:
    - classy/user1
    - classy/user2

Altri esempi

Impostare il caricamento degli asset JS nell’header: { header: true }.
Passare variabili PHP a JS tramite drupalSettings.
Usare attributi come async o defer in script esterni.
Dichiarare librerie esterne come Bootstrap o Font Awesome con type: external.

Extra Block Types (EBT) - Nuova esperienza con Layout Builder❗

❗Extra Paragraph Types (EPT) - Nuova esperienza con Paragraphs