编辑

原生模块设置

需要进行架构审查：本文档旨在支持针对 React Native 的“旧”或“遗留”架构的开发。它可能适用也可能不适用于新架构的开发，需要审查并可能需要更新。有关 React Native Windows 中 React Native 架构的信息，请参阅新旧架构。

有关 Windows 上原生开发的最新信息，请参阅原生平台：概述。

此文档正在不断完善中，并具有版本特异性。请检查本文档的版本（页面顶部）是否与您所针对的 RN/RNW 版本匹配。

本指南将根据我们的建议为您设置一个用于 React Native for Windows 的原生模块。完成此设置后，您应该能够回答这个问题：我需要将原生代码实现在哪里才能在运行时可用？

回答了这个问题后，您应该就可以开始实现您希望向 RNW 应用程序公开的原生模块了。

开发环境

首先，请确保您已安装所有React Native for Windows 开发依赖项。

决定原生模块的托管位置

一旦您的开发环境配置正确，接下来您需要选择原生模块的托管位置。您有三个主要选项：

1. 在您的 React Native for Windows 应用程序项目中创建一个原生模块
2. 向现有原生模块库添加 Windows 支持
3. 创建一个新的原生模块库

选项 1：在您的 React Native for Windows 应用程序项目中创建一个原生模块

将原生功能暴露给您的 React Native for Windows 应用程序的最快途径是在现有应用程序项目中直接创建一个新的原生模块。前提是：

1. 您已按照入门指南操作，其中：
2. 您使用了 React Native Community CLI 的 init 命令来创建一个新的 React Native 项目，并且
3. 您已将 react-native-windows 作为项目的依赖项添加，并且
4. 您使用了 React Native Windows CLI 的 init-windows 命令来初始化项目的原生 Windows 代码。

然后，您应该能够直接在原生 Windows 应用程序项目中实现任何 RNW 原生模块，而无需创建任何单独的项目、库或包。此选项特别适合您的原生需求非常小的情况，例如您只需要向单个 Windows 应用程序公开原生功能，并且不打算与其他应用程序共享或为非 Windows 平台实现该功能。

所以，对于“我需要将原生代码实现在哪里才能在运行时可用？”这个问题的答案是：

您将在原生 Windows 应用程序项目中实现原生代码。也就是说，如果您的应用程序名为 MyApp，您将在项目的 windows\MyApp\ 文件夹中创建和修改文件。

如果您选择了此选项，您可以直接跳到下一步。

注意： RNW 应用程序模板已经包含了一个内置的 IReactPackageProvider，用于在运行时将任何此类原生模块注册到 React Native。您只需实现模块本身的原生 Windows 和 JS/TS 代码。

选项 2：为现有原生模块库添加 Windows 支持

有各种现有的（社区）原生模块库，它们公开了 Android 和 iOS 等其他平台的原生功能。如果该库尚未支持 Windows，您可以尝试自行添加 Windows 支持。如果您已经拥有（或非常乐意使用）现有库，并且您愿意与库所有者合作添加 Windows 支持，则此选项适用。

首先，您需要获取库的源代码。如果该库是开源的（许多都是），您通常可以在其 npmjs.com 列表中找到其源代码存储库的链接。

在您的开发机器上设置好源代码后，您应该可以前往向原生模块库添加 Windows 支持。

注意：有时（社区）库会更换所有者、被放弃和/或不愿意添加和维护 Windows 支持。目前，除了创建和发布您自己的代码分支之外，没有简单的方法来扩展您无法贡献的库。因此，在实施过程深入之前，最好先制定计划并与库所有者进行沟通。

选项 3：创建一个新的原生模块库

如果您想要一个可以被多个应用程序项目重复使用的库，并且现有库不存在（或者您没有修改它的权限），那么最佳选择是创建一个新的库项目来托管原生模块及其功能。

创建新原生模块库项目的基本步骤是：

1. 创建一个新的基本 React Native 库项目
2. 将 react-native-windows 添加为项目的依赖项
3. 使用 React Native Windows CLI 的 init-windows 命令初始化项目的原生 Windows 代码

