字型模組

next/font 自動最佳化您的字型（包括自定義字型），並移除外部網路請求，以提高隱私和效能。

它包括任何字型檔案的**內建自動自託管**。這意味著您可以以最優方式載入網頁字型，且不會發生 佈局偏移。

您還可以方便地使用所有 Google 字型。CSS 和字型檔案在構建時下載，並與您的其他靜態資源一起自託管。**瀏覽器不會向 Google 傳送任何請求。**

要在所有頁面中使用字型，請將其新增到 /pages 下的 _app.js 檔案，如下所示

import { Inter } from 'next/font/google'
 
// If loading a variable font, you don't need to specify the font weight
const inter = Inter({ subsets: ['latin'] })
 
export default function MyApp({ Component, pageProps }) {
  return (
    <main className={inter.className}>
      <Component {...pageProps} />
    </main>
  )
}

🎥 觀看： 瞭解有關使用 next/font 的更多資訊 → YouTube (6 分鐘)。

參考

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']：非可變字型的 3 個可能值的陣列

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 選項為 true（預設值）時，透過 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：一個布林值，用於設定是否應使用自動回退字型以減少 累計佈局偏移 (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

一個字型 face 描述符 鍵值對陣列，用於進一步定義生成的 @font-face。

在 next/font/local 中使用

• 可選

示例

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

示例

Google Fonts

要使用 Google 字型，請將其作為函式從 next/font/google 匯入。我們建議使用 可變字型 以獲得最佳效能和靈活性。

要在所有頁面中使用字型，請將其新增到 /pages 下的 _app.js 檔案，如下所示

import { Inter } from 'next/font/google'
 
// If loading a variable font, you don't need to specify the font weight
const inter = Inter({ subsets: ['latin'] })
 
export default function MyApp({ Component, pageProps }) {
  return (
    <main className={inter.className}>
      <Component {...pageProps} />
    </main>
  )
}

如果您無法使用可變字型，則**需要指定字重**。

import { Roboto } from 'next/font/google'
 
const roboto = Roboto({
  weight: '400',
  subsets: ['latin'],
})
 
export default function MyApp({ Component, pageProps }) {
  return (
    <main className={roboto.className}>
      <Component {...pageProps} />
    </main>
  )
}

您可以使用陣列指定多個字重和/或樣式

const roboto = Roboto({
  weight: ['400', '700'],
  style: ['normal', 'italic'],
  subsets: ['latin'],
  display: 'swap',
})

溫馨提示：對於包含多個單詞的字型名稱，請使用下劃線（_）。例如，Roboto Mono 應匯入為 Roboto_Mono。

在 <head> 中應用字型

您也可以不使用包裝器和 className，而透過將其注入 <head> 中來使用字型，如下所示

import { Inter } from 'next/font/google'
 
const inter = Inter({ subsets: ['latin'] })
 
export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <style jsx global>{`
        html {
          font-family: ${inter.style.fontFamily};
        }
      `}</style>
      <Component {...pageProps} />
    </>
  )
}

單頁使用

要在單個頁面上使用字型，請將其新增到特定頁面，如下所示

import { Inter } from 'next/font/google'
 
const inter = Inter({ subsets: ['latin'] })
 
export default function Home() {
  return (
    <div className={inter.className}>
      <p>Hello World</p>
    </div>
  )
}

指定子集

Google 字型會自動 子集化。這會減小字型檔案的大小並提高效能。您需要定義要預載入的子集。如果在 preload 為 true 的情況下未能指定任何子集，將導致警告。

這可以透過新增到函式呼叫中來實現

const inter = Inter({ subsets: ['latin'] })

有關更多資訊，請參閱 字型 API 參考。

使用多個字型

您可以在應用程式中匯入和使用多個字型。有兩種方法可以採用。

第一種方法是建立一個實用函式，該函式匯出字型，然後匯入並在需要的地方應用其 className。這確保字型僅在渲染時預載入。

import { Inter, Roboto_Mono } from 'next/font/google'
 
