Font-Modul

Diese API-Referenz hilft dir zu verstehen, wie du next/font/google und next/font/local verwendest. Für Funktionen und Anwendung siehe die Seite Schriftarten optimieren.

Font-Funktionsargumente

Zur Verwendung siehe Google Fonts und Lokale Schriftarten.

src

Der Pfad zur Schriftartdatei als String oder Array von Objekten (mit Typ Array<{path: string, weight?: string, style?: string}>) relativ zum Verzeichnis, in dem die Font-Loader-Funktion aufgerufen wird.

Verwendet in next/font/local

• Erforderlich

Beispiele:

• src:'./fonts/my-font.woff2' wobei my-font.woff2 in einem Verzeichnis namens fonts innerhalb des app-Verzeichnisses liegt
• src:[{path: './inter/Inter-Thin.ttf', weight: '100',},{path: './inter/Inter-Regular.ttf',weight: '400',},{path: './inter/Inter-Bold-Italic.ttf', weight: '700',style: 'italic',},]
• wenn die Font-Loader-Funktion in app/page.tsx mit src:'../styles/fonts/my-font.ttf' aufgerufen wird, liegt my-font.ttf in styles/fonts im Projektstamm

weight

Das Schriftgewicht (weight) mit folgenden Möglichkeiten:

• Ein String mit möglichen Werten der verfügbaren Gewichte für die spezifische Schriftart oder ein Wertebereich, wenn es sich um eine variable Schriftart handelt
• Ein Array von Gewichtswerten, wenn die Schriftart keine variable Google-Schriftart ist. Dies gilt nur für next/font/google.

Verwendet in next/font/google und next/font/local

• Erforderlich, wenn die verwendete Schriftart keine variable Schriftart ist

Beispiele:

• weight: '400': Ein String für einen einzelnen Gewichtswert - für die Schriftart Inter sind die möglichen Werte '100', '200', '300', '400', '500', '600', '700', '800', '900' oder 'variable' (wobei 'variable' der Standardwert ist)
• weight: '100 900': Ein String für den Bereich zwischen 100 und 900 für eine variable Schriftart
• weight: ['100','400','900']: Ein Array von 3 möglichen Werten für eine nicht-variable Schriftart

style

Der Schriftstil (style) mit folgenden Möglichkeiten:

• Ein String-Wert mit Standardwert 'normal'
• Ein Array von Stilwerten, wenn die Schriftart keine variable Google-Schriftart ist. Dies gilt nur für next/font/google.

Verwendet in next/font/google und next/font/local

• Optional

Beispiele:

• style: 'italic': Ein String - kann normal oder italic für next/font/google sein
• style: 'oblique': Ein String - kann für next/font/local jeden Wert annehmen, sollte aber aus den Standard-Schriftstilen stammen
• style: ['italic','normal']: Ein Array von 2 Werten für next/font/google - die Werte sind aus normal und italic

subsets

Die Schriftuntergruppen (subsets) definiert durch ein Array von String-Werten mit den Namen jeder Untergruppe, die vorgeladen werden soll. Schriftarten, die über subsets angegeben werden, erhalten ein Link-Preload-Tag im Head-Bereich, wenn die Option preload true ist (Standardeinstellung).

Verwendet in next/font/google

• Optional

Beispiele:

• subsets: ['latin']: Ein Array mit der Untergruppe latin

Eine Liste aller Untergruppen findest du auf der Google-Fonts-Seite deiner Schriftart.

axes

Einige variable Schriftarten haben zusätzliche axes, die einbezogen werden können. Standardmäßig wird nur das Schriftgewicht einbezogen, um die Dateigröße gering zu halten. Die möglichen Werte für axes hängen von der spezifischen Schriftart ab.

Verwendet in next/font/google

• Optional

Beispiele:

• axes: ['slnt']: Ein Array mit dem Wert slnt für die variable Schriftart Inter, die slnt als zusätzliche axes hat, wie hier gezeigt. Die möglichen axes-Werte für deine Schriftart findest du, indem du den Filter auf der Google variable fonts-Seite verwendest und nach Achsen außer wght suchst

display

Das Font-Display (display) mit möglichen String-Werten von 'auto', 'block', 'swap', 'fallback' oder 'optional' mit Standardwert 'swap'.

Verwendet in next/font/google und next/font/local

• Optional

Beispiele:

• display: 'optional': Ein String mit dem Wert optional

preload

Ein Boolean-Wert, der angibt, ob die Schriftart vorgeladen werden soll oder nicht. Der Standardwert ist true.

Verwendet in next/font/google und next/font/local

• Optional

Beispiele:

• preload: false

fallback

Die Ersatzschriftart, die verwendet wird, wenn die Schriftart nicht geladen werden kann. Ein Array von Strings mit Ersatzschriftarten ohne Standardwert.

• Optional

Verwendet in next/font/google und next/font/local

Beispiele:

• fallback: ['system-ui', 'arial']: Ein Array, das die Ersatzschriftarten auf system-ui oder arial setzt

adjustFontFallback

• Für next/font/google: Ein Boolean-Wert, der bestimmt, ob eine automatische Ersatzschriftart verwendet werden soll, um Cumulative Layout Shift zu reduzieren. Der Standardwert ist true.
• Für next/font/local: Ein String- oder Boolean-false-Wert, der bestimmt, ob eine automatische Ersatzschriftart verwendet werden soll, um Cumulative Layout Shift zu reduzieren. Die möglichen Werte sind 'Arial', 'Times New Roman' oder false. Der Standardwert ist 'Arial'.

Verwendet in next/font/google und next/font/local

• Optional

