字体

了解如何使用本地文件或 Google Font 包将自定义字体集成到应用中

Android 和 iOS 都有自己的一套平台字体。为了提供一致的用户体验并增强应用的品牌，你可以使用自定义字体。

¥Android and iOS come with their own set of platform fonts. To provide a consistent user experience and enhance your app's branding, you can use custom fonts.

本指南介绍了向项目中添加和加载自定义字体的不同方法，还提供了与字体相关的其他信息。

¥This guide covers different ways you can add and load a custom font into your project and also provides additional information related to fonts.

添加自定义字体

¥Add a custom font

有两种方法可以将自定义字体添加到项目中：

¥There are two ways you can add a custom font into your project:

• 将字体文件添加到你的本地资源中。例如，assets/fonts 目录中的字体文件。

  ¥Add a font file into your local assets. For example, a font file in the assets/fonts directory.

• 安装 Google 字体包。例如，安装 @expo-google-fonts/inter 包。

  ¥Install a Google Font package. For example, installing @expo-google-fonts/inter package.

支持的字体格式

¥Supported font formats

Expo SDK 正式支持 Android、iOS 和 Web 平台上的 OTF 和 TTF 字体格式。如果你的字体是其他字体格式，则必须设置高级配置以在你的项目中支持该格式。

¥Expo SDK officially supports OTF and TTF font formats across Android, iOS and web platforms. If your font is in another font format, you have to set up advanced configuration to support that format in your project.

如何在 OTF 和 TTF 之间进行选择

¥How to choose between OTF and TTF

如果你使用的字体同时具有 OTF 和 TTF 版本，则最好使用 OTF。.otf 文件比 .ttf 文件小。有时，OTF 在某些情况下也会渲染得更好一些。

¥If the font you're using has both OTF and TTF versions, prefer OTF. The .otf files are smaller than .ttf files. Sometimes, OTF also renders slightly better in certain contexts.

使用本地字体文件

¥Use a local font file

将文件复制到项目的 assets/fonts 目录中。

¥Copy the file into your project's assets/fonts directory.

assets/fonts 目录路径是 React Native 应用中放置字体文件的常见约定。如果你遵循自定义约定，你可以将这些文件放在其他地方。

在项目中使用本地字体文件的两种方法：

¥Two ways to use the local font file in your project:

• 使用 expo-font 配置插件 嵌入字体文件。

  ¥Embed the font file with expo-font config plugin.

• 在运行时使用 useFonts 钩子异步加载字体文件。

  ¥Loading the font file with useFonts hook at runtime asynchronously.

使用 expo-font 配置插件

¥With expo-font config plugin

expo-font 配置插件允许在项目的原生代码中嵌入一个或多个字体文件。它支持 Android 和 iOS 的 ttf 和 otf，而 woff 和 woff2 仅在 iOS 上受支持。这是向你的应用添加字体的推荐方法，因为它具有以下优点：

¥The expo-font config plugin allows embedding one or more font files in your project's native code. It supports ttf and otf for both Android and iOS, and woff and woff2 are supported on iOS only. This is the recommended method for adding fonts to your app due to its benefits:

• 当应用在设备上启动时，字体立即可用。

  ¥Fonts are available immediately when the app starts on a device.

• 应用启动时，无需额外代码即可异步加载项目中的字体。

  ¥No additional code required to load fonts in a project asynchronously when the app starts.

• 由于字体已打包在应用中，因此它们在安装应用的所有设备上始终可用。

  ¥Fonts are consistently available across all devices where the app is installed because they're bundled within the app.

但是，这种方法也有一些限制：

¥However, this method also has some limitations:

• 不适用于 Expo Go，因为此方法需要 创建开发构建。

  ¥Doesn't work with Expo Go since this method requires creating a development build.

要在项目中嵌入字体，请按照以下步骤操作：

¥To embed a font in a project, follow the steps below:

How to determine which font family name to use

• If you provide fonts as an array of file paths (as described above), on Android, the file name (without the extension) becomes the font family name. On iOS, the font family name is read from the font file itself. We recommend naming the font file same as its PostScript name so the font family name is consistent on both platforms.

• If you use the object syntax, provide the "Family Name". This can be found in the Font Book app on macOS, fontdrop.info or other programs.

What is PostScript name of a font file?

The PostScript name of a font file is a unique identifier assigned to the font that follows Adobe's PostScript standard. It is used by operating systems and apps to refer to the font. It is not a font's display name.

For example, Inter Black font file's PostScript name is Inter-Black.

Screenshot from Font Book app on macOS.

With useFonts hook

The useFonts hook from expo-font library allows loading the font file asynchronously. This hook keeps track of the loading state and loads the font when an app is initialized.

It works with all Expo SDK versions and with Expo Go. To load a font in a project using useFonts hook, follow the steps below:

Use Google Fonts

Expo has first-class support for all fonts listed in Google Fonts. They are available using @expo-google-fonts library. With any of the font package from this library, you can quickly integrate that font and its variants.

Two ways to use a Google Font in your project:

• Embed the installed font with expo-font config plugin.
• Load the installed font with useFonts hook at runtime asynchronously.

With expo-font config plugin

Note: Embedding a Google Font using expo-font config plugin has same benefits and limitations as embedding a custom font on your own. See using a local font file with expo-font config plugin for more information.

With useFonts hook

Note: Loading a Google Font using useFonts hook has same benefits and limitations as embedding a custom font on your own. See using a local font file with useFonts hook for more information.

Each google Fonts package provides the useFonts hook to load the fonts asynchronously. This hook keeps track of the loading state and loads the font when an app is initialized. The font package also imports the font file so you don't have to explicitly import it.

Additional information

Minimal example

!!!IG19!!!

Beyond OTF and TTF

If your font is in format other than OTF or TTF, you have to customize the Metro bundler configuration to include it as an extra asset for it to work. In some cases, rendering a font format that a platform doesn't support may cause your app to crash.

For reference, the following table provides the list formats that work on each native platform:

Platform built-in fonts

If you don't want to use a custom font by specifying a fontFamily, platform's default font will be used. Each platform has a set of built in fonts. On Android, the default font is Roboto. On iOS, it's SF Pro.

A platform's default font is usually easy-to-read. However, don't be surprised when the system default font is changed to use another font that is not easy to read. In this case, use your custom font so you have precise control over what the user will see.

Handle @expo/vector-icons initial load

When the icons from @expo/vector-icons library load for the first time, they appear as invisible icons in your app. Once they load, they're cached for all the app's subsequent usage. To avoid showing invisible icons on your app's first load, preload during the initial loading screen with useFonts. For example:

!!!IG11!!!

Now, you can use any icon from the Ionicons library in a React component:

!!!IG12!!!

!!!IG20!!!

Loading a remote font directly from the web

If you're loading remote fonts, make sure they are being served from an origin with CORS properly configured. If you don't do this, your remote font might not load properly on the web platform.

Loading fonts from a local asset is the safest way to load a font in your app. When including fonts as local assets, after you submit your app to the app stores, these fonts are bundled with the app download and will be available immediately. You don't have to worry about CORS or other potential issues.

However, loading a font file directly from web is done by replacing the require('./assets/fonts/FontName.otf') with the URL of your font as shown in the example below.