This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Expo 字体 iconExpo 字体

一个允许在运行时加载字体并在 React Native 组件中使用它们的库。

Android
iOS
tvOS
Web
Included in Expo Go
Recommended version:
~58.0.7

expo-font 允许从网络加载字体并在 React Native 组件中使用它们。有关更详细的使用信息,请参阅 Fonts 指南。

安装

🌐 Installation

Terminal
- npx expo install expo-font
- yarn expo install expo-font
- pnpm expo install expo-font
- bun expo install expo-font

If you are installing this in an existing React Native app, make sure to install expo in your project.

应用配置中的配置

🌐 Configuration in app config

有两种方法可以向你的应用添加字体:使用 expo-font 配置插件(推荐用于 Android 和 iOS)或在运行时加载字体(适用于包括网页在内的所有平台)。

🌐 There are two ways to add fonts to your app: using the expo-font config plugin (recommended for Android and iOS) or loading them at runtime (which works across all platforms including web).

在 Android 和 iOS 上,该插件允许你在构建时嵌入字体文件,这比 useFonts 或 loadAsync 更高效。设置好配置插件并运行 prebuild 后,你可以立即渲染自定义字体。该插件可以通过不同方式进行配置,具体用法请参阅 Fonts 指南。

🌐 On Android and iOS, the plugin allows you to embed font files at build time which is more efficient than useFonts or loadAsync. After you set up the config plugin and run prebuild, you can render custom fonts right away. The plugin can be configured in different ways, see the Fonts guide on how to use it.

Example app.json with config plugin

app.json
{ "expo": { "plugins": [ [ "expo-font", { "fonts": ["./path/to/file.ttf"], "android": { "fonts": [ { "fontFamily": "Source Serif 4", "fontDefinitions": [ { "path": "./path/to/SourceSerif4-ExtraBold.ttf", "weight": 800 } ] }, { "fontFamily": "Roboto Flex", "path": "./path/to/RobotoFlex.ttf", "fontDefinitions": [ { "weight": 400 }, { "weight": 700 }, { "weight": 400, "style": "italic", "axes": { "slnt": -10 } } ] } ] }, "ios": { "fonts": ["./path/to/SourceSerif4-ExtraBold.ttf"] } } ] ] } }

Configurable properties

NameDefaultDescription
fonts[]

An array of font definitions to link to the native project. The paths should be relative to the project root. On Android, the file name becomes the font family name. On iOS, the font family name is always taken directly from the font file and may not be the same as the file name — follow the naming advice or use getLoadedFonts to see what fonts are available.

android{}

An object with a fonts array of font definitions to link to the native project on Android. Use the object syntax within fonts to embed xml fonts with custom family name.

ios{}

An object with a fonts array of font file paths to link to the native project on iOS. The font family name is taken directly from the font file.

Are you using this library in an existing React Native app?

用法

🌐 Usage

如果你不想使用 config 插件,你可以在运行时通过 useFonts 钩子加载字体,如下面的代码片段所示:

🌐 If you don't want to use the config plugin, you can load a font at runtime with the useFonts hook, as shown in the snippet:

Example of loading and using a custom font
import { useFonts } from 'expo-font'; import * as SplashScreen from 'expo-splash-screen'; import { useEffect } from 'react'; import { Text, View, StyleSheet } from 'react-native'; SplashScreen.preventAutoHideAsync(); export default function App() { // Use `useFonts` only if you can't use the config plugin. const [loaded, error] = useFonts({ 'Inter-Black': require('./assets/fonts/Inter-Black.otf'), }); useEffect(() => { if (loaded || error) { SplashScreen.hideAsync(); } }, [loaded, error]); if (!loaded && !error) { return null; } return ( <View style={styles.container}> <Text style={{ fontFamily: 'Inter-Black', fontSize: 30 }}>Inter Black</Text> <Text style={{ fontSize: 30 }}>Platform Default</Text> </View> ); } const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', alignItems: 'center', }, });

可变字体

🌐 Variable fonts

上面示例中的 Roboto Flex 条目是一个可变字体:一个文件包含多种字重。你可以使用 fontWeight 和 fontStyle 样式属性选择字重。可变字体也可以与 useFonts 一起使用。想了解更多,请参见字体指南中的 可变字体。

🌐 The Roboto Flex entry in the example above is a variable font: one file that holds many faces. You select a face with the fontWeight and fontStyle style props. Variable fonts also work with useFonts. To learn more, see Variable fonts in the Fonts guide.

多种粗细和样式

🌐 Multiple weights and styles

一个字体家族也可以包含多个静态字体文件,例如常规、加粗和斜体。要在同一个 fontFamily 名称下加载它们,可以向 useFonts 或 loadAsync 传递一个 FontFamilyDefinition 数组,而不是一个映射。然后使用 fontWeight 和 fontStyle 样式属性选择字体样式。想了解更多,看看字体指南中的 为一个字体家族加载多种字重和样式。

🌐 A font family can also hold several static font files, for example regular, bold, and italic cuts. To load them under a single fontFamily name, pass useFonts or loadAsync an array of FontFamilyDefinitions instead of a map. Then select a face with the fontWeight and fontStyle style props. To learn more, see Loading multiple weights and styles for one font family in the Fonts guide.

应用接口

🌐 API

import * as Font from 'expo-font';

No API data file found, sorry!

错误代码

🌐 Error codes

代码描述
ERR_FONT_API传递给 loadAsync 的参数无效。
ERR_FONT_SOURCE提供的资源类型不正确。
ERR_WEB_ENVIRONMENT浏览器的 document 元素不支持注入字体。
ERR_DOWNLOAD下载提供的资源失败。
ERR_FONT_FAMILY提供的字体家族名称无效。
ERR_UNLOAD尝试卸载尚未完成加载的字体。