Native Platform: Native Bibliotheken verwenden
Diese Anleitung beschreibt, wie Sie native Module (und/oder Komponenten) aus einer nativen Bibliothek in einer React Native für Windows-App nutzen können. Für einen Überblick über die Entwicklung nativer Apps lesen Sie bitte zuerst Native Platform: Overview, bevor Sie diese Anleitung lesen.
Hinweis: Die folgenden Anweisungen sind verallgemeinert und sollten mit den meisten nativen Bibliotheken funktionieren. Spezifische Bibliotheken können jedoch eigene Anleitungen und/oder zusätzliche Installationsschritte haben.
Überblick
Um eine native Bibliothek in einer React Native für Windows-App zu verwenden, müssen Sie
- Das native Bibliothekenpaket als Node.js-Abhängigkeit zur App hinzufügen
- React Native für Windows' Native Module Autolinking verwenden, um das Windows-Projekt der Bibliothek mit dem Windows-Projekt der App zu verbinden
- Die API-Oberfläche der nativen Bibliothek aus dem JavaScript-Code der App aufrufen
Schritt-für-Schritt-Anleitung
0. Einrichtung
Sie benötigen ein React Native-Bibliothekenprojekt mit initialisierter und implementierter Windows-Unterstützung.
Hinweis: Der Rest dieser Anleitung geht davon aus, dass Sie zumindest die Anleitung Native Platform: Native Modules befolgt haben, um ein neues Bibliothekenprojekt namens
testlibzu erstellen und zu implementieren, und dass Sie es über die bereitgestellte App in ihremexample-Ordner konsumieren werden.
1. Das native Bibliothekenpaket als Node.js-Abhängigkeit zur App hinzufügen
Als erstes müssen Sie das Node.js-Paket der nativen Bibliothek als Abhängigkeit Ihrer React Native-App hinzufügen, falls es noch nicht geschehen ist.
yarn add testlib
Hinweis: Dies ist zwar der Standardweg, um das Bibliothekenpaket als Abhängigkeit Ihrer App hinzuzufügen (insbesondere wenn Sie die Bibliothek veröffentlichen und aus einem NPM-Feed beziehen), aber so bezieht die bereitgestellte
example-App die Bibliothek nicht. Dieexample-App verwendet stattdessen einen benutzerdefinierten Eintrag imdependencies-Objekt ihrerreact-native.config.js-Konfiguration.
2. React Native für Windows' Native Module Autolinking verwenden
Bevor wir die native Bibliothek erfolgreich in unserer React Native für Windows-App nutzen können, müssen wir React Native für Windows' Autolinking, d.h. den autolink-windows Befehl, mindestens einmal ausführen, um die nativen Windows-Projekte der Bibliothek ordnungsgemäß mit dem nativen Windows-Projekt unserer App zu verbinden.
yarn react-native autolink-windows
Hinweis: Für unsere
example-App können Sie den angegebenen Befehl entweder aus demexample-Ordner heraus ausführen oderyarn example react-native autolink-windowsdirekt aus dem Stammverzeichnis der Bibliothek ausführen.
Der Befehl wird mehrere native Dateien im windows-Ordner der App (für die example-App im Ordner example\windows\testLibExample) neu generieren oder erstellen, darunter
<?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);
}
Hinweis: Die generierten Dateien enthalten die notwendige Konfiguration, um alle nativen Bibliotheken mit der React Native für Windows-App zu verbinden.
Die Dateien AutolinkedNativeModules.g.targets (und AutolinkedNativeModules.g.props) enthalten die Build-Konfiguration, sodass das native Windows-App-Projekt von jedem nativen Windows-Bibliothekenprojekt abhängt.
Die Dateien AutolinkedNativeModules.g.cpp (und AutolinkedNativeModules.g.h) definieren eine Funktion, die die Liste mit den IReactPackageProvider jeder Bibliothek zurückgibt (welche wiederum die nativen Module und/oder Komponenten jeder Bibliothek enthält), damit diese Bibliotheken zur Laufzeit zu React Natives Liste der registrierten Pakete hinzugefügt werden können.
Hinweis: Standardmäßig führt der übliche run-windows Befehl auch automatisch Autolinking aus, bevor eine React Native für Windows-App erstellt wird.
3. Die API-Oberfläche der nativen Bibliothek aufrufen
Nachdem die native Bibliothek ordnungsgemäß mit der React Native für Windows-App verbunden wurde, sollte der JavaScript-Code der App nun zur Laufzeit auf die JavaScript-APIs der Bibliothek zugreifen können und die native Funktionalität sollte verfügbar sein. Das bedeutet, jedes Mal, wenn der JavaScript-Code der Bibliothek auf seine nativen Module (und/oder Komponenten) zugreifen muss, sind diese bereits auf der nativen Seite vorbereitet und registriert.
3.1 API eines nativen Moduls verwenden
Wenn Ihre Bibliothek APIs implementiert und exportiert, die native Module verwenden, können Sie diese aus Ihrem JavaScript importieren und aufrufen.
In unserer example-App können wir sehen, wie die Funktion multiply der Bibliothek in example\src\App.tsx importiert und verwendet wird.
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 Eine native Komponente verwenden
Wenn Ihre Bibliothek Komponenten implementiert und exportiert, die native Komponenten verwenden, können Sie diese ebenfalls aus Ihrem JavaScript importieren und verwenden.
Für unsere example-App können wir, wenn Sie die Anleitung Native Platform: Native Components befolgt haben, sehen, wie die Komponente CircleMask der Bibliothek in dieser example\src\App.tsx importiert und verwendet wird.
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',
},
});
Hinweis: Die standardmäßige
example-App ist eine New Architecture-App und kann nicht zum Testen von Paper Native Components verwendet werden.
3.3 Funktionalität überprüfen
Um die End-to-End-Funktionalität zu überprüfen, sollten Sie in der Lage sein, die bereitgestellte example-App mit dem run-windows Befehl zu starten.
yarn react-native run-windows
Hinweis: Für unsere
example-App können Sie den angegebenen Befehl entweder aus demexample-Ordner heraus ausführen oderyarn example react-native run-windowsdirekt aus dem Stammverzeichnis der Bibliothek ausführen.