字体模块

此 API 参考将帮助你了解如何使用 next/font/google 和 next/font/local。功能及使用方法请参见优化字体页。

¥This API reference will help you understand how to use next/font/google and next/font/local. For features and usage, please see the Optimizing Fonts page.

字体函数参数

¥Font Function Arguments

如需使用，请查看谷歌字体和本地字体。

¥For usage, review Google Fonts and Local Fonts.

键	类型	必需的
`src`	字符串或对象数组	是的
`weight`	字符串或数组	必需/可选
`style`	字符串或数组	*
`subsets`	字符串数组	*
`axes`	字符串数组	*
`display`	字符串	*
`preload`	布尔值	*
`fallback`	字符串数组	*
`adjustFontFallback`	布尔值或字符串	*
`variable`	字符串	*
`declarations`	对象数组	*

`src`

字体文件的路径，作为字符串或对象数组（类型为 Array<{path: string, weight?: string, style?: string}>），相对于调用字体加载器函数的目录。

¥The path of the font file as a string or an array of objects (with type Array<{path: string, weight?: string, style?: string}>) relative to the directory where the font loader function is called.

用于 next/font/local

¥Used in next/font/local

必需的

¥Required

示例：

¥Examples:

src:'./fonts/my-font.woff2'，其中 my-font.woff2 放置在 app 目录内名为 fonts 的目录中

¥src:'./fonts/my-font.woff2' where my-font.woff2 is placed in a directory named fonts inside the app directory
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',},]
如果使用 src:'../styles/fonts/my-font.ttf' 在 app/page.tsx 中调用字体加载器函数，则 my-font.ttf 被放置在项目根目录下的 styles/fonts 中

¥if the font loader function is called in app/page.tsx using src:'../styles/fonts/my-font.ttf', then my-font.ttf is placed in styles/fonts at the root of the project

`weight`

字体 weight 具有以下可能性：

¥The font weight with the following possibilities:

一个字符串，其中包含特定字体可用的权重值或一系列值（如果是 variable 字体）

¥A string with possible values of the weights available for the specific font or a range of values if it's a variable font
如果字体不是可变谷歌字体，则为权重值数组。仅适用于 next/font/google。

¥An array of weight values if the font is not a variable google font. It applies to next/font/google only.

用于 next/font/google 和 next/font/local

¥Used in next/font/google and next/font/local

如果使用的字体不是 variable，则为必填项

¥Required if the font being used is not variable

示例：

¥Examples:

weight: '400'：单个权重值的字符串 - 对于字体 Inter，可能的值为 '100'、'200'、'300'、'400'、'500'、'600'、'700'、'800'、'900' 或 'variable'，其中 'variable' 是默认值）

¥weight: '400': A string for a single weight value - for the font Inter, the possible values are '100', '200', '300', '400', '500', '600', '700', '800', '900' or 'variable' where 'variable' is the default)
weight: '100 900'：可变字体的 100 和 900 范围之间的字符串

¥weight: '100 900': A string for the range between 100 and 900 for a variable font
weight: ['100','400','900']：非可变字体的 3 个可能值的数组

¥weight: ['100','400','900']: An array of 3 possible values for a non variable font

`style`

字体 style 具有以下可能性：

¥The font style with the following possibilities:

字符串 value，默认值为 'normal'

¥A string value with default value of 'normal'
如果字体不是可变谷歌字体，则为样式值数组。仅适用于 next/font/google。

¥An array of style values if the font is not a variable google font. It applies to next/font/google only.

用于 next/font/google 和 next/font/local

¥Used in next/font/google and next/font/local

可选的

¥Optional

示例：

¥Examples:

style: 'italic'：一个字符串 - next/font/google 可以是 normal 或 italic

¥style: 'italic': A string - it can be normal or italic for next/font/google
style: 'oblique'：一个字符串 - 它可以为 next/font/local 取任何值，但预计来自标准字体样式

¥style: 'oblique': A string - it can take any value for next/font/local but is expected to come from standard font styles
style: ['italic','normal']：next/font/google 的 2 个值的数组 - 值来自 normal 和 italic

¥style: ['italic','normal']: An array of 2 values for next/font/google - the values are from normal and italic

`subsets`

字体 subsets 由字符串值数组定义，其中包含你希望成为 preloaded 的每个子集的名称。当 preload 选项为 true（默认值）时，通过 subsets 指定的字体将在头部注入一个链接预加载标记。

¥The font subsets defined by an array of string values with the names of each subset you would like to be preloaded. Fonts specified via subsets will have a link preload tag injected into the head when the preload option is true, which is the default.

用于 next/font/google

¥Used in next/font/google

可选的

¥Optional

示例：

¥Examples:

subsets: ['latin']：具有子集 latin 的数组

¥subsets: ['latin']: An array with the subset latin

你可以在 Google Fonts 页面上找到你的字体的所有子集的列表。

¥You can find a list of all subsets on the Google Fonts page for your font.

`axes`

某些可变字体具有可以包含的额外 axes。默认情况下，仅包含字体粗细以减小文件大小。axes 的可能值取决于特定字体。

¥Some variable fonts have extra axes that can be included. By default, only the font weight is included to keep the file size down. The possible values of axes depend on the specific font.

用于 next/font/google

¥Used in next/font/google

可选的

¥Optional

示例：

¥Examples:

axes: ['slnt']：Inter 可变字体的值为 slnt 的数组，其中 slnt 作为附加 axes，如此处所示。你可以通过使用 Google 可变字体页面上的过滤器并查找 wght 以外的轴来找到字体可能的 axes 值

¥axes: ['slnt']: An array with value slnt for the Inter variable font which has slnt as additional axes as shown here. You can find the possible axes values for your font by using the filter on the Google variable fonts page and looking for axes other than wght

`display`

字体 display 可能带有 'auto'、'block'、'swap'、'fallback' 或 'optional' 的字符串 values，默认值为 'swap'。

¥The font display with possible string values of 'auto', 'block', 'swap', 'fallback' or 'optional' with default value of 'swap'.

用于 next/font/google 和 next/font/local

¥Used in next/font/google and next/font/local

可选的

¥Optional

示例：

¥Examples:

display: 'optional'：分配给 optional 值的字符串

¥display: 'optional': A string assigned to the optional value

`preload`

一个布尔值，指定字体是否应为 preloaded。默认为 true。

¥A boolean value that specifies whether the font should be preloaded or not. The default is true.

用于 next/font/google 和 next/font/local

¥Used in next/font/google and next/font/local

可选的

¥Optional

示例：

¥Examples:

preload: false

`fallback`

无法加载字体时使用的后备字体。没有默认值的后备字体字符串数组。

¥The fallback font to use if the font cannot be loaded. An array of strings of fallback fonts with no default.

可选的

¥Optional

用于 next/font/google 和 next/font/local

¥Used in next/font/google and next/font/local

示例：

¥Examples:

fallback: ['system-ui', 'arial']：将后备字体设置为 system-ui 或 arial 的数组

¥fallback: ['system-ui', 'arial']: An array setting the fallback fonts to system-ui or arial

`adjustFontFallback`

对于 next/font/google：一个布尔值，设置是否应使用自动后备字体来减少累积布局偏移。默认为 true。

¥For next/font/google: A boolean value that sets whether an automatic fallback font should be used to reduce Cumulative Layout Shift. The default is true.
对于 next/font/local：字符串或布尔值 false 值，用于设置是否应使用自动后备字体来减少累积布局偏移。可能的值为 'Arial'、'Times New Roman' 或 false。默认为 'Arial'。

¥For next/font/local: A string or boolean false value that sets whether an automatic fallback font should be used to reduce Cumulative Layout Shift. The possible values are 'Arial', 'Times New Roman' or false. The default is 'Arial'.

用于 next/font/google 和 next/font/local

¥Used in next/font/google and next/font/local

可选的

¥Optional

示例：

¥Examples:

adjustFontFallback: false：对于 next/font/google

¥adjustFontFallback: false: for next/font/google
adjustFontFallback: 'Times New Roman'：对于 next/font/local

¥adjustFontFallback: 'Times New Roman': for next/font/local

`variable`

一个字符串值，用于定义样式与 CSS 变量方法.css 一起应用时要使用的 CSS 变量名称。