不幸的是，React Native 和 React Native Community CLI 都没有提供创建新的 React Native 库项目的方法。但是，有许多流行的第三方 CLI 工具可以做到这一点。具体来说，RNW 针对由 create-react-native-library CLI 工具创建的项目测试其支持的库模板。

要开始使用 create-react-native-library 创建名为 my-library 的新库项目，请运行：

npx --yes create-react-native-library@latest my-library

系统将提示您回答有关新库的几个问题。该工具支持各种不同的项目类型，但由于我们的目标是创建一个可以添加 Windows 原生模块的新项目，因此我们推荐以下选项：

1. 类型：您期望公开的原生代码以及您想要支持的应用程序类型将决定您在此处选择的选项。

   1. 如果您要公开非 UI 功能（即新的原生函数），请选择：
      1. Turbo module（即 --template module-new），如果您只希望支持新架构应用程序，或
      2. Turbo module with backward compat（即 --template module-mixed），如果您希望同时支持新旧架构应用程序。
   2. 如果您要公开 UI 功能（即新的原生视图），请选择：
      1. Fabric view (即 --template view-new)，如果您只希望支持新架构应用，或
      2. Fabric view with backward compat (即 --template view-mixed)，如果您希望同时支持新旧架构应用。
   3. 如果您想同时公开 UI 和非 UI 功能，您有两种选择：
      1. 创建两个独立的库，一个用于 UI，一个用于非 UI。
      2. 只需选择一个选项开始，并预计您需要做一些额外的手动工作才能稍后添加另一个。一个库可以轻松地支持 UI 和非 UI，您只是不会有您没有首先选择的选项的示例代码。

2. 语言：此选择仅影响您将用于实现 Android 和 iOS 原生代码的语言。

   注意：如果您选择 C++ for Android & iOS，并打算与 Windows 共享 C++ 代码，您将需要手动操作，将共享 C++ 代码包含并用于 RNW 库的实现。

3. 示例：Vanilla（即 --example vanilla）

注意：如果您选择与上述推荐选项不同的选项，您的体验可能会有所不同。有关 create-react-native-library 提供的所有选项的更多信息，请参阅 create-react-native-library CLI 文档。

创建基本 React Native 库后，导航到您创建的文件夹并运行：

yarn install

现在您应该可以继续向原生模块库添加 Windows 支持。

向原生模块库添加 Windows 支持

一旦您拥有一个基本 React Native 库（无论您是创建的还是找到的），下一步是添加并初始化 React Native for Windows 支持。

将 react-native-windows 添加为依赖项

正确定义您的 NPM 依赖项是创建和维护 React Native 库（尤其是支持多个平台的库）的重要组成部分。此处的说明代表了开始针对 react-native-windows 所需的最低步骤。如果您正在向非您拥有的库添加 Windows 支持，您将需要与库所有者合作，以确保对 package.json 所做的任何更改都是适当的。

有关 NPM 依赖项如何工作的更多信息，请参阅在 package.json 文件中指定 dependencies 和 devDependencies。

对于 React Native for Windows 应用程序项目，您通常会添加对 react-native-windows 版本的直接依赖，该版本与应用程序使用的 react-native 的主要/次要版本相同。但是，大多数库项目都期望能够支持一系列 React Native 版本的目标应用程序——因此，对于库项目，您通常会改为添加 react-native-windows 的开发和对等依赖。

开发依赖指定您希望用于开发库本身的包版本。您通常会希望添加与库作为开发依赖项的 react-native 的主要/次要版本匹配的最新主要/次要版本的 react-native-windows。

因此，例如，如果您检查库的 package.json，看到 devDependency 指定 RN 0.76，您将需要为 RNW 0.76 添加一个开发依赖。您可以使用 yarn 完成此操作：

yarn add react-native-windows@^0.76.0 --dev

