字體模組

此 API 參考將幫助您了解如何使用 next/font/google 和 next/font/local。關於功能和用法，請參閱字體最佳化頁面。

字體函式引數

關於用法，請查看Google Fonts 和 本地字體。

srcweightweight，具有以下可能性

• 一個字串，其中包含特定字體可用粗細的可能值，如果是可變字體
  ，則為一個範圍的值
• 如果字體不是可變式 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 選項為 true（預設值）時，透過 subsets 指定的字體將會在 head 中注入一個連結預載標籤。

用於 next/font/google

• 選用

範例

• subsets: ['latin']：一個包含子集 latin 的陣列

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

axes

某些可變字體具有額外的 axes 可以包含。預設情況下，只包含字體粗細以減小檔案大小。axes 的可能值取決於特定字體。

用於 next/font/google

• 選用

範例

• axes: ['slnt']：一個包含 Inter 可變字體的 slnt 值的陣列，如 這裡 所示，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

fallbackadjustFontFallback

• 適用於 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。

用於 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 設定為外部 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'

版本變更