Модуль Font (Шрифты)

Это справочное руководство по API поможет вам понять, как использовать next/font/google и next/font/local. Для получения информации о функциях и использовании см. страницу Оптимизация шрифтов.

Аргументы функции шрифта

Для использования ознакомьтесь с разделами Google Fonts и Локальные шрифты.

src

Путь к файлу шрифта в виде строки или массива объектов (типа Array<{path: string, weight?: string, style?: string}>) относительно директории, где вызывается функция загрузки шрифта.

Используется в next/font/local

• Обязательный

Примеры:

• src:'./fonts/my-font.woff2', где my-font.woff2 находится в директории fonts внутри директории app
• 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',},]
• если функция загрузки шрифта вызывается в app/page.tsx с src:'../styles/fonts/my-font.ttf', то my-font.ttf должен находиться в styles/fonts в корне проекта

weight

Вес шрифта с возможными значениями:

• Строка с возможными значениями весов для конкретного шрифта или диапазон значений, если это переменный шрифт
• Массив значений весов, если шрифт не является переменным шрифтом Google. Применяется только для next/font/google.

Используется в next/font/google и next/font/local

• Обязателен, если используемый шрифт не является переменным

Примеры:

• weight: '400': Строка для одного значения веса - для шрифта Inter возможные значения: '100', '200', '300', '400', '500', '600', '700', '800', '900' или 'variable' (где 'variable' используется по умолчанию)
• weight: '100 900': Строка для диапазона от 100 до 900 для переменного шрифта
• weight: ['100','400','900']: Массив из 3 возможных значений для не переменного шрифта

style

Стиль шрифта с возможными значениями:

• Строка со значением по умолчанию 'normal'
• Массив значений стилей, если шрифт не является переменным шрифтом Google. Применяется только для next/font/google.

Используется в next/font/google и next/font/local

• Опционально

Примеры:

• style: 'italic': Строка - может быть normal или italic для next/font/google
• style: 'oblique': Строка - может принимать любое значение для next/font/local, но ожидается использование стандартных стилей шрифта
• style: ['italic','normal']: Массив из 2 значений для next/font/google - значения могут быть normal и italic

subsets

Подмножества шрифта, определяемые массивом строковых значений с именами каждого подмножества, которое вы хотите предварительно загрузить. Шрифты, указанные в subsets, будут иметь тег предварительной загрузки в заголовке, если опция preload имеет значение true (по умолчанию).

Используется в next/font/google

• Опционально

Примеры:

• subsets: ['latin']: Массив с подмножеством latin

Список всех подмножеств можно найти на странице Google Fonts для вашего шрифта.

axes

Некоторые переменные шрифты имеют дополнительные axes, которые можно включить. По умолчанию включён только вес шрифта для уменьшения размера файла. Возможные значения axes зависят от конкретного шрифта.

Используется в next/font/google

• Опционально

Примеры:

• axes: ['slnt']: Массив со значением slnt для переменного шрифта Inter, который имеет slnt в качестве дополнительного axes, как показано здесь. Возможные значения axes для вашего шрифта можно найти, используя фильтр на странице переменных шрифтов Google и ища оси, отличные от wght

display

Отображение шрифта с возможными строковыми значениями: 'auto', 'block', 'swap', 'fallback' или 'optional' (по умолчанию 'swap').

Используется в next/font/google и next/font/local

• Опционально

Примеры:

• display: 'optional': Строка со значением optional

preload

Логическое значение, определяющее, должен ли шрифт быть предварительно загружен или нет. По умолчанию true.

Используется в next/font/google и next/font/local

• Опционально

Примеры:

• preload: false

fallback

Шрифт для замены, если основной шрифт не может быть загружен. Массив строк с шрифтами для замены без значения по умолчанию.

• Опционально

Используется в next/font/google и next/font/local

Примеры:

• fallback: ['system-ui', 'arial']: Массив, устанавливающий шрифты для замены system-ui или arial

adjustFontFallback

• Для next/font/google: Логическое значение, определяющее, следует ли использовать автоматический шрифт для замены, чтобы уменьшить Совокупный сдвиг макета (CLS). По умолчанию true.
• Для next/font/local: Строка или логическое значение false, определяющее, следует ли использовать автоматический шрифт для замены, чтобы уменьшить Совокупный сдвиг макета (CLS). Возможные значения: 'Arial', 'Times New Roman' или false. По умолчанию 'Arial'.