Beispiele:

• adjustFontFallback: false: für next/font/google
• adjustFontFallback: 'Times New Roman': für next/font/local

variable

Ein String-Wert zur Definition des CSS-Variablennamens, der verwendet werden soll, wenn der Stil mit der CSS-Variablenmethode angewendet wird.

Verwendet in next/font/google und next/font/local

• Optional

Beispiele:

• variable: '--my-font': Die CSS-Variable --my-font wird deklariert

declarations

Ein Array von Font-Face-Deskriptor-Schlüssel-Wert-Paaren, die das generierte @font-face weiter definieren.

Verwendet in next/font/local

• Optional

Beispiele:

• declarations: [{ prop: 'ascent-override', value: '90%' }]

Stile anwenden

Du kannst die Schriftstile auf drei Arten anwenden:

• className
• style
• CSS-Variablen

className

Gibt einen schreibgeschützten CSS-className für die geladene Schriftart zurück, der einem HTML-Element übergeben werden kann.

<p className={inter.className}>Hello, Next.js!</p>

style

Gibt ein schreibgeschütztes CSS-style-Objekt für die geladene Schriftart zurück, das einem HTML-Element übergeben werden kann, einschließlich style.fontFamily für den Zugriff auf den Schriftfamiliennamen und die Ersatzschriftarten.

<p style={inter.style}>Hello World</p>

CSS-Variablen

Wenn du deine Stile in einem externen Stylesheet festlegen und dort zusätzliche Optionen angeben möchtest, verwende die CSS-Variablenmethode.

Importiere neben der Schriftart auch die CSS-Datei, in der die CSS-Variable definiert ist, und setze die Variable-Option des Font-Loader-Objekts wie folgt:

import { Inter } from 'next/font/google'
import styles from '../styles/component.module.css'
 
const inter = Inter({
  variable: '--font-inter',
})

Um die Schriftart zu verwenden, setze die className des übergeordneten Containers des zu stylenden Texts auf den variable-Wert des Font-Loaders und die className des Texts auf die styles-Eigenschaft aus der externen CSS-Datei.

<main className={inter.variable}>
  <p className={styles.text}>Hello World</p>
</main>

Definiere die Selektor-Klasse text in der CSS-Datei component.module.css wie folgt:

.text {
  font-family: var(--font-inter);
  font-weight: 200;
  font-style: italic;
}

Im obigen Beispiel wird der Text Hello World mit der Schriftart Inter und der generierten Ersatzschriftart mit font-weight: 200 und font-style: italic gestylt.

Verwendung einer Schriftarten-Definitionsdatei

Jedes Mal, wenn du die localFont- oder Google-Font-Funktion aufrufst, wird diese Schriftart als eine Instanz in deiner Anwendung gehostet. Wenn du also dieselbe Schriftart an mehreren Stellen verwenden musst, solltest du sie an einer Stelle laden und das zugehörige Schriftart-Objekt importieren, wo du es benötigst. Dies geschieht über eine Schriftarten-Definitionsdatei.

Erstelle zum Beispiel eine fonts.ts-Datei in einem styles-Ordner im Stammverzeichnis deines App-Verzeichnisses.

Definiere dann deine Schriftarten wie folgt:

import { Inter, Lora, Source_Sans_3 } from 'next/font/google'
import localFont from 'next/font/local'
 
// variable Schriftarten definieren
const inter = Inter()
const lora = Lora()
// 2 Gewichte einer nicht-variablen Schriftart definieren
const sourceCodePro400 = Source_Sans_3({ weight: '400' })
const sourceCodePro700 = Source_Sans_3({ weight: '700' })
// eine lokale Schriftart definieren, wobei GreatVibes-Regular.ttf im styles-Ordner gespeichert ist  
const greatVibes = localFont({ src: './GreatVibes-Regular.ttf' })
 
export { inter, lora, sourceCodePro400, sourceCodePro700, greatVibes }

import { Inter, Lora, Source_Sans_3 } from 'next/font/google'
import localFont from 'next/font/local'
 
// variable Schriftarten definieren
const inter = Inter()
const lora = Lora()
// 2 Gewichte einer nicht-variablen Schriftart definieren
const sourceCodePro400 = Source_Sans_3({ weight: '400' })
const sourceCodePro700 = Source_Sans_3({ weight: '700' })
// eine lokale Schriftart definieren, wobei GreatVibes-Regular.ttf im styles-Ordner gespeichert ist
const greatVibes = localFont({ src: './GreatVibes-Regular.ttf' })
 
export { inter, lora, sourceCodePro400, sourceCodePro700, greatVibes }

Du kannst diese Definitionen nun wie folgt in deinem Code verwenden:

import { inter, lora, sourceCodePro700, greatVibes } from '../styles/fonts'
 
export default function Page() {
  return (
    <div>
      <p className={inter.className}>Hello world using Inter font</p>
      <p style={lora.style}>Hello world using Lora font</p>
      <p className={sourceCodePro700.className}>
        Hello world using Source_Sans_3 font with weight 700
      </p>
      <p className={greatVibes.className}>My title in Great Vibes font</p>
    </div>
  )
}

Um den Zugriff auf die Schriftdefinitionen in deinem Code zu erleichtern, kannst du in deiner tsconfig.json oder jsconfig.json einen Pfad-Alias wie folgt definieren:

{
  "compilerOptions": {
    "paths": {
      "@/fonts": ["./styles/fonts"]
    }
  }
}

Du kannst nun jede Schriftdefinition wie folgt importieren:

import { greatVibes, sourceCodePro400 } from '@/fonts'

Versionsänderungen