VN-Designer Entwickler-Dokumentation
05

Stil des Blocks (style.less)

Wie style.less übersetzt wird: Variablen aus den Eigenschaften, Hintergrund-Variablen, Bedingungen, Bereichsbildung per Instanzklasse, CSS-Layer und Rangfolge in Editor und Export, Grundschriftgröße, Buttons und Links, Theme-CSS gegen Block-CSS.

Überblick#

style.less ist der Stil eines Blocks. Das Programm übersetzt ihn mit LESS 4.9.1 bei jedem Zeichnen des Blocks neu, also bei jeder Änderung eines Werts im Eigenschaften-Panel. Statt style.less darf die Datei style.css heißen; sie läuft durch denselben Übersetzer.

less
padding-top: (@abstand * 1rem);
background: @kartenFarbe;
.titel { color: @akzent; }
@media (max-width: 767px) { padding-top: 0; }

Drei Dinge unterscheiden diese Datei von gewöhnlichem LESS:

  1. Variablen: Jede Eigenschaft aus <vn-parameters> steht als Variable @name zur Verfügung, dazu @bg-type, @bg-value, @bg-parallax und eine Reihe Theme-Variablen.
  2. Wurzel: Das Programm verpackt den ganzen Inhalt in .<Instanzklasse> { … }. Deklarationen ohne Selektor gelten deshalb für das Wurzelelement, jede Regel nur für Elemente im Block.
  3. Rangfolge: Im Editor steht das CSS in einem eigenen Layer; die Regeln dazu stehen unten.

Variablen aus den Eigenschaften#

Für jedes Feld mit Namen deklariert das Programm vor Ihrem LESS eine Variable. Der Wert hängt vom Feldtyp ab:

FeldtypLESS-WertBeispiel @nameVerwendung
rangeZahl ohne Einheit4padding-top: (@abstand * 1rem);
colorFarbe#4f46e5background: @akzent;, fade(@akzent, 20%)
checkboxtrue oder falsetrue& when (@schatten) { … }
select, text, textarea, imageText in einfachen Anführungszeichen'center'& when (@ausrichtung = 'center') { … }, url(@foto)
Hintergrund-Widgetkeine Variable @bg, sondern die Hintergrund-Variablen

Ein leerer range-Wert ergibt 0, eine leere Farbe #000000. In Text werden ' und @{ maskiert, so dass beliebige Eingaben das LESS nicht brechen.

Werte als Text in CSS ausgeben#

Weil Text als LESS-Text (mit Anführungszeichen) ankommt, ergibt aspect-ratio: @ratio; die ungültige Ausgabe aspect-ratio: '16/9';. Es gibt drei Wege, den reinen Wert zu bekommen (alle geprüft):

less
aspect-ratio: ~"@{ratio}";     // Eigenschaftswert ohne Anführungszeichen
@cls: e(@mode);                 // Namen für Selektoren: .grid-x, &.is-grid
.@{cls}-x { … }
&.ansicht-@{cls} { … }
SchreibweiseErgebnis bei @mode: 'grid'
@mode als Wert'grid' (mit Anführungszeichen)
~"@{mode}"grid
e(@mode)grid
.@{mode}-x (ohne e()).'grid'-x (ungültig)

Texte in content oder url(…) funktionieren direkt: content: "@{label}"; und url(@foto) (beides geprüft).

Gleichsetzen und Bedingungen#

Mit & when (…) { … } nimmt man Regeln abhängig von Werten auf (Guards von LESS).

less
& when (@schatten) { box-shadow: 0 8px 24px rgba(0, 0, 0, .2); }
& when not (@schatten) { box-shadow: none; }
& when (@ansicht = 'liste') { .karten { display: block; } }
& when (@anzahl > 2) and (@schatten) { … }

Was in einer Bedingung funktioniert (geprüft)