对等依赖项指定库所需或支持的包版本。如果您查看库的 package.json，您最可能看到的 react-native 对等依赖项是 *，表示任何版本，但有时您会看到更具体的版本范围。无论是什么，对等依赖项本质上意味着“我需要这个包（和版本范围），但不要替我下载它，我会尝试使用其他人（通常是应用程序）指定的任何版本。”对于 RNW，您很可能希望为 react-native-windows 添加一个与现有 react-native 对等依赖项类似的对等依赖项。

因此，例如，如果您检查库的 package.json，看到 devDependency 指定 RN *，您将需要为 RNW * 添加一个开发依赖。您可以使用 yarn 完成此操作：

yarn add react-native-windows@* --peer

就是这样，您已准备好初始化项目的原生 Windows 代码。

注意：许多原生模块库通常（声称）支持比 RNW 支持的更旧的 RN 版本，因此您可能需要先将库升级到较新版本，才能正确支持 react-native-windows。虽然可以为对等依赖项创建更严格的版本范围（即库可能声称支持 react-native@*，但您选择 react-native-windows@>=0.76.0），但您仍会希望坚持使用相同的开发依赖项主要/次要版本配对，以避免意外行为。

为库项目初始化原生 Windows 代码

此时，您应该已准备好使用 init-windows 命令添加 Windows 支持。该过程与向应用程序项目添加 Windows 支持类似，但您需要指定一个库模板：

npx @react-native-community/cli init-windows --template cpp-lib --overwrite

这会添加 C++/WinRT 库项目的原生代码。

所以，对于“我需要将原生代码实现在哪里才能在运行时可用？”这个问题的答案是：

您将在原生 Windows 库项目中实现原生代码。也就是说，如果您的库名为 MyLib，您将在项目的 windows\MyLib\ 文件夹中创建和修改文件。

就是这样，您可以继续下一步了。

注意：有两个较旧的库模板，old/uwp-cpp-lib 用于创建 C++/WinRT UWP 项目，old/uwp-cs-lib 用于 C# UWP 项目。这两个模板都计划最终弃用，不建议用于初始化新项目。它们只应由具有特定遗留要求的开发人员使用。

后续步骤

您现在已经创建了构建原生模块或视图管理器的脚手架。现在是时候向模块添加业务逻辑了——请按照 原生模块 和 视图管理器 文档中描述的步骤进行操作。

其他任务

以下是您在编写原生模块时希望执行的一些其他常见任务。

构建用于测试的示例应用程序

如果您直接在 React Native for Windows 应用程序中实现您的原生模块，那么您的应用程序就在那里准备好进行测试。或者，如果您在单独的库中实现您的原生模块，它可能已经包含一个用于测试其他 React Native 平台的示例应用程序。

如果此类应用程序已经存在，您只需按照入门指南中的步骤，像其他 RN 应用程序一样为其添加 Windows 支持。

注意：如果您（或库作者）使用 create-react-native-library 创建库，那么通常在项目的 example 文件夹中已经有一个示例应用程序。当您运行 init-windows --template cpp-lib 来初始化库的 Windows 支持时，RNW CLI 将检测到该 example 文件夹，并自动尝试使用 init-windows --template cpp-app 为您设置和初始化 Windows 支持。

让您的模块准备好在应用程序中消费

如果您已按照上述步骤操作，那么由于自动链接，您的模块应该已经可以供其他应用程序使用了。

在模块发布前进行测试

为您的模块添加测试

我们使用 WebdriverIO + WinAppDriver 进行 UI 测试。更多详细信息请参阅此处。有关实际示例，请查看react-native-webview 或 progress-view。

为您的模块设置 CI（持续集成）管道

模块开发完成后，最好设置一个具有自动化构建和测试的 CI 管道，以避免将来的回归。有关更多信息，请参阅为 RNW 应用程序设置持续集成管道。

记录您的模块

模块完成后，请更新 react-native-community/directory，以便其关于您的原生模块的信息是最新的。如果您正在构建一个将由 Microsoft 维护的原生模块，请在 react-native-windows-samples 中更新支持的社区模块文档，并提供您的原生模块信息。