export const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
})
 
export const roboto_mono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap',
})

在上面的示例中，Inter 將全域性應用，而 Roboto Mono 可以根據需要匯入和應用。

或者，您可以建立 CSS 變數 並與您首選的 CSS 解決方案一起使用

html {
  font-family: var(--font-inter);
}
 
h1 {
  font-family: var(--font-roboto-mono);
}

在上面的例子中，Inter 將全域性應用，而任何 <h1> 標籤將使用 Roboto Mono 樣式化。

建議：請謹慎使用多種字型，因為每種新字型都是客戶端必須下載的額外資源。

本地字型

匯入 next/font/local 並指定本地字型檔案的 src。我們建議使用 可變字型 以獲得最佳效能和靈活性。

import localFont from 'next/font/local'
 
// Font files can be colocated inside of `pages`
const myFont = localFont({ src: './my-font.woff2' })
 
export default function MyApp({ Component, pageProps }) {
  return (
    <main className={myFont.className}>
      <Component {...pageProps} />
    </main>
  )
}

如果要為一個字體系列使用多個檔案，src 可以是一個數組

const roboto = localFont({
  src: [
    {
      path: './Roboto-Regular.woff2',
      weight: '400',
      style: 'normal',
    },
    {
      path: './Roboto-Italic.woff2',
      weight: '400',
      style: 'italic',
    },
    {
      path: './Roboto-Bold.woff2',
      weight: '700',
      style: 'normal',
    },
    {
      path: './Roboto-BoldItalic.woff2',
      weight: '700',
      style: 'italic',
    },
  ],
})

有關更多資訊，請參閱 字型 API 參考。

使用 Tailwind CSS

next/font 與 Tailwind CSS 使用 CSS 變數 無縫整合。

在下面的示例中，我們使用了 next/font/google 中的 Inter 和 Roboto_Mono 字型（您可以使用任何 Google 字型或本地字型）。使用 variable 選項分別為這些字型定義 CSS 變數名稱，例如 inter 和 roboto_mono。然後，應用 inter.variable 和 roboto_mono.variable 將 CSS 變數包含在您的 HTML 文件中。

溫馨提示：您可以根據您的偏好、樣式需求或專案要求，將這些變數新增到 <html> 或 <body> 標籤中。

import { Inter } from 'next/font/google'
 
const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
})
 
const roboto_mono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-roboto-mono',
})
 
export default function MyApp({ Component, pageProps }) {
  return (
    <main className={`${inter.variable} ${roboto_mono.variable} font-sans`}>
      <Component {...pageProps} />
    </main>
  )
}

最後，將 CSS 變數新增到您的 Tailwind CSS 配置中

@import 'tailwindcss';
 
@theme inline {
  --font-sans: var(--font-inter);
  --font-mono: var(--font-roboto-mono);
}

Tailwind CSS v3

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
    './app/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {
      fontFamily: {
        sans: ['var(--font-inter)'],
        mono: ['var(--font-roboto-mono)'],
      },
    },
  },
  plugins: [],
}

您現在可以使用 font-sans 和 font-mono 實用類來將字型應用到您的元素。

<p class="font-sans ...">The quick brown fox ...</p>
<p class="font-mono ...">The quick brown fox ...</p>

應用樣式

您可以透過三種方式應用字型樣式

• 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 設定為外部 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 字型函式時，該字型都將作為應用程式中的一個例項託管。因此，如果您需要在多個地方使用相同的字型，您應該在一個地方載入它，並在需要的地方匯入相關的字型物件。這可以透過使用字型定義檔案來完成。

例如，在您的 app 目錄的根目錄下的 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'

預載入

當在您網站的頁面上呼叫字型函式時，它不會全域性可用，也不會在所有路由上預載入。相反，字型僅根據其使用的檔案型別在相關路由上預載入

• 如果它是一個獨特頁面，則在該頁面的獨特路由上預載入
• 如果它在自定義應用中，則在 /pages 下的所有網站路由上預載入。

版本變更