SchreibweiseErgebnis
when (@checkbox)wahr, wenn an
when (@checkbox = true)wahr, wenn an
when (@checkbox = false)wahr, wenn aus
when not (@checkbox)wahr, wenn aus
when (@text = 'abc') und when (@text = "abc")wahr bei Gleichheit
when (@text = abc) (ohne Anführungszeichen)nie wahr
when (@zahl > 2), when (@zahl = 2)Vergleich mit der Zahl
when (@zahl = "2")nie wahr (Zahl gegen Text)
when (@a) and (@b), when (@a), (@b)und, oder
when (default())Fehler: nur in Mixin-Guards erlaubt, das ganze CSS des Blocks fällt aus

Rechnen#

  • Multiplikation braucht keine Klammern: @n * 1rem, @n * 10%, 2 * @n; Klammern schaden aber nie ((@n * 1rem)), und das gilt als Standard in den Bausteinen.
  • Division nur in Klammern: (@n / 2). Das Programm schreibt @variable / zahl und @variable / @variable von selbst in Klammern um (line-height: @n / 2; ergibt 1.5). Eine Division von Literalen wird nicht umgeschrieben: 10px / 2 bleibt stehen, (10px / 2) ergibt 5px.
  • Einheiten hängen Sie an: (@n * 1px), (@n * 1%), (@n * 1vw).
  • CSS-Funktionen mit Variablen schreiben Sie als LESS-Text: font-size: ~"clamp(1rem, @{n}vw, 3rem)";, width: ~"calc(100% - @{n}rem)";. min() und max() mit Klammerrechnung gehen auch direkt: min((@n * 10px), 50%).
  • Farbfunktionen von LESS sind verfügbar: fade, lighten, darken, mix, contrast (geprüft).

Hintergrund-Variablen#

Hat der Block ein Hintergrund-Widget, kommen diese Variablen hinzu (bg steht für den Namen des Widgets; die Namen @bg-type, @bg-value, @bg-parallax sind fest, unabhängig vom Feldnamen):

VariableWertBedeutung
@bg-type'color', 'image' oder 'video'gewählte Art
@bg-value bei FarbeFarbe, z. B. #f3f4f6keine Anführungszeichen
@bg-value bei BildText, die Bildadresseurl(@bg-value) ergibt url("…")
@bg-value bei VideoText, die Videoadresse
@bg-parallaxtrue oder falseSchalter „Parallax-Effekt“ (nur bei Bild an)

Muster (aus themes/vn-studio-src/components/header1, erweitert um Parallax)

less
& when (@bg-type = 'color') { background-color: @bg-value; }
& when (@bg-type = 'image') {
  background-image: url(@bg-value);
  background-size: cover;
  background-position: center;
  & when (@bg-parallax = true) { background-attachment: fixed; }
}

Bei Bild mit eingeschaltetem Parallax hängt das Programm zusätzlich eine eigene Regel .<Instanzklasse> { background-attachment: fixed; } an. Parallax funktioniert also auch dann, wenn Ihr LESS @bg-parallax nie abfragt.

Theme-Variablen#

Zusätzlich zu den Feldern kennt jedes LESS diese Variablen, damit Blöcke aus Theme-Paketen ohne ihr Theme nicht an einer fehlenden Variable scheitern:

VariablenVorgabewert
@primaryColor#3B7DDD
@secondaryColor#6C757D
@successColor#28A745
@infoColor#17A2B8
@warningColor#FFC107
@dangerColor#DC3545
@mainFont, @display1Font, @display2Font, @display4Font, @display5FontPoppins
@display7FontRoboto
@display1Size bis @display7Size (1, 2, 4, 5, 7)4.25, 3, 0.875, 1.5, 1.06
@isRoundedButtons, @isGhostButtonBorder, @isAnimatedOnScroll, @isScrollToTopButtonfalse

Gehört der Block zu einem Theme-Paket, dessen params.json unter theme.settings eigene Variablen festlegt, ersetzen deren Werte die Vorgaben, siehe Theme-Eigenschaften. Ein Feld des Blocks mit gleichem Namen überschreibt beides.

Bereich und Wurzel#

Das Programm verpackt Ihr LESS so:

less
@abstand: 4;  // … alle Variablen
.vn-imp-meine-bloecke-bmw3s4eyec6ik {   // Instanzklasse
  /* Ihr style.less */
}

Die Instanzklasse trägt jede Block-Instanz einzeln (vn-imp-<alias>-<Block-Kennung>, siehe Pakete); zwei Blöcke desselben Typs stören sich deshalb nicht.

Daraus folgt (alles geprüft)

Sie schreibenErgebnisMeint
padding: 2rem;.wurzel { padding: 2rem; }das Wurzelelement selbst
.titel { … }.wurzel .titel { … }Nachfahren im Block
&.aktiv { … }.wurzel.aktiv { … }das Wurzelelement mit zusätzlicher Klasse
> .direkt { … }.wurzel > .direkt { … }direkte Kinder
.karte { &:hover { … } &-titel { … } }.wurzel .karte:hover, .wurzel .karte-titelübliches LESS-Verschachteln
h1, h2 { … } und * { … }.wurzel h1, .wurzel h2, .wurzel *gilt nur im Block
@media (…) { … }@media (…) { .wurzel … }Medienabfrage außen, Regel innen
@container, @layer, @supportswie @media
@keyframes, @font-faceohne Instanzklassegelten für die ganze Seite
body { … }, html { … }, :root { … }.wurzel body { … }trifft nie etwas

Zwei Eigenheiten, die der Übersetzer glättet:

  • Eine vorangestellte Sprachmarke aus eingefügtem Chat-Code (css: oder eine erste Zeile css) wird entfernt; sonst verschluckte LESS die erste Eigenschaft.
  • Zeilenkommentare // … entfallen in der Ausgabe, Blockkommentare /* … */ bleiben.

Fehler im LESS#

Scheitert die Übersetzung (Syntaxfehler, unbekannte Variable, Guard default()), geschieht Folgendes:

  • Der Block bekommt im Editor das rote Etikett „⚠ CSS-Fehler“; die Meldung steht im Tooltip.
  • Das CSS dieses Blocks ist leer (nicht nur die fehlerhafte Regel). Andere Blöcke sind nicht betroffen.
  • Eine Warnung steht in der Konsole der Entwicklerwerkzeuge.

Typische Ursachen: ein Name mit Umlaut oder $ als Eigenschaftsname, @import, ein nicht geschlossener Block, when (default()).

Rangfolge: Layer und Reihenfolge#

Editor und Export setzen das CSS unterschiedlich zusammen. Beides ist nötig zu verstehen, wenn ein Block im Editor anders aussieht als auf der fertigen Seite.

Im Editor#

Der Editor legt beim Start die Rangfolge der CSS-Layer fest (spätere gewinnen):

