字体模块

此 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 位于 app 目录内的名为 fonts 的目录中
• 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']：用于非可变字体，包含三个可能值的数组。

style

字体style，具有以下几种可能值。

• 一个字符串值，默认值为'normal'。
• 如果字体不是Google 可变字体，则可以使用字体样式值的数组。仅适用于next/font/google。

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

• 可选。

示例

• style: 'italic'：一个字符串 - 对于next/font/google，它可以是normal或italic。
• style: 'oblique'：一个字符串 - 对于next/font/local，它可以取任何值，但预期来自标准字体样式。
• style: ['italic','normal']：对于next/font/google，包含两个值的数组 - 值来自normal和italic。

subsets

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

用于next/font/google。

• 可选。

示例

• subsets: ['latin']：包含子集latin的数组。

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

axes

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

用于next/font/google。

• 可选。

示例

• axes: ['slnt']：包含值slnt的数组，用于Inter可变字体，该字体具有slnt作为附加axes，如此处所示。您可以通过使用Google 可变字体页面上的过滤器并查找除wght之外的其他轴来找到您字体的可能axes值。

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：一个布尔值，设置是否应使用自动后备字体来减少累积布局偏移。默认为true。
• 对于next/font/local：一个字符串或布尔值false，设置是否应使用自动后备字体来减少累积布局偏移。可能的值为'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。

声明

一系列字体面 描述符 键值对，用于进一步定义生成的 @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',
})

要使用字体，请将要设置样式的文本的父容器的 className 设置为字体加载器的 variable 值，并将文本的 className 设置为外部 CSS 文件中的 styles 属性。

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

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

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

在上面的示例中，文本“Hello World”使用 Inter 字体和生成的字体回退进行样式设置，其中 font-weight: 200 和 font-style: italic。

使用字体定义文件

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

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

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

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'

版本变更