使用库

了解如何在项目中使用基于 React Native、Expo SDK 和第三方的库。

每个应用都不可避免地会使用第三方库，因此了解如何确定库是否与你的项目兼容非常重要。

¥Every app is inevitably going to use a third-party library, so it's important to understand how to determine whether a library is compatible with your project.

React Native 核心库

¥React Native core libraries

React Native 提供了一组大多数开发者在其应用中需要的内置原语。其中包括 <ActivityIndicator>、<TextInput>、<Text>、<ScrollView> 和 <View> 等组件。这些列在 React Native 文档的 核心组件和 API 处。你还可以查看 与你的 Expo SDK 版本对应的 React Native 版本。

¥React Native provides a set of built-in primitives that most developers will need in their apps. These include components such as <ActivityIndicator>, <TextInput>, <Text>, <ScrollView>, and <View>. These are listed at Core Components and APIs in React Native documentation. You can also view the React Native version that corresponds to your Expo SDK version.

要在项目中使用 React Native 组件或 API，请从代码中的 react-native 包导入它：

¥To use a React Native component or API in your project, import it from the react-native package in your code:

import { Text, View } from 'react-native';

export default function App() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>Hello, world!</Text>
    </View>
  );
}

Expo SDK 库

¥Expo SDK libraries

Expo SDK 接续了 React Native 核心库的结尾。它提供对许多设备和系统功能的访问，例如音频、条形码扫描、相机、日历、联系人、视频等。它还添加了其他强大的库，如更新、地图、OAuth 身份验证工具等。有关更多信息，请参阅我们如何决定 Expo SDK 包含哪些内容。

¥The Expo SDK picks up where the React Native core libraries end. It provides access to a lot of device and system functionality such as audio, barcode scanning, camera, calendar, contacts, video, and so on. It also adds other powerful libraries like updates, maps, OAuth authentication tools, and more. For more information, see how we decide what goes into the Expo SDK.

要使用 Expo SDK 中的库，请在 API 参考 中找到你要查找的库或使用文档搜索。

¥To use a library from the Expo SDK, find the one you are looking for in the API reference or use the documentation search.

你将在每个 API 参考的顶部看到平台兼容性标签。它告诉你该库与哪些平台和环境兼容。例如，expo-device 库的平台标签如下所示：

¥You will see the platform compatibility tags at the top of each API reference. It tells you which platforms and environments the library is compatible with. For example, the platform tags for the expo-device library look like the following:

在平台兼容性表之后，有一个库的描述和一个包含安装库说明的部分。例如：

¥After the platform compatibility table, there is a library's description and a section with instructions on installing the library. For example:

npx expo install 命令选择与你的项目兼容的库版本，然后使用你的 JavaScript 包管理器（例如 npm）进行安装。

¥The npx expo install command picks a library version compatible with your project and then uses your JavaScript package manager (such as npm) to install it.

接下来，典型的 API 参考包括：

¥Next, a typical API reference includes:

• 如果库需要配置插件，请配置插件使用信息。

  ¥Config plugin usage information if the library requires a config plugin.

• 一个代码示例，展示如何使用库。

  ¥A code example that shows how to use the library.

• API 部分列出了如何导入库，后面是库提供的钩子、属性、类型、方法和类的列表。

  ¥API section that lists how to import the library, followed by a list of hooks, props, types, methods, and classes that the library provides.

注意：如果你使用 TypeScript，你可以在兼容 TypeScript 的代码编辑器（例如 VS Code）中看到 API 部分中包含的信息，并自动补齐。

¥Note: If you use TypeScript, you can see the information included in the API section in your TypeScript-compatible code editor (such as VS Code) with auto-completion.

第三方库

¥Third-party libraries

寻找第三方库

¥Finding a third-party library

React Native 目录 是专门为 React Native 构建的可搜索库数据库。如果你正在寻找的库不是由 React Native 或 Expo SDK 提供的，那么这是在尝试为你的应用查找库时首先查看的最佳位置。

¥React Native Directory is a searchable database of libraries built specifically for React Native. If the library that you are looking for is not provided by React Native or the Expo SDK then this is the best place to look first when trying to find a library for your app.

在 React Native Directory 之后，npm 注册表 是下一个最好的地方。npm 注册表是 JavaScript 库的权威来源，但它列出的库可能并不全部与 React Native 兼容。React Native 是众多 JavaScript 编程环境之一，包括 Node.js、Web 浏览器、Electron 等，而 npm 包含适用于所有这些环境的库。当你创建 开发构建 时，任何与 React Native 兼容的库都与 Expo 项目兼容。但是，它可能与 Expo 应用不兼容。