css
@layer app-ui, bootstrap-base, theme-base, vn-blocks;
LayerInhalt
app-uiOberfläche des Programms
bootstrap-baseBootstrap 5.0.1 für die Arbeitsfläche (@scope (#canvas))
theme-baseTheme-CSS des Pakets (@scope (#canvas)), siehe Theme-CSS
vn-blocksdas CSS aller Blöcke, übersetzt, mit Instanzklasse, ohne @scope
ohne LayerRegeln aus den Site-Einstellungen (Schrift, Schriftgröße, Typografie, Link-Stil) und „Eigenes CSS“

Im Export#

Es gibt keine Layer und kein @scope. Die Seite lädt vendor/bootstrap.min.css und danach style.css. In style.css stehen in dieser Reihenfolge: Theme-CSS (ungescopt), CSS aller Blöcke, Schriftregeln der Site-Einstellungen, feste Hilfsregeln des Programms (Menü, Links, Dialoge), zuletzt „Eigenes CSS“. Es entscheiden die gewöhnlichen Regeln: Wichtigkeit, dann Spezifität, dann Reihenfolge.

Wer gewinnt (gemessen)#

Alle Zeilen sind am laufenden Programm gemessen (Editor) und an einer aus dem Export gebauten Seite (Export).

FallEditorExport
Block-Regel gegen Bootstrap, beide ohne !importantBlock (Layer)Block (höhere Spezifität, später)
Block-Regel gegen Theme-CSS, beide ohne !importantBlockBlock (später)
Block !important gegen Bootstrap !important (z. B. .text-white)BootstrapBlock (höhere Spezifität)
Block !important gegen Theme-CSS !importantThemeSpezifität, dann Reihenfolge
Block !important gegen Site-Einstellung oder „Eigenes CSS“ mit !importantBlockSpezifität, dann Reihenfolge
Block ohne !important gegen „Eigenes CSS“ ohne !importantEigenes CSS (ohne Layer)Spezifität: meist Block
Block ohne !important gegen die Schriftgröße der Site (!important)SiteSite

Die Regel dahinter: Bei gewöhnlichen Angaben gewinnt der spätere Layer, ohne Layer gewinnt über alle Layer. Bei !important dreht sich die Rangfolge um: der frühere Layer gewinnt, ohne Layer verliert. Eine !important-Angabe im Block schlägt deshalb im Editor keine !important-Regel aus Bootstrap oder dem Theme-CSS.

Die Falle #canvas im Theme-CSS#

Das Theme-CSS steht im Editor in @scope (#canvas) { … }. Innerhalb von @scope ist #canvas der Scope-Wurzelknoten, und ein Selektor #canvas .x trifft dort nichts (geprüft). Für Regeln, die nur im Editor gelten sollen, schreiben Sie :scope#canvas .x.

Schreibweise im Theme-CSSEditorExport
.x { … }trifft .x in der Arbeitsflächetrifft .x
#canvas .x { … }trifft nichtstrifft nichts (es gibt kein #canvas)
:scope#canvas .x { … }trifft .x (nur im Editor)trifft nichts
:scope { --farbe: red; }setzt die Variable auf #canvassetzt sie auf html
html { … }, body { … }, :root { … }ohne Wirkunggilt normal

Medienabfragen verwenden im Editor die Fensterbreite des Programms, nicht die Breite der Arbeitsfläche. Handy und Tablet prüfen Sie in der Live-Vorschau (Schalter „Tablet“ und „Handy“).

Site-Einstellungen, die Ihr CSS überstimmen#

Einige Einstellungen des Projekts erzeugen CSS mit !important. Sie gelten für alle Blöcke und wirken auch auf Ihr Block-LESS:

EinstellungWirkt aufFolge für das Block-LESS
Schriftgröße Fließtext (neue Projekte: 1.2rem)body, p, li, td, th, blockquote, figcaption, label und die Textklassen älterer Pakete (Ältere Schreibweisen)font-size an diesen Elementen mit !important
Schrift für Fließtext und Menü, Schrift für ÜberschriftenTexte, Überschriften, Menü, .btnfont-family
Typografie je Element (H1–H6, P, LI, Buttons)die genannten Elementefont-family, font-size, font-weight, color, line-height mit !important
Globale Button-Ecken.btn ohne eigene Formborder-radius mit !important
Link-StilLinks in nav und außerhalbtext-decoration (ohne !important)

Was das für Sie heißt (gemessen, siehe oben):

  • p { font-size: 3rem; } im Block-LESS bleibt wirkungslos, solange die Schriftgröße der Site gesetzt ist. Legen Sie feine Größen auf div oder span, oder setzen Sie !important (.klasse { font-size: 3rem !important; }).
  • Die Schriftgröße gilt nur für Fließtext. Überschriften, Menü, Buttons und Links bleiben davon unberührt.

Die Praxisregel der mitgelieferten Bausteine: Farben, Rahmen und Schrift von Buttons und Links im Block-LESS mit !important setzen.

less
.tz-text .btn-primary {
  background-color: @akzent !important;
  border-color: @akzent !important;
  color: #fff !important;
}

Gemessen wurde: Eine Button-Regel ohne !important gewinnt im Editor und im Export gegen Bootstrap (siehe die Tabelle oben). !important schützt vor den Regeln, die dort nicht gewinnen: Theme-CSS mit höherer Spezifität oder !important und die Schriftregeln der Site. Bei !important gegen Bootstrap-!important beachten Sie die Warnung oben (Editor und Export weichen ab).

Der Button-Dialog setzt die Farbe als Bootstrap-Klasse (btn-primary …). Wählt der Nutzer „Eigene Farbe“, entfällt die Farbklasse und die Farben stehen als gewöhnlicher Inline-Stil am Element (ohne !important, im Code geprüft). Zielen Sie mit !important deshalb auf die Farbklasse (.btn-primary), nicht auf .btn: eine !important-Regel auf .btn überstimmt die eigene Farbe des Nutzers.

Block-CSS oder Theme-CSS?#

Gehört ins Block-LESS (style.less)Gehört ins Theme-CSS (plugins/theme/css/style.css)
alles, was von Eigenschaften des Blocks abhängt (@name)Regeln ohne Variablen, die mehrere Blöcke teilen (Grundtypografie des Themes, gemeinsame Hilfsklassen)
Aussehen dieses Bausteins.btn-Formen und Standardfarben des Themes
@media, @container für diesen Blockseitenweite Regeln (body, :scope)
@keyframes des Blocks (mit Kürzel im Namen)Schriften (@font-face) mit Dateien aus dem Paket

Das Block-LESS wird mit dem Block gespeichert und beim Export nur für benutzte Blöcke ausgegeben. Das Theme-CSS wird einmal pro Projekt geladen; ein späteres Paket-Update ändert es in bestehenden Projekten nicht (Nur einmal pro Projekt). Ein Fehler im Theme-CSS lässt sich deshalb später schlechter beheben als einer im Block.

Beispiel#

Das Beispiel kombiniert Variablen, Bedingungen, Hintergrund-Variablen, Medienabfrage und die Praxisregel für Buttons. Es gehört zum Teaser-Block aus Eingabefelder; dort steht auch das Template.

less
position: relative;
padding-top: (@abstandOben * 1rem);
padding-bottom: (@abstandUnten * 1rem);
color: @textFarbe;

& when (@bg-type = 'color') { background-color: @bg-value; }
& when (@bg-type = 'image') {
  background-image: url(@bg-value);
  background-size: cover;
  background-position: center;
  & when (@bg-parallax = true) { background-attachment: fixed; }
}

.tz-inner { position: relative; z-index: 1; display: flex; gap: 2rem; align-items: center; }
.tz-foto { max-width: 40%; border-radius: 0.5rem; }
.tz-vorteile { white-space: pre-line; font-size: 1.1rem; }
&.tz-mitte .tz-inner { justify-content: center; text-align: center; }
.tz-text h2 { color: @akzent; }
.tz-text .btn-primary {
  background-color: @akzent !important;
  border-color: @akzent !important;
  color: #fff !important;
}
@media (max-width: 767px) {
  .tz-inner { flex-direction: column; }
  .tz-foto { max-width: 100%; }
}

Übersetzt ergibt das bei abstandOben = 4 und Bildhintergrund unter anderem:

css
.vn-imp-beispiel-teaser-bmw3se032ai5q {
  position: relative;
  padding-top: 4rem;
  padding-bottom: 4rem;
  color: #1f2937;
  background-image: url("assets/x.jpg");
  background-size: cover;
  background-position: center;
  background-attachment: fixed;
}
.vn-imp-beispiel-teaser-bmw3se032ai5q .tz-inner { … }

Prüfliste#

  • Jede Variable @name im LESS ist ein Feld in <vn-parameters> (oder eine Hintergrund-/Theme-Variable).
  • @bg-… nur, wenn ein Hintergrund-Widget da ist, und nur in einer Bedingung auf @bg-type.
  • Select-Werte als Text vergleichen (@x = 'a'), in Eigenschaften und Selektoren mit ~"@{x}" oder e(@x).
  • body, html, :root nicht im Block-LESS.
  • Keine BOM, kein @import, kein default().
  • Namen in @keyframes/@font-face mit Kürzel.
  • !important nur dort, wo es gebraucht wird, und danach in der Live-Vorschau gegengeprüft.