编辑

原生平台：使用原生库

本指南介绍如何在 React Native for Windows 应用程序中使用原生库中的原生模块（和/或组件）。有关原生开发的更高级概述，请在阅读本指南之前参阅原生平台：概述。

注意：以下说明是通用性的，应适用于大多数原生库，但特定库可能有自己的说明和/或额外的安装步骤。

高级概述

要在 React Native for Windows 应用程序中使用原生库，您需要：

1. 将原生库包添加为应用程序的 Node.js 依赖项
2. 使用 React Native for Windows 的原生模块自动链接功能将库的 Windows 项目连接到应用程序的 Windows 项目
3. 从应用程序的 JavaScript 代码中调用原生库的 API 接口

分步指南

0. 设置

您需要一个已初始化并实现 Windows 支持的 React Native 库项目。

注意：本指南的其余部分假设您至少已遵循原生平台：原生模块指南创建并实现了一个名为 testlib 的新库项目，并且您将通过其 example 文件夹中提供的应用程序使用它。

1. 将原生库包添加为应用程序的 Node.js 依赖项

您需要做的第一件事是，如果原生库的 Node.js 包尚未是您的 React Native 应用程序的依赖项，请将其添加为依赖项。

yarn add testlib

注意：虽然这是将库包添加为应用程序依赖项的标准方式（特别是如果您将库发布到 NPM feed 并从中获取），但这不是所提供的 example 应用程序使用库的方式。 example 应用程序而是使用其 react-native.config.js 配置的 dependencies 对象中的自定义条目。

2. 使用 React Native for Windows 的原生模块自动链接功能

现在，在我们成功地在 React Native for Windows 应用程序中消费原生库之前，我们需要运行 React Native for Windows 的自动链接，即autolink-windows 命令，至少一次，以正确连接库的原生 Windows 项目到我们应用程序的原生 Windows 项目。

yarn react-native autolink-windows

注意：对于我们的 example 应用程序，您可以从 example 文件夹内运行给定命令，或者直接从库的根文件夹运行 yarn example react-native autolink-windows。

该命令将（重新）在应用程序的 windows 文件夹下生成几个原生文件（对于 example 应用程序，在 example\windows\testLibExample 下），包括：

AutolinkedNativeModules.g.targets

AutolinkedNativeModules.g.cpp

AutolinkedNativeModules.g.props

AutolinkedNativeModules.g.h

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- AutolinkedNativeModules.g.targets contents generated by "npx @react-native-community/cli autolink-windows" -->
  <ItemGroup>
    <!-- Projects from testlib -->
    <ProjectReference Include="$(ProjectDir)..\..\..\windows\testlib\testlib.vcxproj">
      <Project>{4AA0750A-2B4A-4DE1-BD39-B65A83AADE6B}</Project>
    </ProjectReference>
  </ItemGroup>
</Project>

// AutolinkedNativeModules.g.cpp contents generated by "npx @react-native-community/cli autolink-windows"
// clang-format off
#include "pch.h"
#include "AutolinkedNativeModules.g.h"

// Includes from testlib
#include <winrt/testlib.h>

namespace winrt::Microsoft::ReactNative
{

void RegisterAutolinkedNativeModulePackages(winrt::Windows::Foundation::Collections::IVector<winrt::Microsoft::ReactNative::IReactPackageProvider> const& packageProviders)
{ 
    // IReactPackageProviders from testlib
    packageProviders.Append(winrt::testlib::ReactPackageProvider());
}

}

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- AutolinkedNativeModules.g.props contents generated by "npx @react-native-community/cli autolink-windows" -->
  <PropertyGroup>
  </PropertyGroup>
</Project>

// AutolinkedNativeModules.g.h contents generated by "npx @react-native-community/cli autolink-windows"
// clang-format off
#pragma once

namespace winrt::Microsoft::ReactNative
{

void RegisterAutolinkedNativeModulePackages(winrt::Windows::Foundation::Collections::IVector<winrt::Microsoft::ReactNative::IReactPackageProvider> const& packageProviders);

}

注意：生成的文件包含连接所有原生库到 React Native for Windows 应用程序的必要设置。

AutolinkedNativeModules.g.targets（和 AutolinkedNativeModules.g.props）文件包含构建配置，使得原生 Windows 应用程序项目依赖于每个原生 Windows 库项目。

AutolinkedNativeModules.g.cpp（和 AutolinkedNativeModules.g.h）文件定义了一个函数，该函数返回包含每个库的IReactPackageProvider（它又包含每个库的原生模块和/或组件）的列表，以便这些库可以在运行时添加到 React Native 的注册包列表中。

注意：默认情况下，通常的run-windows 命令也会在构建 React Native for Windows 应用程序之前自动运行自动链接。

3. 调用原生库的 API 接口

当原生库正确连接到 React Native for Windows 应用程序后，应用程序的 JavaScript 应该能够在运行时调用库的 JavaScript API，并期待原生功能可用。也就是说，每次库的 JavaScript 需要访问其原生模块（和/或组件）时，它们都将已经准备好并在原生端注册。

3.1 使用原生模块的 API

如果您的库实现并导出了使用原生模块的任何 API，您可以从 JavaScript 中导入并调用它们。

对于我们的 example 应用程序，我们可以在 example\src\App.tsx 中看到库的 multiply 函数被导入和使用。

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

const result = multiply(3, 7);

export default function App() {
  return (
    <View style={styles.container}>
      <Text>Result: {result}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

3.2 使用原生组件

如果您的库实现并导出了使用原生组件的任何组件，您也可以从 JavaScript 中导入和使用它们。

对于我们的 example 应用程序，如果您遵循了原生平台：原生组件指南，我们可以在 example\src\App.tsx 中看到库的 CircleMask 组件被导入和使用。

import { Text, View, StyleSheet } from 'react-native';
import { multiply, CircleMask } from 'testlib';

const result = multiply(3, 7);

export default function App() {
  return (
    <View style={styles.container}>
      <CircleMask style={{ margin: 10 }}>
        <View
          style={{
            backgroundColor: '#006666',
            width: 100,
            height: 100,
            justifyContent: 'center',
            alignItems: 'center',
          }}
        >
          <Text>Result: {result}</Text>
        </View>
      </CircleMask>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

注意：提供的默认 example 应用程序是一个新架构应用程序，不能用于测试 Paper 原生组件。

3.3 验证功能

要验证功能是否端到端工作，您应该能够使用run-windows 命令启动提供的 example 应用程序。

yarn react-native run-windows

注意：对于我们的 example 应用程序，您可以从 example 文件夹内运行给定命令，或者直接从库的根文件夹运行 yarn example react-native run-windows。