¥A string value to define the CSS variable name to be used if the style is applied with the CSS variable method.

用于 next/font/google 和 next/font/local

¥Used in next/font/google and next/font/local

可选的

¥Optional

示例：

¥Examples:

variable: '--my-font'：CSS 变量 --my-font 被声明

¥variable: '--my-font': The CSS variable --my-font is declared

`declarations`

字体 descriptor 键值对数组，进一步定义生成的 @font-face。

¥An array of font face descriptor key-value pairs that define the generated @font-face further.

用于 next/font/local

¥Used in next/font/local

可选的

¥Optional

示例：

¥Examples:

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

应用样式

¥Applying Styles

你可以通过三种方式应用字体样式：

¥You can apply the font styles in three ways:

`className`

返回一个只读 CSS className，用于将加载的字体传递给 HTML 元素。

¥Returns a read-only CSS className for the loaded font to be passed to an HTML element.

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

`style`

返回一个只读 CSS style 对象，用于将加载的字体传递给 HTML 元素，包括 style.fontFamily 以访问字体系列名称和后备字体。

¥Returns a read-only CSS style object for the loaded font to be passed to an HTML element, including style.fontFamily to access the font family name and fallback fonts.

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

CSS 变量

¥CSS Variables

如果你想在外部样式表中设置样式并在其中指定其他选项，请使用 CSS 变量方法。

¥If you would like to set your styles in an external style sheet and specify additional options there, use the CSS variable method.

除了导入字体之外，还要导入定义 CSS 变量的 CSS 文件，并设置字体加载器对象的变量选项，如下所示：

¥In addition to importing the font, also import the CSS file where the CSS variable is defined and set the variable option of the font loader object as follows:

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 设置为外部 CSS 文件中的 styles 属性。

¥To use the font, set the className of the parent container of the text you would like to style to the font loader's variable value and the className of the text to the styles property from the external CSS file.

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

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

在 component.module.css CSS 文件中定义 text 选择器类，如下所示：

¥Define the text selector class in the component.module.css CSS file as follows:

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

在上面的示例中，文本 Hello World 使用 Inter 字体设置样式，并使用 font-weight: 200 和 font-style: italic 生成后备字体。

¥In the example above, the text Hello World is styled using the Inter font and the generated font fallback with font-weight: 200 and font-style: italic.

使用字体定义文件

¥Using a font definitions file

每次调用 localFont 或 Google 字体函数时，该字体都会作为一个实例托管在你的应用中。因此，如果需要在多个地方使用相同的字体，应该在一处加载，并在需要的地方导入相关的字体对象。这是使用字体定义文件完成的。

¥Every time you call the localFont or Google font function, that font will be hosted as one instance in your application. Therefore, if you need to use the same font in multiple places, you should load it in one place and import the related font object where you need it. This is done using a font definitions file.

例如，在应用目录根目录的 styles 文件夹中创建 fonts.ts 文件。

¥For example, create a fonts.ts file in a styles folder at the root of your app directory.

然后，指定字体定义，如下所示：

¥Then, specify your font definitions as follows:

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

你现在可以在代码中使用这些定义，如下所示：

¥You can now use these definitions in your code as follows:

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 文件中定义路径别名，如下所示：

¥To make it easier to access the font definitions in your code, you can define a path alias in your tsconfig.json or jsconfig.json files as follows:

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

你现在可以导入任何字体定义，如下所示：

¥You can now import any font definition as follows:

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

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

版本变更

¥Version Changes

版本	变化
`v13.2.0`	`@next/font` 更名为 `next/font`。不再需要安装。
`v13.0.0`	添加了 `@next/font`。

字体函数参数​

src​

weight​

style​

subsets​

axes​

display​

preload​

fallback​

adjustFontFallback​

variable​

declarations​

应用样式​

className​

style​

CSS 变量​

使用字体定义文件​

版本变更​

字体函数参数

`src`

`weight`

`style`

`subsets`

`axes`

`display`

`preload`

`fallback`

`adjustFontFallback`

`variable`

`declarations`

应用样式

`className`

`style`

CSS 变量

使用字体定义文件

版本变更