Используется в next/font/google и next/font/local

• Опционально

Примеры:

• adjustFontFallback: false: для next/font/google
• adjustFontFallback: 'Times New Roman': для next/font/local

variable

Строковое значение для определения имени CSS-переменной, которая будет использоваться, если стиль применяется с помощью метода CSS-переменных.

Используется в next/font/google и next/font/local

• Опционально

Примеры:

• variable: '--my-font': Объявляется CSS-переменная --my-font

declarations

Массив пар ключ-значение дескрипторов @font-face, которые дополнительно определяют сгенерированный @font-face.

Используется в next/font/local

• Опционально

Примеры:

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

Применение стилей

Вы можете применить стили шрифта тремя способами:

• className
• style
• CSS-переменные

className

Возвращает только для чтения CSS className для загруженного шрифта, который можно передать HTML-элементу.

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

style

Возвращает только для чтения CSS style объект для загруженного шрифта, который можно передать HTML-элементу, включая style.fontFamily для доступа к имени семейства шрифтов и шрифтам для замены.

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

CSS-переменные

Если вы хотите установить свои стили во внешней таблице стилей и указать там дополнительные параметры, используйте метод CSS-переменных.

В дополнение к импорту шрифта также импортируйте CSS-файл, где определена CSS-переменная, и установите параметр variable объекта загрузчика шрифта следующим образом:

import { Inter } from 'next/font/google'
import styles from '../styles/component.module.css'

const inter = Inter({
  variable: '--font-inter',
})

import { Inter } from 'next/font/google'
import styles from '../styles/component.module.css'

const inter = Inter({
  variable: '--font-inter',
})

Чтобы использовать шрифт, установите className родительского контейнера текста, который вы хотите стилизовать, в значение variable загрузчика шрифта, а className текста — в свойство styles из внешнего CSS-файла.

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

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

Определите класс селектора text в CSS-файле component.module.css следующим образом:

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

В приведённом выше примере текст Hello World стилизован с использованием шрифта Inter и сгенерированного шрифта для замены с font-weight: 200 и font-style: italic.

Использование файла определений шрифтов

Каждый раз, когда вы вызываете функцию localFont или Google Font, этот шрифт будет размещаться как один экземпляр в вашем приложении. Поэтому, если вам нужно использовать один и тот же шрифт в нескольких местах, вы должны загрузить его в одном месте и импортировать соответствующий объект шрифта там, где он вам нужен. Это делается с помощью файла определений шрифтов.

Например, создайте файл fonts.ts в папке styles в корне вашей директории app.

Затем укажите определения ваших шрифтов следующим образом:

import { Inter, Lora, Source_Sans_3 } from 'next/font/google'
import localFont from 'next/font/local'

// определите ваши переменные шрифты
const inter = Inter()
const lora = Lora()
// определите 2 веса не переменного шрифта
const sourceCodePro400 = Source_Sans_3({ weight: '400' })
const sourceCodePro700 = Source_Sans_3({ weight: '700' })
// определите пользовательский локальный шрифт, где GreatVibes-Regular.ttf хранится в папке styles
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'

// определите ваши переменные шрифты
const inter = Inter()
const lora = Lora()
// определите 2 веса не переменного шрифта
const sourceCodePro400 = Source_Sans_3({ weight: '400' })
const sourceCodePro700 = Source_Sans_3({ weight: '700' })
// определите пользовательский локальный шрифт, где GreatVibes-Regular.ttf хранится в папке styles
const greatVibes = localFont({ src: './GreatVibes-Regular.ttf' })

export { inter, lora, sourceCodePro400, sourceCodePro700, greatVibes }

Теперь вы можете использовать эти определения в своём коде следующим образом:

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>
  )
}

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>
  )
}

Чтобы упростить доступ к определениям шрифтов в вашем коде, вы можете определить псевдоним пути в ваших файлах tsconfig.json или jsconfig.json следующим образом:

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

Теперь вы можете импортировать любое определение шрифта следующим образом:

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

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

Изменения версий