¥After the React Native Directory, the npm registry is the next best place. The npm registry is the definitive source for JavaScript libraries, but the libraries that it lists may not all be compatible with React Native. React Native is one of many JavaScript programming environments, including Node.js, web browsers, Electron, and more, and npm includes libraries that work for all of these environments. Any library that is compatible with React Native is compatible with the Expo project when you create a development build. However, it may not be compatible with the Expo Go app.

确定第三方库兼容性

¥Determining third-party library compatibility

使用 Expo 开发构建 构建生产质量的应用。它包括你的项目运行所需的所有原生代码。这是在将应用发布到 App Store 或 Google Play 之前测试应用的好方法。你还可以包含需要原生项目（android 和 ios 目录）配置的库。

¥Use Expo development builds for building production-quality apps. It includes all of the native code that your project needs to run. This is a great way to test your app before you publish it to the App Store or Google Play. You can also include libraries that require native projects (android and ios directories) configuration.

Expo Go 应用是开发构建的可选垫脚石。你可以在开发应用时使用它来快速测试应用，但它不包含支持每个库所需的所有原生代码。你可以通过访问 React Native Directory 网站并验证它是否具有 "✔️ Expo" 标签来查找与 Expo Go 兼容的库。你还可以启用 按 Expo Go 过滤。

¥The Expo Go app is an optional stepping stone towards development builds. You can use it to quickly test your app while you are developing it, but it does not include all of the native code required to support every library. You can check React Native Directory to find a library compatible with Expo Go by visiting the website and verifying that it has a "✔️ Expo Go" tag. You can also enable the filter by Expo Go.

要确定新的依赖是否更改原生项目目录，你可以检查以下内容：

¥To determine if a new dependency changes native project directories, you can check the following:

• 该库是否包含 android 或 ios 目录？

  ¥Does the library includes android or ios directories?

• 库的自述文件是否提到链接？

  ¥Does the library's README mention linking?

• 该库是否要求你更改 android/app/src/main/AndroidManifest.xml 或 ios/Podfile 或 ios/Info.plist 来更改项目配置？

  ¥Does the library requires you to change android/app/src/main/AndroidManifest.xml or ios/Podfile or ios/Info.plist to change the project configuration?

• 库有 配置插件 吗？

  ¥Does the library have a config plugin?

如果你对这些问题中的任何一个的回答是肯定的，那么你应该 创建开发版本 在你的项目中使用该库。

¥If you answered yes to any of these questions, then you should create a development build to use the library in your project.

未列入目录？你可以在 GitHub 上找到该项目。执行此操作的一个简单方法是使用 npx npm-home --github <package-name>。例如，要打开 react-native-localize 的 GitHub 页面，请运行：

¥Not listed on the directory? You can find the project on GitHub. A simple way to do this is with npx npm-home --github <package-name>. For example, to open the GitHub page for react-native-localize, run:

如果你需要一些确定库兼容性的帮助，请 在 React Native Directory 存储库上创建问题 并告诉我们。这不仅可以帮助你，还可以帮助其他开发者在将来获得简单的答案！

¥If you want some help determining library compatibility, create an issue on the React Native Directory repository and let us know. This will not just help you, it will also help other developers have an easy answer in the future!

安装第三方库

¥Installing a third-party library

我们建议始终直接使用 npx expo install 而不是 npm install 或 yarn add，因为它允许 Expo CLI 在可能的情况下选择库的兼容版本，并警告你已知的不兼容性。

¥We recommend always using npx expo install instead of npm install or yarn add directly because it allows Expo CLI to pick a compatible version of a library when possible and also warn you about known incompatibilities.

一旦确定该库是否与 React Native 兼容，请使用 Expo CLI 安装该包：

¥Once you have determined if the library is compatible with React Native, use Expo CLI to install the package:

请务必遵循项目网站或自述文件以获取任何其他配置和使用说明。你可以使用以下命令快速访问自述文件：

¥Be sure to follow the project website or README for any additional configuration and usage instructions. You can get to the README quickly using this command:

如果模块需要额外的原生配置，你可以使用 配置插件。有些软件包需要配置插件，但他们还没有，你可以参考 树外配置插件.1 的列表。

¥If the module needs additional native configuration, you can do so using config plugins. Some packages require a config plugin but they don't have one yet, you can refer to the list of out-of-tree config plugins.

如果 Expo 不支持该模块，你可以创建一个 开发构建：

¥If the module is not supported in Expo Go, you can create a development build: