Модуль шрифтов

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

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

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

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

Вес шрифта 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

Начертание шрифта 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, определяемый массивом строковых значений с именами каждого набора, который вы хотите загрузить предварительно. Шрифты, указанные через 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

Свойство шрифта 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: Булево значение, определяющее, нужно ли использовать автоматический запасной шрифт для уменьшения Cumulative Layout Shift. По умолчанию true.
• Для next/font/local: Строковое или булево значение false , определяющее, нужно ли использовать автоматический запасной шрифт для уменьшения Cumulative Layout Shift. Возможные значения '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

Массив пар ключ-значение описателей шрифтов descriptor , определяющих сгенерированные @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, и установите опцию переменной объекта загрузчика шрифтов следующим образом:

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>

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

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

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

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

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

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

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

import { Inter, Lora, Source_Sans_3 } from 'next/font/google'
import localFont from 'next/font/local'
 
// define your variable fonts
const inter = Inter()
const lora = Lora()
// define 2 weights of a non-variable font
const sourceCodePro400 = Source_Sans_3({ weight: '400' })
const sourceCodePro700 = Source_Sans_3({ weight: '700' })
// define a custom local font where GreatVibes-Regular.ttf is stored in the styles folder
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>
  )
}

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

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

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

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

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