From 28ba571e66a77777766194b41fe24e6977110b4a Mon Sep 17 00:00:00 2001 From: Chiara Mooney <34109996+chiaramooney@users.noreply.github.com> Date: Fri, 8 Dec 2023 15:13:55 -0800 Subject: [PATCH] Cut Website Documentation for RNW v0.73 (#903) ## Description ### Why Update website for RNW v0.73. ###### Microsoft Reviewers: [Open in CodeFlow](https://microsoft.github.io/open-pr/?codeflow=https://github.com/microsoft/react-native-windows-samples/pull/903) --- docs/getting-started.md | 2 +- ...essibilityStateCheckedValue-api-windows.md | 16 + .../AccessibilityStates-api-windows.md | 8 +- ...DynamicAutomationProperties-api-windows.md | 30 +- docs/native-api/IRedBoxHandler-api-windows.md | 2 +- docs/native-api/QuirkSettings-api-windows.md | 12 +- .../ReactPointerEventArgs-api-windows.md | 7 + docs/native-api/ViewPanel-api-windows.md | 27 +- docs/native-api/index-api-windows.md | 1 + website/.unbroken_exclusions | 20 + website/README.md | 2 +- website/pages/en/support.js | 4 +- website/siteConfig.js | 2 +- .../version-0.73/getting-started.md | 116 ++++ website/versioned_docs/version-0.73/hermes.md | 121 ++++ ...essibilityStateCheckedValue-api-windows.md | 17 + .../AccessibilityStates-api-windows.md | 16 + ...DynamicAutomationProperties-api-windows.md | 184 ++++++ .../native-api/IRedBoxHandler-api-windows.md | 108 ++++ .../native-api/QuirkSettings-api-windows.md | 88 +++ .../ReactPointerEventArgs-api-windows.md | 50 ++ .../native-api/ViewPanel-api-windows.md | 79 +++ .../native-api/index-api-windows.md | 126 ++++ .../version-0.73/native-modules.md | 551 ++++++++++++++++++ website/versioned_docs/version-0.73/nuget.md | 63 ++ .../version-0.73-sidebars.json | 83 +++ website/versions.json | 1 + 27 files changed, 1669 insertions(+), 67 deletions(-) create mode 100644 docs/native-api/AccessibilityStateCheckedValue-api-windows.md create mode 100644 website/versioned_docs/version-0.73/getting-started.md create mode 100644 website/versioned_docs/version-0.73/hermes.md create mode 100644 website/versioned_docs/version-0.73/native-api/AccessibilityStateCheckedValue-api-windows.md create mode 100644 website/versioned_docs/version-0.73/native-api/AccessibilityStates-api-windows.md create mode 100644 website/versioned_docs/version-0.73/native-api/DynamicAutomationProperties-api-windows.md create mode 100644 website/versioned_docs/version-0.73/native-api/IRedBoxHandler-api-windows.md create mode 100644 website/versioned_docs/version-0.73/native-api/QuirkSettings-api-windows.md create mode 100644 website/versioned_docs/version-0.73/native-api/ReactPointerEventArgs-api-windows.md create mode 100644 website/versioned_docs/version-0.73/native-api/ViewPanel-api-windows.md create mode 100644 website/versioned_docs/version-0.73/native-api/index-api-windows.md create mode 100644 website/versioned_docs/version-0.73/native-modules.md create mode 100644 website/versioned_docs/version-0.73/nuget.md create mode 100644 website/versioned_sidebars/version-0.73-sidebars.json diff --git a/docs/getting-started.md b/docs/getting-started.md index 55af8cd11..6303cdb2e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -17,7 +17,7 @@ Remember to call `react-native init` from the place you want your project direct - + diff --git a/docs/native-api/AccessibilityStateCheckedValue-api-windows.md b/docs/native-api/AccessibilityStateCheckedValue-api-windows.md new file mode 100644 index 000000000..7202d535c --- /dev/null +++ b/docs/native-api/AccessibilityStateCheckedValue-api-windows.md @@ -0,0 +1,16 @@ +--- +id: AccessibilityStateCheckedValue +title: AccessibilityStateCheckedValue +--- + +Kind: `enum` + +| Name | Value | Description | +|--|--|--| +|`Unchecked` | 0x0 | | +|`Checked` | 0x1 | | +|`Mixed` | 0x2 | | + + +## Referenced by +- [`DynamicAutomationProperties`](DynamicAutomationProperties) diff --git a/docs/native-api/AccessibilityStates-api-windows.md b/docs/native-api/AccessibilityStates-api-windows.md index a00379dda..de1cf994e 100644 --- a/docs/native-api/AccessibilityStates-api-windows.md +++ b/docs/native-api/AccessibilityStates-api-windows.md @@ -10,8 +10,6 @@ Kind: `enum` |`Selected` | 0x0 | | |`Disabled` | 0x1 | | |`Checked` | 0x2 | | -|`Unchecked` | 0x3 | | -|`Busy` | 0x4 | | -|`Expanded` | 0x5 | | -|`Collapsed` | 0x6 | | -|`CountStates` | 0x7 | | +|`Busy` | 0x3 | | +|`Expanded` | 0x4 | | +|`CountStates` | 0x5 | | diff --git a/docs/native-api/DynamicAutomationProperties-api-windows.md b/docs/native-api/DynamicAutomationProperties-api-windows.md index 2c65f3736..5fee9854b 100644 --- a/docs/native-api/DynamicAutomationProperties-api-windows.md +++ b/docs/native-api/DynamicAutomationProperties-api-windows.md @@ -26,9 +26,6 @@ Kind: `class` ### AccessibilityStateCheckedProperty `static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityStateCheckedProperty` -### AccessibilityStateCollapsedProperty -`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityStateCollapsedProperty` - ### AccessibilityStateDisabledProperty `static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityStateDisabledProperty` @@ -38,9 +35,6 @@ Kind: `class` ### AccessibilityStateSelectedProperty `static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityStateSelectedProperty` -### AccessibilityStateUncheckedProperty -`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityStateUncheckedProperty` - ### AccessibilityValueMaxProperty `static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityValueMaxProperty` @@ -82,12 +76,7 @@ Kind: `class` ### GetAccessibilityStateChecked -`static` bool **`GetAccessibilityStateChecked`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) - - - -### GetAccessibilityStateCollapsed -`static` bool **`GetAccessibilityStateCollapsed`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) +`static` [`AccessibilityStateCheckedValue`](AccessibilityStateCheckedValue) **`GetAccessibilityStateChecked`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) @@ -106,11 +95,6 @@ Kind: `class` -### GetAccessibilityStateUnchecked -`static` bool **`GetAccessibilityStateUnchecked`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) - - - ### GetAccessibilityValueMax `static` double **`GetAccessibilityValueMax`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) @@ -157,12 +141,7 @@ Kind: `class` ### SetAccessibilityStateChecked -`static` void **`SetAccessibilityStateChecked`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, bool value) - - - -### SetAccessibilityStateCollapsed -`static` void **`SetAccessibilityStateCollapsed`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, bool value) +`static` void **`SetAccessibilityStateChecked`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, [`AccessibilityStateCheckedValue`](AccessibilityStateCheckedValue) value) @@ -181,11 +160,6 @@ Kind: `class` -### SetAccessibilityStateUnchecked -`static` void **`SetAccessibilityStateUnchecked`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, bool value) - - - ### SetAccessibilityValueMax `static` void **`SetAccessibilityValueMax`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, double value) diff --git a/docs/native-api/IRedBoxHandler-api-windows.md b/docs/native-api/IRedBoxHandler-api-windows.md index fda06c63e..712dd5407 100644 --- a/docs/native-api/IRedBoxHandler-api-windows.md +++ b/docs/native-api/IRedBoxHandler-api-windows.md @@ -31,7 +31,7 @@ class MyRedBoxHandler : IRedBoxHandler } public void ShowNewError(IRedBoxErrorInfo info, RedBoxErrorType type) { - // Dont report non-fatal errors (optional) + // Do not report non-fatal errors (optional) if (type != RedBoxErrorType.JavaScriptSoft) ReportErrorToMyErrorReportingSystem(info, type); diff --git a/docs/native-api/QuirkSettings-api-windows.md b/docs/native-api/QuirkSettings-api-windows.md index af2590d30..31d2ec6de 100644 --- a/docs/native-api/QuirkSettings-api-windows.md +++ b/docs/native-api/QuirkSettings-api-windows.md @@ -32,7 +32,6 @@ By default `react-native-windows` will handle various back events and forward th - ### SetMapWindowDeactivatedToAppStateInactive `static` void **`SetMapWindowDeactivatedToAppStateInactive`**([`ReactInstanceSettings`](ReactInstanceSettings) settings, bool value) @@ -65,6 +64,15 @@ When running multiple windows from a single UI thread, focusing a native view ca +### SetUseRuntimeScheduler +`static` void **`SetUseRuntimeScheduler`**([`ReactInstanceSettings`](ReactInstanceSettings) settings, bool value) + +> **EXPERIMENTAL** + +By default `react-native-windows` will use the new RuntimeScheduler.Setting this to false will revert the behavior to previous scheduling logic. + + + ### SetUseWebFlexBasisBehavior `static` void **`SetUseWebFlexBasisBehavior`**([`ReactInstanceSettings`](ReactInstanceSettings) settings, bool value) @@ -72,7 +80,7 @@ When running multiple windows from a single UI thread, focusing a native view ca **Default value**: `false` -There is a chance that cached flex basis values can cause text truncation in some re-layout scenarios. Enabling [Yoga](https://github.com/facebook/yoga)'s experimental web flex basis behavior fixes this issue, however using it may result in perfomance regressions due to additional layout passes. +There is a chance that cached flex basis values can cause text truncation in some re-layout scenarios. Enabling [Yoga](https://github.com/facebook/yoga)'s experimental web flex basis behavior fixes this issue, however using it may result in performance regressions due to additional layout passes. diff --git a/docs/native-api/ReactPointerEventArgs-api-windows.md b/docs/native-api/ReactPointerEventArgs-api-windows.md index ef5ea3f27..c0efaf5e9 100644 --- a/docs/native-api/ReactPointerEventArgs-api-windows.md +++ b/docs/native-api/ReactPointerEventArgs-api-windows.md @@ -12,6 +12,13 @@ Kind: `class` Event arguments wrapper for [`IViewManagerWithPointerEvents`](IViewManagerWithPointerEvents). ## Properties +### AllowUncaptured + bool `AllowUncaptured` + +> **EXPERIMENTAL** + +Gets or sets a flag that allows the ReactRootView to handle pointer events even when it does not capture the pointer. This is particularly useful for view managers that seek to capture the pointer to handle move events for a gesture (e.g., dragging), but conditionally may allow the ReactRootView to emit events (e.g., if the [`PointerEventKind.End`](PointerEventKind) event is received before a drag threshold is hit. + ### Args `readonly` [`PointerRoutedEventArgs`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Input.PointerRoutedEventArgs) `Args` diff --git a/docs/native-api/ViewPanel-api-windows.md b/docs/native-api/ViewPanel-api-windows.md index 2d6a4be39..f988a3da4 100644 --- a/docs/native-api/ViewPanel-api-windows.md +++ b/docs/native-api/ViewPanel-api-windows.md @@ -5,32 +5,17 @@ title: ViewPanel Kind: `class` -Extends: [`Panel`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Panel) +Extends: [`Grid`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Grid) ## Properties -### BorderBrush - [`Brush`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Media.Brush) `BorderBrush` - ### BorderBrushProperty `static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `BorderBrushProperty` -### BorderThickness - [`Thickness`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Thickness) `BorderThickness` - ### BorderThicknessProperty `static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `BorderThicknessProperty` -### ClipChildren - bool `ClipChildren` - -### ClipChildrenProperty -`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `ClipChildrenProperty` - -### CornerRadius - [`CornerRadius`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.CornerRadius) `CornerRadius` - ### CornerRadiusProperty `static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `CornerRadiusProperty` @@ -60,21 +45,11 @@ void **`Clear`**() -### FinalizeProperties -void **`FinalizeProperties`**() - - - ### GetLeft `static` double **`GetLeft`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) -### GetOuterBorder -[`Border`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Border) **`GetOuterBorder`**() - - - ### GetTop `static` double **`GetTop`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) diff --git a/docs/native-api/index-api-windows.md b/docs/native-api/index-api-windows.md index c0c01e10c..4a570f5d5 100644 --- a/docs/native-api/index-api-windows.md +++ b/docs/native-api/index-api-windows.md @@ -7,6 +7,7 @@ sidebar_label: Full reference ## Enums - [`AccessibilityRoles`](AccessibilityRoles) +- [`AccessibilityStateCheckedValue`](AccessibilityStateCheckedValue) - [`AccessibilityStates`](AccessibilityStates) - [`AccessibilityValue`](AccessibilityValue) - [`BackNavigationHandlerKind`](BackNavigationHandlerKind) diff --git a/website/.unbroken_exclusions b/website/.unbroken_exclusions index 7ea46fe19..2c3a57188 100644 --- a/website/.unbroken_exclusions +++ b/website/.unbroken_exclusions @@ -11,6 +11,7 @@ !versioned_docs/version-0.70/native-api/*-api-windows*.md !versioned_docs/version-0.71/native-api/*-api-windows*.md !versioned_docs/version-0.72/native-api/*-api-windows*.md +!versioned_docs/version-0.73/native-api/*-api-windows*.md # See Issue 410 File not found IReactContext while parsing versioned_docs/version-0.64/native-modules-advanced.md @@ -24,6 +25,25 @@ File not found native-api/IReactContext-api-windows.md while parsing versioned_d File not found native-api/ReactNativeHost-api-windows.md while parsing versioned_docs/version-0.72/native-modules-advanced.md #fix-unbroken.js auto-generated do not edit this line or below +File not found getting-started.md while parsing versioned_docs/version-0.73/getting-started.md +File not found native-modules.md while parsing versioned_docs/version-0.73/getting-started.md +File not found rnw-dependencies.md while parsing versioned_docs/version-0.73/getting-started.md +File not found run-windows-cli.md while parsing versioned_docs/version-0.73/getting-started.md +File not found getting-started.md while parsing versioned_docs/version-0.73/hermes.md +File not found rnm-getting-started.md while parsing versioned_docs/version-0.73/hermes.md +File not found native-modules-advanced.md while parsing versioned_docs/version-0.73/native-modules.md +File not found native-modules-vs-turbo-modules.md while parsing versioned_docs/version-0.73/native-modules.md +File not found native-modules-setup.md while parsing versioned_docs/version-0.73/native-modules.md +File not found native-modules-async.md while parsing versioned_docs/version-0.73/native-modules.md +File not found native-modules-jsvalue.md while parsing versioned_docs/version-0.73/native-modules.md +File not found view-managers.md while parsing versioned_docs/version-0.73/native-modules.md +File not found native-code-language-choice.md while parsing versioned_docs/version-0.73/native-modules.md +File not found getting-started.md while parsing versioned_docs/version-0.73/nuget.md +File not found nuget-update.md while parsing versioned_docs/version-0.73/nuget.md +File not found managing-cpp-deps.md while parsing versioned_docs/version-0.73/nuget.md +File not found upgrade-app.md while parsing versioned_docs/version-0.73/nuget.md +File not found native-modules-csharp-codegen.md while parsing versioned_docs/version-0.73/nuget.md +File not found supported-community-modules.md while parsing versioned_docs/version-0.73/nuget.md File not found IReactPackageProvider-api-windows.md while parsing versioned_docs/version-0.72/coreapp.md File not found ReactInstanceSettings-api-windows.md while parsing versioned_docs/version-0.72/coreapp.md File not found getting-started.md while parsing versioned_docs/version-0.72/getting-started.md diff --git a/website/README.md b/website/README.md index c29a75732..dee5fa641 100644 --- a/website/README.md +++ b/website/README.md @@ -186,7 +186,7 @@ Complete the documentation updates for both main and stable version 0.XX above. 1. Edit `website/.unbroken_exclusions` and add the line `!versioned_docs/version-0.XX/native-api/*-api-windows*.md` underneath the other versioned doc exclusions listed at the top of the file. 1. Update `support.js` and add/update the entry for the new version of React Native Windows with the correct release and Active Support Start Date _X_ (ex: 6/27/22). Then make sure to edit the previous version's: 1. Maintenance Start Date (set to the last day of the month that's 1 month out from _X_, ex: 7/31/22) - 2. End of Support Date (set to the last day of the month that's 3 months out from _X_, ex: 9/30/22) + 2. End of Support Date (set to the last day of the month that's 2 months out from _X_, ex: 9/30/22) 1. When you are ready for your new docs to be the default documentation on the website, edit `website/siteConfig.js` to point to 0.XX for its `defaultVersionShown` constant. # FAQ diff --git a/website/pages/en/support.js b/website/pages/en/support.js index 3e6e2084c..a90ae45fd 100644 --- a/website/pages/en/support.js +++ b/website/pages/en/support.js @@ -16,8 +16,8 @@ The React Native for Windows (RNW) Team strives to provide full support for the | Version | Support Phase | Release Date | Active Support Start | Maintenance Support Start | End of Support | | -- | -- | -- | -- | -- | -- | | [main](https://www.npmjs.com/package/react-native-windows/v/canary) | [Canary](#canary-support) | *N/A* | *N/A* | *N/A* | *N/A* | -| [0.73](https://www.npmjs.com/package/react-native-windows/v/preview) | [Preview](#preview-support) | *TBD* | *TBD* | *TBD* | *TBD* | -| [0.72](https://www.npmjs.com/package/react-native-windows/v/latest) | [Active](#active-support) | 06/23/2023 | 06/23/2023 | *TBD* | *TBD* | +| [0.73](https://www.npmjs.com/package/react-native-windows/v/latest) | [Active](#active-support) | 12/11/23 | 12/11/23 | *TBD* | *TBD* | +| [0.72](https://www.npmjs.com/package/react-native-windows/v/v0.72-stable) | [Active](#active-support) | 06/23/2023 | 06/23/2023 | 01/31/24 | 03/31/24 | | [0.71](https://www.npmjs.com/package/react-native-windows/v/v0.71-stable) | [Unsupported](#unsupported) | 01/23/2023 | 01/23/2023 | 07/31/2023 | 09/30/2023 | | [0.70](https://www.npmjs.com/package/react-native-windows/v/v0.70-stable) | [Unsupported](#unsupported) | 09/12/2022 | 09/12/2022 | 02/28/2023 | 04/30/2023 | | [0.69](https://www.npmjs.com/package/react-native-windows/v/v0.69-stable) | [Unsupported](#unsupported) | 06/27/2022 | 06/27/2022 | 10/31/2022 | 12/31/2022 | diff --git a/website/siteConfig.js b/website/siteConfig.js index f20061aac..2daade773 100644 --- a/website/siteConfig.js +++ b/website/siteConfig.js @@ -8,7 +8,7 @@ // See https://docusaurus.io/docs/site-config for all the possible // site configuration options. -const defaultVersionShown = "0.72"; +const defaultVersionShown = "0.73"; const repoUrl = "https://github.com/microsoft/react-native-windows"; const siteConfig = { diff --git a/website/versioned_docs/version-0.73/getting-started.md b/website/versioned_docs/version-0.73/getting-started.md new file mode 100644 index 000000000..a3c4d6bcb --- /dev/null +++ b/website/versioned_docs/version-0.73/getting-started.md @@ -0,0 +1,116 @@ +--- +id: version-0.73-getting-started +title: Get Started with Windows +original_id: getting-started +--- + +This guide will help you get started on setting up your very first React Native for Windows app. + +Make sure you have installed all of the [development dependencies](rnw-dependencies.md). + +For information around how to set up React Native, see the [React Native Getting Started Guide](https://reactnative.dev/docs/getting-started). + +## Install React Native for Windows + +Remember to call `react-native init` from the place you want your project directory to live. + + + + + + + + + +```bat +npx react-native@nightly init --version "nightly" +``` + +### Navigate into this newly created directory + +Once your project has been initialized, React Native will have created a new sub directory where all your generated files live. + +```bat +cd projectName +``` + +### Install the Windows extension + +Lastly, install the React Native for Windows packages. + +```bat +npx react-native-windows-init --overwrite +``` + +> The --overwrite flag copies a custom `metro.config.js` file. If you are starting a new app, this should have no impact. If you are adding Windows to your existing app and you have modified the `metro.config.js` file, please back up your changes, run the command and copy over to take effect. + +For information on the options that `react-native-windows-init` takes see [React Native Windows Init CLI](https://microsoft.github.io/react-native-windows/init-cli). + +## Running a React Native Windows App + +> Make sure a browser is launched and running before running a React Native Windows app. +> Also ensure your system meets all the [requirements](rnw-dependencies.md) to build a Windows app as well. + +- Without Using Visual Studio + + In your React Native Windows project directory, run: + + ```bat + npx react-native run-windows + ``` + + For information on the options that `@react-native-windows/cli` takes see [React Native Windows CLI](run-windows-cli.md). + + A new Command Prompt window will open with the React packager as well as a `react-native-windows` app. This step may take a while during first run since it involves building the entire project and all dependencies. You can now start developing! :tada: + +- Using Visual Studio + + - From the root of the project directory, run the following script which will automatically link your app's dependencies: + ```bat + npx react-native autolink-windows + ``` + - Open the solution file in the application folder in Visual Studio (e.g., `AwesomeProject/windows/AwesomeProject.sln` if you used `AwesomeProject` as ``) + - Select the `Debug` configuration and the `x64` platform from the combo box controls to the left of the `Run` button and underneath the `Team` and `Tools` menu item. + - Run `yarn start` (or `npm start`) from your project directory, and wait for the React Native packager to report success. + - Click the `Run` button to the right of the platform combo box control in VS, or select the `Debug`->`Start without Debugging` menu item. You now see your new app and Chrome should have loaded `http://localhost:8081/debugger-ui/` in a new tab. Press `F12` or `Ctrl+Shift+I` in Chrome to open its Developer Tools. :tada: + +- With VS Code + - Open your applications folder in VS Code. + - Install the [React Native Tools](https://marketplace.visualstudio.com/items?itemName=msjsdiag.vscode-react-native) plugin for VS Code. + - Create a new file in the applications root directory, `.vscode/launch.json` and paste the following configuration: + ```json + { + "version": "0.2.0", + "configurations": [ + { + "name": "Debug Windows", + "cwd": "${workspaceFolder}", + "type": "reactnative", + "request": "launch", + "platform": "windows" + } + ] + } + ``` + - Press `F5` or navigate to the debug menu (alternatively press `Ctrl+Shift+D`) and in the Debug drop-down select "Debug Windows" and press the green arrow to run the application. + +## Authoring Native Modules + +See [Native Modules and React Native Windows](native-modules.md). + +## Building a standalone React Native Windows App + +Follow these steps to build a version of your app that you can install or publish to the store. This version will package your bundle and assets into the APPX package so you don't need to run Metro. + +- Open the solution in Visual Studio +- Select the Release configuration from the Configuration Manager drop-down. +- Build the solution. You can now launch without first launching Metro. +- If you want to build an APPX package to share or publish, use the **Project** > **Publish** > **Create App Packages...** option. + +> The Debug configuration uses the Web Debugger by default, which means the application's JavaScript code runs in Chrome.
+> If you're getting different runtime behavior between the Release and Debug configurations, consider disabling the `UseWebDebugger` setting in [`App.cpp`](https://github.com/microsoft/react-native-windows/blob/6b415659aa017dbc41e3f28e817fb768a8e80435/vnext/template/cpp-app/src/App.cpp#L30) or [`App.xaml.cs`](https://github.com/microsoft/react-native-windows/blob/6b415659aa017dbc41e3f28e817fb768a8e80435/vnext/template/cs-app/src/App.xaml.cs#L20) to get the same behavior in the Debug configuration. + +See also this article for additional details: https://techcommunity.microsoft.com/t5/windows-dev-appconsult/getting-started-with-react-native-for-windows/ba-p/912093# + + + diff --git a/website/versioned_docs/version-0.73/hermes.md b/website/versioned_docs/version-0.73/hermes.md new file mode 100644 index 000000000..9a35c1a93 --- /dev/null +++ b/website/versioned_docs/version-0.73/hermes.md @@ -0,0 +1,121 @@ +--- +id: version-0.73-hermes +title: Hermes on Windows + macOS +original_id: hermes +--- + +# Hermes + +The [Hermes](https://hermesengine.dev/) engine is an open source JavaScript engine created by Facebook to optimize building and running React Native applications. + +To learn more about what it is and how to use it, check out the [React Native](https://reactnative.dev/docs/hermes#docsNav) documentation for it. + +## Hermes on Windows: + +Hermes is supported on Windows, generally providing better performance characteristics than the default Chakra engine. + +### Enabling Hermes for new projects + +Hermes is enabled by default for React Native Windows project. + +### Using Hermes in an existing project + +Set the `UseHermes` property to `true` in the `ExperimentalFeatures.props` file in your project's `windows` directory: + +```xml + + ... + true + +``` + +### Disabling Hermes + +To revert back to using Chakra, set the `UseHermes` property to `false` in the `ExperimentalFeatures.props` file in your project's `windows` directory: + +```xml + + ... + false + +``` + +### Known limitations + +- Hermes dll is not signed by Microsoft. + +## Hermes on macOS + +Hermes is available on React Native for macOS, provided you are using version 0.62 or higher. +To learn how to upgrade to the latest version, check out the **Upgrading** section of the [macOS Getting Started guide](rnm-getting-started.md). + +After you have upgraded to the latest version of React Native for macOS, install and add the following: + +1. Install the npm package `yarn add 'hermes-engine-darwin@^0.4.3'` +2. Add (or uncomment) the following pod dependencies to your macOS target in your `Podfile`:
+ +``` +pod 'React-Core/Hermes', :path => '../node_modules/react-native-macos/' +pod 'hermes', :path => '../node_modules/hermes-engine-darwin' +pod 'libevent', :podspec => '../node_modules/react-native-macos/third-party-podspecs/libevent.podspec' +``` + +3. Run `pod install` + +> Be sure to set your target's deployment target to at least 10.14 before running `pod install` + +## Hermes Inspector + +_React Native for Windows_ with _Hermes engine_ supports direct JavaScript runtime inspection using tools such as Chrome or [Edge `devtools`](https://docs.microsoft.com/microsoft-edge/devtools-guide-chromium/), [`VSCode` debugger](https://code.visualstudio.com/Docs/editor/debugging), [Flipper](https://fbflipper.com/) etc. by implementing an in-process Chrome Debug Protocol server. +Please note that it is fundamentally different from "Remote JS Debugging", which loads the JavaScript bundle into a remote Chrome browser session with duplex communication over IPC channels. + +We share the implementation (code and design) with other platforms wherever possible. All the external endpoints, APIs and protocols should be identical to _React Native_ environments on other platforms. +Hence, we expect most tooling available on other platforms to just work on Windows. But, as of now, we have tested only with Chrome and Edge `devtools`. + +### Steps to enable direct debugging + +1. Initialize React Native Host, + - Turn on `DeveloperSupport` + - Turn on `FastRefresh` + - Turn off `WebDebugger` + - Turn on `Direct Debugging` +2. Ensure Dev-Server is running +3. Start the application + +After the app has booted, + +4. Navigate to `edge://inspect` in Edge browser or `chrome://inspect` in Chrome browser +5. Enable **Discover network targets** and **configure** the target discovery settings to include `localhost:8081` (or wherever the metro server is running) +6. Within a few seconds "Hermes React Native" should appear on the page as a remote target +7. Click on the **inspect** link to launch the `devtools` page +8. Click `Ctrl+P` to open source files and set break points +9. Alternatively, you can insert `debugger` statements in source code to break on specific locations + +In order to break on locations during boot, you can either + +- Add statements into the boot sequence to pause the runtime waiting for debugger to connect. + +```js +debugger; +``` + +- Set a break point and refresh the bundle through the Dev Server. The runtime will wait for debugger to attach. + +### Steps to enable heap profiling + +Follow steps 1-7 from above, and then + +1. Click on the "Memory" tab in the inspector +2. Heap snapshots and instrumented allocations should be working. + +### Enable debugging/profiling on release builds + +We keep the inspector turned off on release builds by default. If you want to debug or profile release builds, set the MSBuild property `EnableHermesInspectorInReleaseFlavor` to `'true'` when building the platform. + +```bash +npx react-native run-windows --msbuild EnableHermesInspectorInReleaseFlavor=true +``` + +### Known Issues + +1. CPU Sampling profiler currently doesn't work. diff --git a/website/versioned_docs/version-0.73/native-api/AccessibilityStateCheckedValue-api-windows.md b/website/versioned_docs/version-0.73/native-api/AccessibilityStateCheckedValue-api-windows.md new file mode 100644 index 000000000..344ec867c --- /dev/null +++ b/website/versioned_docs/version-0.73/native-api/AccessibilityStateCheckedValue-api-windows.md @@ -0,0 +1,17 @@ +--- +id: version-0.73-AccessibilityStateCheckedValue +title: AccessibilityStateCheckedValue +original_id: AccessibilityStateCheckedValue +--- + +Kind: `enum` + +| Name | Value | Description | +|--|--|--| +|`Unchecked` | 0x0 | | +|`Checked` | 0x1 | | +|`Mixed` | 0x2 | | + + +## Referenced by +- [`DynamicAutomationProperties`](DynamicAutomationProperties) diff --git a/website/versioned_docs/version-0.73/native-api/AccessibilityStates-api-windows.md b/website/versioned_docs/version-0.73/native-api/AccessibilityStates-api-windows.md new file mode 100644 index 000000000..2cdad9b02 --- /dev/null +++ b/website/versioned_docs/version-0.73/native-api/AccessibilityStates-api-windows.md @@ -0,0 +1,16 @@ +--- +id: version-0.73-AccessibilityStates +title: AccessibilityStates +original_id: AccessibilityStates +--- + +Kind: `enum` + +| Name | Value | Description | +|--|--|--| +|`Selected` | 0x0 | | +|`Disabled` | 0x1 | | +|`Checked` | 0x2 | | +|`Busy` | 0x3 | | +|`Expanded` | 0x4 | | +|`CountStates` | 0x5 | | diff --git a/website/versioned_docs/version-0.73/native-api/DynamicAutomationProperties-api-windows.md b/website/versioned_docs/version-0.73/native-api/DynamicAutomationProperties-api-windows.md new file mode 100644 index 000000000..7ed065e08 --- /dev/null +++ b/website/versioned_docs/version-0.73/native-api/DynamicAutomationProperties-api-windows.md @@ -0,0 +1,184 @@ +--- +id: version-0.73-DynamicAutomationProperties +title: DynamicAutomationProperties +original_id: DynamicAutomationProperties +--- + +Kind: `class` + + + +## Properties +### AccessibilityActionEventHandlerProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityActionEventHandlerProperty` + +### AccessibilityActionsProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityActionsProperty` + +### AccessibilityInvokeEventHandlerProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityInvokeEventHandlerProperty` + +### AccessibilityRoleProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityRoleProperty` + +### AccessibilityStateBusyProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityStateBusyProperty` + +### AccessibilityStateCheckedProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityStateCheckedProperty` + +### AccessibilityStateDisabledProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityStateDisabledProperty` + +### AccessibilityStateExpandedProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityStateExpandedProperty` + +### AccessibilityStateSelectedProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityStateSelectedProperty` + +### AccessibilityValueMaxProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityValueMaxProperty` + +### AccessibilityValueMinProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityValueMinProperty` + +### AccessibilityValueNowProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityValueNowProperty` + +### AccessibilityValueTextProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `AccessibilityValueTextProperty` + + + +## Methods +### GetAccessibilityActionEventHandler +`static` [`AccessibilityActionEventHandler`](AccessibilityActionEventHandler) **`GetAccessibilityActionEventHandler`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityActions +`static` [`IVector`](https://docs.microsoft.com/uwp/api/Windows.Foundation.Collections.IVector-1)<[`AccessibilityAction`](AccessibilityAction)> **`GetAccessibilityActions`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityInvokeEventHandler +`static` [`AccessibilityInvokeEventHandler`](AccessibilityInvokeEventHandler) **`GetAccessibilityInvokeEventHandler`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityRole +`static` [`AccessibilityRoles`](AccessibilityRoles) **`GetAccessibilityRole`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityStateBusy +`static` bool **`GetAccessibilityStateBusy`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityStateChecked +`static` [`AccessibilityStateCheckedValue`](AccessibilityStateCheckedValue) **`GetAccessibilityStateChecked`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityStateDisabled +`static` bool **`GetAccessibilityStateDisabled`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityStateExpanded +`static` bool **`GetAccessibilityStateExpanded`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityStateSelected +`static` bool **`GetAccessibilityStateSelected`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityValueMax +`static` double **`GetAccessibilityValueMax`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityValueMin +`static` double **`GetAccessibilityValueMin`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityValueNow +`static` double **`GetAccessibilityValueNow`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetAccessibilityValueText +`static` string **`GetAccessibilityValueText`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### SetAccessibilityActionEventHandler +`static` void **`SetAccessibilityActionEventHandler`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, [`AccessibilityActionEventHandler`](AccessibilityActionEventHandler) value) + + + +### SetAccessibilityActions +`static` void **`SetAccessibilityActions`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, [`IVector`](https://docs.microsoft.com/uwp/api/Windows.Foundation.Collections.IVector-1)<[`AccessibilityAction`](AccessibilityAction)> value) + + + +### SetAccessibilityInvokeEventHandler +`static` void **`SetAccessibilityInvokeEventHandler`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, [`AccessibilityInvokeEventHandler`](AccessibilityInvokeEventHandler) value) + + + +### SetAccessibilityRole +`static` void **`SetAccessibilityRole`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, [`AccessibilityRoles`](AccessibilityRoles) value) + + + +### SetAccessibilityStateBusy +`static` void **`SetAccessibilityStateBusy`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, bool value) + + + +### SetAccessibilityStateChecked +`static` void **`SetAccessibilityStateChecked`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, [`AccessibilityStateCheckedValue`](AccessibilityStateCheckedValue) value) + + + +### SetAccessibilityStateDisabled +`static` void **`SetAccessibilityStateDisabled`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, bool value) + + + +### SetAccessibilityStateExpanded +`static` void **`SetAccessibilityStateExpanded`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, bool value) + + + +### SetAccessibilityStateSelected +`static` void **`SetAccessibilityStateSelected`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, bool value) + + + +### SetAccessibilityValueMax +`static` void **`SetAccessibilityValueMax`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, double value) + + + +### SetAccessibilityValueMin +`static` void **`SetAccessibilityValueMin`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, double value) + + + +### SetAccessibilityValueNow +`static` void **`SetAccessibilityValueNow`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, double value) + + + +### SetAccessibilityValueText +`static` void **`SetAccessibilityValueText`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, string value) + + + + diff --git a/website/versioned_docs/version-0.73/native-api/IRedBoxHandler-api-windows.md b/website/versioned_docs/version-0.73/native-api/IRedBoxHandler-api-windows.md new file mode 100644 index 000000000..bd1150565 --- /dev/null +++ b/website/versioned_docs/version-0.73/native-api/IRedBoxHandler-api-windows.md @@ -0,0 +1,108 @@ +--- +id: version-0.73-IRedBoxHandler +title: IRedBoxHandler +original_id: IRedBoxHandler +--- + +Kind: `interface` + + + +`IRedBoxHandler` provides an extension point to allow custom error handling within the React instance. +This can be useful if you have an existing error reporting system that you want React errors to be reported to. +The default implementation of `RedBoxHandler` shows an error messages in a error screen +that covers the whole application window. + +If you want to maintain the existing `RedBox` behaviors, and also report errors to your own reporting system, +your implementation can call into the default `RedBoxHandler`, which can be obtained by calling : + +```csharp +RedBoxHelper::CreateDefaultHandler(Host); +``` + +Sample settings up a `RedBoxHandler` that reports errors to an external system, and displays the default `RedBox` +experience within the application: + +```csharp + +class MyRedBoxHandler : IRedBoxHandler +{ + MyRedBoxHandler(IRedBoxHandler defaultHandler) { + innerHandler = defaultHandler; + } + + public void ShowNewError(IRedBoxErrorInfo info, RedBoxErrorType type) { + // Do not report non-fatal errors (optional) + if (type != RedBoxErrorType.JavaScriptSoft) + ReportErrorToMyErrorReportingSystem(info, type); + + // Display errors in app if the instance is running with DevSupportEnabled + if (innerHandler.IsDevSupportEnabled) + innerHandler.ShowNewError(info, type); + } + + public bool IsDevSupportEnabled { + get; + } + { + // The default handler will return true if the instance has DevSupport turned on + // But if you want to record error information in released versions of your app + // Then you should return true here, so that all errors get reported. + return true; + } + + public void UpdateError(IRedBoxErrorInfo info) { + if (innerHandler.IsDevSupportEnabled) + innerHandler.UpdateError(info); + } + + public void DismissRedBox() { + if (innerHandler.IsDevSupportEnabled) + innerHandler.DismissRedBox(); + } + + private IRedBoxHandler innerHandler; +} + + +RegisterMyRedBoxHandler() +{ + Host.InstanceSettings.RedBoxHandler = new MyRedBoxHandler(RedBoxHelper.CreateDefaultHandler(Host)); +} + +``` + +## Properties +### IsDevSupportEnabled +`readonly` bool `IsDevSupportEnabled` + +This property will control if errors should be reported to the handler. If this returns false, [`ShowNewError`](#shownewerror) and [`UpdateError`](#updateerror) will not be called. + + + +## Methods +### DismissRedBox +void **`DismissRedBox`**() + + + +### ShowNewError +void **`ShowNewError`**([`IRedBoxErrorInfo`](IRedBoxErrorInfo) info, [`RedBoxErrorType`](RedBoxErrorType) type) + +This method is called when an error is initially hit. + + + +### UpdateError +void **`UpdateError`**([`IRedBoxErrorInfo`](IRedBoxErrorInfo) info) + +This method is called when updated information about an error has been resolved. For JavaScript errors, this is called if source map information was able to be resolved to provide a more useful call stack. + + + + + + +## Referenced by +- [`ReactInstanceSettings`](ReactInstanceSettings) +- [`RedBoxHelper`](RedBoxHelper) diff --git a/website/versioned_docs/version-0.73/native-api/QuirkSettings-api-windows.md b/website/versioned_docs/version-0.73/native-api/QuirkSettings-api-windows.md new file mode 100644 index 000000000..8c7ae59e5 --- /dev/null +++ b/website/versioned_docs/version-0.73/native-api/QuirkSettings-api-windows.md @@ -0,0 +1,88 @@ +--- +id: version-0.73-QuirkSettings +title: QuirkSettings +original_id: QuirkSettings +--- + +Kind: `class` + + + +> **EXPERIMENTAL** + +This can be used to add settings that allow react-native-windows behavior to be maintained across version updates to facilitate upgrades. Settings in this class are likely to be removed in future releases, so apps should try to update their code to not rely on these settings. + + + +## Methods +### SetAcceptSelfSigned +`static` void **`SetAcceptSelfSigned`**([`ReactInstanceSettings`](ReactInstanceSettings) settings, bool value) + +> **EXPERIMENTAL** + +Runtime setting allowing Networking (HTTP, WebSocket) connections to skip certificate validation. + + + +### SetBackHandlerKind +`static` void **`SetBackHandlerKind`**([`ReactInstanceSettings`](ReactInstanceSettings) settings, [`BackNavigationHandlerKind`](BackNavigationHandlerKind) kind) + +> **EXPERIMENTAL** + +By default `react-native-windows` will handle various back events and forward them to JavaScript. Setting this to [`BackNavigationHandlerKind.Native`](BackNavigationHandlerKind) prevents `react-native-windows` from handling these events, including forwarding to JavaScript. This will allow applications to handle back navigation in native code, but will prevent the `BackHandler` native module from receiving events. + + + +### SetMapWindowDeactivatedToAppStateInactive +`static` void **`SetMapWindowDeactivatedToAppStateInactive`**([`ReactInstanceSettings`](ReactInstanceSettings) settings, bool value) + +> **EXPERIMENTAL** + +**Default value**: `false` + +By default `react-native-windows` will only track `active` and `background` `AppState`. Setting this to true enables `react-native-windows` to also track `inactive` `AppState` which [maps closely to iOS.](https://reactnative.dev/docs/appstate)`inactive` tracks the [Window.Activated Event](https://docs.microsoft.com/uwp/api/windows.ui.core.corewindow.activated) when the window is deactivated. + + + +### SetMatchAndroidAndIOSStretchBehavior +`static` void **`SetMatchAndroidAndIOSStretchBehavior`**([`ReactInstanceSettings`](ReactInstanceSettings) settings, bool value) + +> **EXPERIMENTAL** + +**Default value**: `true` + +Older versions of react-native-windows did not use [Yoga](https://github.com/facebook/yoga)'s legacy stretch behavior. This meant that react-native-windows would layout views slightly differently that in iOS and Android. +Set this setting to false to maintain the behavior from react-native-windows <= 0.62. + + + +### SetSuppressWindowFocusOnViewFocus +`static` void **`SetSuppressWindowFocusOnViewFocus`**([`ReactInstanceSettings`](ReactInstanceSettings) settings, bool value) + +> **EXPERIMENTAL** + +When running multiple windows from a single UI thread, focusing a native view causes the parent window of that view to get focus as well. Set this setting to true to prevent focus of a blurred window when a view in that window is programmatically focused. + + + +### SetUseRuntimeScheduler +`static` void **`SetUseRuntimeScheduler`**([`ReactInstanceSettings`](ReactInstanceSettings) settings, bool value) + +> **EXPERIMENTAL** + +By default `react-native-windows` will use the new RuntimeScheduler.Setting this to false will revert the behavior to previous scheduling logic. + + + +### SetUseWebFlexBasisBehavior +`static` void **`SetUseWebFlexBasisBehavior`**([`ReactInstanceSettings`](ReactInstanceSettings) settings, bool value) + +> **EXPERIMENTAL** + +**Default value**: `false` + +There is a chance that cached flex basis values can cause text truncation in some re-layout scenarios. Enabling [Yoga](https://github.com/facebook/yoga)'s experimental web flex basis behavior fixes this issue, however using it may result in performance regressions due to additional layout passes. + + + + diff --git a/website/versioned_docs/version-0.73/native-api/ReactPointerEventArgs-api-windows.md b/website/versioned_docs/version-0.73/native-api/ReactPointerEventArgs-api-windows.md new file mode 100644 index 000000000..acbb5c405 --- /dev/null +++ b/website/versioned_docs/version-0.73/native-api/ReactPointerEventArgs-api-windows.md @@ -0,0 +1,50 @@ +--- +id: version-0.73-ReactPointerEventArgs +title: ReactPointerEventArgs +original_id: ReactPointerEventArgs +--- + +Kind: `class` + + + +> **EXPERIMENTAL** + +Event arguments wrapper for [`IViewManagerWithPointerEvents`](IViewManagerWithPointerEvents). + +## Properties +### AllowUncaptured + bool `AllowUncaptured` + +> **EXPERIMENTAL** + +Gets or sets a flag that allows the ReactRootView to handle pointer events even when it does not capture the pointer. This is particularly useful for view managers that seek to capture the pointer to handle move events for a gesture (e.g., dragging), but conditionally may allow the ReactRootView to emit events (e.g., if the [`PointerEventKind.End`](PointerEventKind) event is received before a drag threshold is hit. + +### Args +`readonly` [`PointerRoutedEventArgs`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Input.PointerRoutedEventArgs) `Args` + +> **EXPERIMENTAL** + +Gets the wrapped routed pointer event. + +### Kind + [`PointerEventKind`](PointerEventKind) `Kind` + +> **EXPERIMENTAL** + +Gets or sets the pointer event kind. The only valid override is [`PointerEventKind.CaptureLost`](PointerEventKind) to [`PointerEventKind.End`](PointerEventKind) to handle cases where PointerCaptureLost events on ReactRootView can be safely treated as PointerReleased events, e.g., for pointer events on selectable text. + +### Target + Object `Target` + +> **EXPERIMENTAL** + +Gets or sets the React target for the pointer event. + + + + + + +## Referenced by +- [`IViewManagerWithPointerEvents`](IViewManagerWithPointerEvents) diff --git a/website/versioned_docs/version-0.73/native-api/ViewPanel-api-windows.md b/website/versioned_docs/version-0.73/native-api/ViewPanel-api-windows.md new file mode 100644 index 000000000..dc5b26837 --- /dev/null +++ b/website/versioned_docs/version-0.73/native-api/ViewPanel-api-windows.md @@ -0,0 +1,79 @@ +--- +id: version-0.73-ViewPanel +title: ViewPanel +original_id: ViewPanel +--- + +Kind: `class` + +Extends: [`Grid`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.Grid) + + + +## Properties +### BorderBrushProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `BorderBrushProperty` + +### BorderThicknessProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `BorderThicknessProperty` + +### CornerRadiusProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `CornerRadiusProperty` + +### LeftProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `LeftProperty` + +### TopProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `TopProperty` + +### ViewBackground + [`Brush`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Media.Brush) `ViewBackground` + +### ViewBackgroundProperty +`static` `readonly` [`DependencyProperty`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.DependencyProperty) `ViewBackgroundProperty` + + +## Constructors +### ViewPanel + **`ViewPanel`**() + + + + +## Methods +### Clear +void **`Clear`**() + + + +### GetLeft +`static` double **`GetLeft`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### GetTop +`static` double **`GetTop`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element) + + + +### InsertAt +void **`InsertAt`**(uint32_t index, [`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) value) + + + +### RemoveAt +void **`RemoveAt`**(uint32_t index) + + + +### SetLeft +`static` void **`SetLeft`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, double value) + + + +### SetTop +`static` void **`SetTop`**([`UIElement`](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.UIElement) element, double value) + + + + diff --git a/website/versioned_docs/version-0.73/native-api/index-api-windows.md b/website/versioned_docs/version-0.73/native-api/index-api-windows.md new file mode 100644 index 000000000..ff1f69faa --- /dev/null +++ b/website/versioned_docs/version-0.73/native-api/index-api-windows.md @@ -0,0 +1,126 @@ +--- +id: version-0.73-Native-API-Reference +title: namespace Microsoft.ReactNative +sidebar_label: Full reference +: +original_id: Native-API-Reference +--- + +## Enums +- [`AccessibilityRoles`](AccessibilityRoles) +- [`AccessibilityStateCheckedValue`](AccessibilityStateCheckedValue) +- [`AccessibilityStates`](AccessibilityStates) +- [`AccessibilityValue`](AccessibilityValue) +- [`BackNavigationHandlerKind`](BackNavigationHandlerKind) +- [`CanvasComposite`](CanvasComposite) +- [`CanvasEdgeBehavior`](CanvasEdgeBehavior) +- [`EffectBorderMode`](EffectBorderMode) +- [`EffectOptimization`](EffectOptimization) +- [`JSIEngine`](JSIEngine) +- [`JSValueType`](JSValueType) +- [`JsiErrorType`](JsiErrorType) +- [`JsiValueKind`](JsiValueKind) +- [`LoadingState`](LoadingState) +- [`LogLevel`](LogLevel) +- [`MethodReturnType`](MethodReturnType) +- [`PointerEventKind`](PointerEventKind) +- [`RedBoxErrorType`](RedBoxErrorType) +- [`ViewManagerPropertyType`](ViewManagerPropertyType) +## Interfaces +- [`IJSValueReader`](IJSValueReader) +- [`IJSValueWriter`](IJSValueWriter) +- [`IJsiByteBuffer`](IJsiByteBuffer) +- [`IJsiHostObject`](IJsiHostObject) +- [`IReactContext`](IReactContext) +- [`IReactDispatcher`](IReactDispatcher) +- [`IReactModuleBuilder`](IReactModuleBuilder) +- [`IReactNonAbiValue`](IReactNonAbiValue) +- [`IReactNotificationArgs`](IReactNotificationArgs) +- [`IReactNotificationService`](IReactNotificationService) +- [`IReactNotificationSubscription`](IReactNotificationSubscription) +- [`IReactPackageBuilder`](IReactPackageBuilder) +- [`IReactPackageProvider`](IReactPackageProvider) +- [`IReactPropertyBag`](IReactPropertyBag) +- [`IReactPropertyName`](IReactPropertyName) +- [`IReactPropertyNamespace`](IReactPropertyNamespace) +- [`IReactSettingsSnapshot`](IReactSettingsSnapshot) +- [`IReactViewHost`](IReactViewHost) +- [`IReactViewInstance`](IReactViewInstance) +- [`IRedBoxErrorFrameInfo`](IRedBoxErrorFrameInfo) +- [`IRedBoxErrorInfo`](IRedBoxErrorInfo) +- [`IRedBoxHandler`](IRedBoxHandler) +- [`IViewManager`](IViewManager) +- [`IViewManagerCreateWithProperties`](IViewManagerCreateWithProperties) +- [`IViewManagerRequiresNativeLayout`](IViewManagerRequiresNativeLayout) +- [`IViewManagerWithChildren`](IViewManagerWithChildren) +- [`IViewManagerWithCommands`](IViewManagerWithCommands) +- [`IViewManagerWithDropViewInstance`](IViewManagerWithDropViewInstance) +- [`IViewManagerWithExportedEventTypeConstants`](IViewManagerWithExportedEventTypeConstants) +- [`IViewManagerWithExportedViewConstants`](IViewManagerWithExportedViewConstants) +- [`IViewManagerWithNativeProperties`](IViewManagerWithNativeProperties) +- [`IViewManagerWithOnLayout`](IViewManagerWithOnLayout) +- [`IViewManagerWithPointerEvents`](IViewManagerWithPointerEvents) +- [`IViewManagerWithReactContext`](IViewManagerWithReactContext) +## Structs +- [`AccessibilityAction`](AccessibilityAction) +- [`DesktopWindowMessage`](DesktopWindowMessage) +- [`JsiBigIntRef`](JsiBigIntRef) +- [`JsiObjectRef`](JsiObjectRef) +- [`JsiPropertyIdRef`](JsiPropertyIdRef) +- [`JsiScopeState`](JsiScopeState) +- [`JsiStringRef`](JsiStringRef) +- [`JsiSymbolRef`](JsiSymbolRef) +- [`JsiValueRef`](JsiValueRef) +- [`JsiWeakObjectRef`](JsiWeakObjectRef) +## Classes +- [`BorderEffect`](BorderEffect) +- [`ColorSourceEffect`](ColorSourceEffect) +- [`CompositeStepEffect`](CompositeStepEffect) +- [`CoreAppPage`](CoreAppPage) +- [`DevMenuControl`](DevMenuControl) +- [`DynamicAutomationPeer`](DynamicAutomationPeer) +- [`DynamicAutomationProperties`](DynamicAutomationProperties) +- [`DynamicValueProvider`](DynamicValueProvider) +- [`GaussianBlurEffect`](GaussianBlurEffect) +- [`InstanceCreatedEventArgs`](InstanceCreatedEventArgs) +- [`InstanceDestroyedEventArgs`](InstanceDestroyedEventArgs) +- [`InstanceLoadedEventArgs`](InstanceLoadedEventArgs) +- [`JsiError`](JsiError) +- [`JsiPreparedJavaScript`](JsiPreparedJavaScript) +- [`JsiRuntime`](JsiRuntime) +- [`LayoutService`](LayoutService) +- [`QuirkSettings`](QuirkSettings) +- [`ReactApplication`](ReactApplication) +- [`ReactCoreInjection`](ReactCoreInjection) +- [`ReactDispatcherHelper`](ReactDispatcherHelper) +- [`ReactInstanceSettings`](ReactInstanceSettings) +- [`ReactNativeHost`](ReactNativeHost) +- [`ReactNotificationServiceHelper`](ReactNotificationServiceHelper) +- [`ReactPointerEventArgs`](ReactPointerEventArgs) +- [`ReactPropertyBagHelper`](ReactPropertyBagHelper) +- [`ReactRootView`](ReactRootView) +- [`ReactViewOptions`](ReactViewOptions) +- [`RedBoxHelper`](RedBoxHelper) +- [`ViewControl`](ViewControl) +- [`ViewPanel`](ViewPanel) +- [`XamlHelper`](XamlHelper) +- [`XamlMetaDataProvider`](XamlMetaDataProvider) +- [`XamlUIService`](XamlUIService) +## Delegates +- [`AccessibilityActionEventHandler`](AccessibilityActionEventHandler) +- [`AccessibilityInvokeEventHandler`](AccessibilityInvokeEventHandler) +- [`ConstantProviderDelegate`](ConstantProviderDelegate) +- [`InitializerDelegate`](InitializerDelegate) +- [`JSValueArgWriter`](JSValueArgWriter) +- [`JsiByteArrayUser`](JsiByteArrayUser) +- [`JsiHostFunction`](JsiHostFunction) +- [`LogHandler`](LogHandler) +- [`MethodDelegate`](MethodDelegate) +- [`MethodResultCallback`](MethodResultCallback) +- [`ReactCreatePropertyValue`](ReactCreatePropertyValue) +- [`ReactDispatcherCallback`](ReactDispatcherCallback) +- [`ReactModuleProvider`](ReactModuleProvider) +- [`ReactNotificationHandler`](ReactNotificationHandler) +- [`ReactViewManagerProvider`](ReactViewManagerProvider) +- [`SyncMethodDelegate`](SyncMethodDelegate) +- [`UIBatchCompleteCallback`](UIBatchCompleteCallback) diff --git a/website/versioned_docs/version-0.73/native-modules.md b/website/versioned_docs/version-0.73/native-modules.md new file mode 100644 index 000000000..a8d88ebac --- /dev/null +++ b/website/versioned_docs/version-0.73/native-modules.md @@ -0,0 +1,551 @@ +--- +id: version-0.73-native-modules +title: Native Modules +original_id: native-modules +--- + +> **This documentation and the underlying platform code is a work in progress.** +> **Examples (C# and C++/WinRT):** +> +> - [Native Module Sample in `microsoft/react-native-windows-samples`](https://github.com/microsoft/react-native-windows-samples/tree/main/samples/NativeModuleSample) +> - [Sample App in `microsoft/react-native-windows/packages/microsoft-reactnative-sampleapps`](https://github.com/microsoft/react-native-windows/tree/main/packages/sample-apps) + +Sometimes an app needs access to a platform API that React Native doesn't have a corresponding module for yet. Maybe you want to reuse some existing .NET code without having to re-implement it in JavaScript, or write some high performance, multi-threaded code for image processing, a database, or any number of advanced extensions. + +React Native was designed such that it is possible for you to write real native code and have access to the full power of the platform. This is a more advanced feature and we don't expect it to be part of the usual development process, however it is essential that it exists. If React Native doesn't support a native feature that you need, you should be able to build it yourself. + +> NOTE: If you are building a widget that has a UI component, check out the [Native UI Component guide](view-managers.md). + +## Overview + +Native modules contain (or wrap) native code which can then be exposed to JS. To accomplish this in React Native for Windows, at a high level you must: + +1. Author your native module, which is the class that calls your native code. + 1. Add custom attributes to the class. These attributes allow you to define methods, properties, constants, and events that can be referenced from JavaScript. +1. Register your native module. Note that native modules defined within your app are automatically registered. + 1. Add the package to your React Native application. +1. Use your native module from your JavaScript code. + +React Native for Windows supports authoring native modules in both C# and C++. Examples of both are provided below. Please see the [Choosing C++ or C# for native code](native-code-language-choice.md) note for more information about which to choose. + +> NOTE: If you are unable to use the reflection-based annotation approach, you can define native modules directly using the ABI. This is outlined in the [Writing Native Modules without using Attributes](native-modules-advanced.md) document. + +## Initial Setup + +Follow the [Native Modules Setup Guide](native-modules-setup.md) to create the Visual Studio infrastructure to author your own stand-alone native module for React Native Windows. + +Once you have set up your development environment and project structure, you are ready to write code. + +Open the Visual Studio solution in the `windows` folder and add the new files directly to the app project. + +## Sample Native Module + +### 1. Configure windows codegen in `package.json` + +Add the following object to your package's `package.json` file: + +```json + "codegenConfig": { + "name": "NameOfYourApp", + "type": "modules", + "jsSrcsDir": "src", + "windows": { + "namespace": "YourAppCodegenNamespace", + "cppStringType": "std::string", /* optional */ + "separateDataTypes": false, /* optional */ + "outputDirectory": "codegen" /* optional */ + } + }, +``` + +The values for `name`, `type`, `jsSrcsDir` are shared with react-native as documented [here](https://reactnative.dev/docs/next/the-new-architecture/pillars-turbomodules). The `windows` object will cause the windows-codegen task to generate windows specific codegen for any TurboModule spec files defined within your project. + +- `windows.namespace`: Required. This property controls which C++ namespace these generated files are using. +- `windows.cppStringType`: Optional. This property controls which C++ string type is used in generated files. The default value is `std::string`. You could choose between `std::string` and `std::wstring`. +- `windows.separateDataTypes`: Optional. + - The default value is `false`, in which case `NativeAbcSpec.g.h` is generated from `NativeAbc.ts`, or with other recognized file extension. + - When it is `true`: + - `NativeAbcDataTypes.h` and `NativeAbcSpec.g.h` are generated. `NativeAbcDataTypes.h` contains all custom types defined in `NativeAbc.ts`. + - `NativeAbcSpec.g.h` contains all the remaining code. + - `NativeAbcSpec.g.h` does not include `NativeAbcDataTypes.h`. + - If there is no custom types, `NativeAbcDataTypes.h` will not be generated even when `windows.separateDataTypes` is `true`. +- `windows.outputDirectory`: Optional. This property controls where generated files are located. The default value is `codegen`, which put files in the `codegen` folder under the working directory. If such folder does not exist at the moment, it will be created. + +### 2. Create JavaScript Specification + +Modules should have a definition defined in a typed dialect of JavaScript (either TypeScript or Flow). Codegen will use these specifications to verify the interface provided by your native code. + +There are two requirements the file containing this specification must meet: + +- The file **must** be named `Native`, with a `.js` or `.jsx` extension when using Flow, or a `.ts`, or `.tsx` extension when using TypeScript. +- The file **must** export a `TurboModuleRegistrySpec` object. + +Example Specification file `NativeFancyMath.ts`: + +```ts +import type { TurboModule } from 'react-native/Libraries/TurboModule/RCTExport'; +import { TurboModuleRegistry } from 'react-native'; + +export interface Spec extends TurboModule { + getConstants() : { + E: number, + Pi: number, + }; + + add(a: number, b: number, callback: (value: number) => void) : void; +} + +export default TurboModuleRegistry.get( + 'FancyMath' +) as Spec | null; +``` + +> Note even through this file uses `TurboModuleRegistry`, Native Modules will still work with this JavaScript. The code is forward looking and will support Native Modules or TurboModules. + + + + +### Attributes + +| Attribute | Use | +| ----------------------- | --------------------------------------------------------- | +| `ReactModule` | Specifies the class is a native module. | +| `ReactMethod` | Specifies an asynchronous method. | +| `ReactSyncMethod` | Specifies a synchronous method. | +| `ReactConstant` | Specifies a field or property that represents a constant. | +| `ReactConstantProvider` | Specifies a method that provides a set of constants. | +| `ReactEvent` | Specifies a field or property that represents an event. | +| `ReactStruct` | Specifies a `struct` that can be used in native methods. | +| `ReactInit` | Specifies a class initialization module. | +| `ReactFunction` | Specifies a JavaScript function that you want exposed to your native code. | + + +### 3. Authoring your Native Module + +Here is a sample native module written in C# called `FancyMath`. It is a simple class that defines two numerical constants and a method 'add'. + +`FancyMath.cs`: + +```csharp +using System; +using Microsoft.ReactNative.Managed; + +namespace NativeModuleSample +{ + [ReactModule] + class FancyMath + { + [ReactConstant] + public double E = Math.E; + + [ReactConstant("Pi")] + public double PI = Math.PI; + + [ReactMethod("add")] + public double Add(double a, double b) + { + double result = a + b; + AddEvent(result); + return result; + } + + [ReactEvent] + public ReactEvent AddEvent { get; set; } + } +} +``` + +First off, you see that we're making use of the `Microsoft.ReactNative.Managed` shared library, which provides the easiest (and recommended) experience for authoring native modules. `Microsoft.ReactNative.Managed` provides the mechanism that discovers the native module annotations to build bindings at runtime. + +The `[ReactModule]` attribute says that the class is a React Native native module. It has an optional parameter for the module name visible to JavaScript and optionally the name of a registered event emitter. By default, the name visible to JavaScript is the same as the class name, and the default event emitter is `RCTDeviceEventEmitter`. + +You can overwrite the JavaScript module name like this: `[ReactModule("math")]`. + +You can specify a different event emitter like this: `[ReactModule(EventEmitter = "mathEmitter")]`. + +> NOTE: Using the default event emitter, `RCTDeviceEventEmitter`, all native event names must be **globally unique across all native modules** (even the ones built-in to RN). However, specifying your own event emitter means you'll need to create and register that too. This process is outlined in the [Native Modules and React Native Windows (Advanced Topics)](native-modules-advanced.md) document. + +The `[ReactConstant]` attribute is how you can define constants. Here `FancyMath` has defined two constants: `E` and `Pi`. When accessing these constants you should use `FancyMath.getConstants().E`. If you want to use another name in JS you could override the JS name like this: `[ReactConstant("e")]`. + +The `[ReactMethod]` attribute is how you define methods. In `FancyMath` we have one method, `add`, which takes two doubles and returns their sum. As before, you can optionally customize the name like this: `[ReactMethod("add")]`. + +The `[ReactEvent]` attribute is how you define events. In `FancyMath` we have one event, `AddEvent`, which uses the `ReactEvent` delegate, where the double represents the type of the event data. Now whenever we invoke the `AddEvent` delegate in our native code (as we do above), an event named `"AddEvent"` will be raised in JavaScript. As before, you could have optionally customized the name in JS like this: `[ReactEvent("addEvent")]`. + + +### 4. Registering your Native Module + +> IMPORTANT NOTE: When you create a new project via the CLI, the generated `ReactApplication` class will automatically register all native modules defined within the app. **You will not need to manually register native modules that are defined within your app's scope, as they will be registered automatically.** + +Now, we want to register our new `FancyMath` module with React Native so we can use it from JavaScript code. To do this, first we're going to create a `ReactPackageProvider` which implements [`Microsoft.ReactNative.IReactPackageProvider`](https://github.com/microsoft/react-native-windows/blob/main/vnext/Microsoft.ReactNative/IReactPackageProvider.idl). + +`ReactPackageProvider.cs`: + +```csharp +using Microsoft.ReactNative.Managed; + +namespace NativeModuleSample +{ + public sealed class ReactPackageProvider : IReactPackageProvider + { + public void CreatePackage(IReactPackageBuilder packageBuilder) + { + packageBuilder.AddAttributedModules(); + } + } +} +``` + +Here we've implemented the `CreatePackage` method, which receives `packageBuilder` to build contents of the package. Since we use reflection to discover and bind native module, we call `AddAttributedModules` extension method to register all native modules in our assembly that have the `ReactModule` attribute. + +Now that we have the `ReactPackageProvider`, it's time to register it within our `ReactApplication`. We do that by simply adding the provider to the `PackageProviders` property. + +`App.xaml.cs`: + +```csharp +using Microsoft.ReactNative; + +namespace SampleApp +{ + sealed partial class App : ReactApplication + { + public App() + { + /* Other Init Code */ + + PackageProviders.Add(new Microsoft.ReactNative.Managed.ReactPackageProvider()); // Includes any modules in this project + PackageProviders.Add(new NativeModuleSample.ReactPackageProvider()); + + /* Other Init Code */ + } + } +} +``` + +This example assumes that the `NativeModuleSample.ReactPackageProvider` we created above is in a different project (assembly) than our application. However you'll notice that by default we also added a `Microsoft.ReactNative.Managed.ReactPackageProvider`. + +The `Microsoft.ReactNative.Managed.ReactPackageProvider` is a convenience that makes sure that all native modules and view managers defined within the app project automatically get registered. So if you're creating your native modules directly within the app project, you won't actually want to define a separate `ReactPackageProvider`. + + + +### Attributes + +| Attribute | Use | +| ------------------------ | --------------------------------------------------------- | +| `REACT_MODULE` | Specifies the class is a native module, making this module recognizable by `AddAttributedModules` function. | +| `REACT_MODULE_NOREG` | Specifies the class is a native module. | +| `REACT_METHOD` | Specifies an asynchronous method. | +| `REACT_SYNC_METHOD` | Specifies a synchronous method. | +| `REACT_GET_CONSTANTS` | Specifies a method that provides a set of constants. (Preferred) | +| `REACT_CONSTANT` | Specifies a field or property that represents a constant. | +| `REACT_CONSTANTPROVIDER` | Specifies a method that provides a set of constants. | +| `REACT_EVENT` | Specifies a field or property that represents an event. | +| `REACT_STRUCT` | Specifies a `struct` that can be used in native methods (don't nest the definition inside `REACT_MODULE`). | +| `REACT_INIT` | Specifies a class initialization module. | +| `ReactFunction` | Specifies a JavaScript function that you want exposed to your native code. | + +### 3. Authoring your Native Module + +Here is a sample native module written in C++ called `FancyMath`. It is a simple class that defines two numerical constants and a method 'add'. + +`FancyMath.h`: + +```cpp +#pragma once + +#include "pch.h" + +#include // This file will be generated by the windows-codegen command from your js spec file + +#include +#define _USE_MATH_DEFINES +#include + +#include "NativeModules.h" + +namespace NativeModuleSample +{ + REACT_MODULE(FancyMath); + struct FancyMath + { + // The namespace here will align with the codegenConfig.windows.namespace property in your package.json + using ModuleSpec = YourAppCodegenNamespace::FancyMathSpec; + + REACT_GET_CONSTANTS(GetConstants) + SampleLibraryCodegen::FancyMathSpec_Constants GetConstants() noexcept { + SampleLibraryCodegen::FancyMathSpec_Constants constants; + constants.E = M_E; + constants.Pi = M_PI; + return constants; + } + + REACT_METHOD(Add, L"add"); + double Add(double a, double b) noexcept + { + double result = a + b; + AddEvent(result); + return result; + } + + REACT_EVENT(AddEvent); + std::function AddEvent; + }; +} +``` + +The `REACT_MODULE` macro-attribute says that the class is a React Native native module. It receives the class name as a first parameter. All other macro-attributes also receive their target as a first parameter. `REACT_MODULE` has an optional parameter for the module name visible to JavaScript and optionally the name of a registered event emitter. By default, the name visible to JavaScript is the same as the class name, and the default event emitter is `RCTDeviceEventEmitter`. + +It is important to specify the `ModuleSpec`. Defining `ModuleSpec` will enforce that your module defines the same methods as the JS spec file. + +> NOTE: Methods annotated with `REACT_METHOD` and friends must have the `noexcept` specifier, otherwise the program will not compile. Module authors should make sure all exceptions are handled inside the method. + +You can overwrite the JavaScript module name like this: `REACT_MODULE(FancyMath, L"math")`. + +You can specify a different event emitter like this: `REACT_MODULE(FancyMath, L"math", L"mathEmitter")`. + +> NOTE: Using the default event emitter, `RCTDeviceEventEmitter`, all native event names must be **globally unique across all native modules** (even the ones built-in to RN). However, specifying your own event emitter means you'll need to create and register that too. This process is outlined in the [Native Modules and React Native Windows (Advanced Topics)](native-modules-advanced.md) document. + +Then we define constants, this is done using the `REACT_GET_CONSTANTS` macro-attribute. In this case we are returning a struct which was defined using `REACT_STRUCT`. This generates code to automatically translate the struct into a `JSValueObject`. + +It's just as easy to add custom methods, by attributing a public method with `REACT_METHOD`. In `FancyMath` we have one method, `add`, which takes two doubles and returns their sum. Again, we've specified the optional `name` argument in the `REACT_METHOD` macro-attribute so in JS we call `add` instead of `Add`. + +Native modules do not have the ability to check that the parameter types and the number of parameters match between what's called from JavaScript and what the native code accepts. However, the framework will validate that the number of promises-like parameters match: if the JavaScript API is `async`, it will expect that there is one "promise-like" parameter in the native method implementation signature. + +A "promise-like" parameter is either: +- `React::ReactPromise` +- a callback function or functor. + +See [Using Asynchronous Windows APIs](native-modules-async.md). + +Here is an example of an `async` method that returns a string: + +```cpp + REACT_METHOD(GetString, L"getString"); + void GetString(React::ReactPromise&& result) noexcept + { + if (error) { + result.Reject("Failure"); + } else { + std::string text = DoSomething(); + result.Resolve(text); + } + } +``` + +This can be also tied in with C++/WinRT event handlers or `IAsyncOperation` like so: + +```cpp + REACT_METHOD(GetString, L"getString"); + void GetString(React::ReactPromise&& result) noexcept + { + if (error) { + result.Reject("Failure"); + } else { + something.Completed([result] (const auto& operation, const auto& status) { + // do error checking, e.g. status should be Completed + winrt::hstring result{operation.GetResults()}; + result.Resolve(winrt::to_string(result)); + }); + } + } +``` +See [JavaScript and Windows Runtime strings](#javascript-and-windows-runtime-strings) for more details. + +The [`JSValue`](native-modules-jsvalue.md) type can be used when the API returns a JavaScript objects or takes JavaScript objects as input parameters. + +Native modules will want to use `REACT_METHOD` instead of `REACT_SYNC_METHOD` since the latter precludes web debugging and has performance implications. When using web debugging you will see an exception that reads: +`Calling synchronous methods on native modules is not supported in Chrome. Consider providing alternative to expose this method in debug mode, e.g. by exposing constants ahead-of-time` +See: [`MessageQueue.js`](https://github.com/facebook/react-native/blob/e27d656ef370958c864b052123ec05579ac9fc01/Libraries/BatchedBridge/MessageQueue.js#L175). + +To add custom events, we attribute a `std::function` delegate with `REACT_EVENT`, where the double represents the type of the event data. Now whenever we invoke the `AddEvent` delegate in our native code (as we do above), an event named `"AddEvent"` will be raised in JavaScript. As before, you could have optionally customized the name in JS like this: `REACT_EVENT(AddEvent, "addEvent")`. + +### 4. Registering your Native Module + +> IMPORTANT NOTE: When you create a new project via the CLI, the generated `ReactApplication` class will automatically register all native modules defined within the app. **You will not need to manually register native modules that are defined within your app's scope, as they will be registered automatically.** + +Now, we want to register our new `FancyMath` module with React Native so we can use it from JavaScript code. To do this, first we're going to create a `ReactPackageProvider` which implements [`Microsoft.ReactNative.IReactPackageProvider`](https://github.com/microsoft/react-native-windows/blob/main/vnext/Microsoft.ReactNative/IReactPackageProvider.idl). It starts with defining an interface definition (`.idl`) file: + +`ReactPackageProvider.idl`: + +```c++ +namespace NativeModuleSample +{ + [webhosthidden] + [default_interface] + runtimeclass ReactPackageProvider : Microsoft.ReactNative.IReactPackageProvider + { + ReactPackageProvider(); + }; +} +``` + +After that we add the .h and .cpp files: + +`ReactPackageProvider.h`: + +```cpp +#pragma once + +#include "ReactPackageProvider.g.h" + +using namespace winrt::Microsoft::ReactNative; + +namespace winrt::NativeModuleSample::implementation +{ + struct ReactPackageProvider : ReactPackageProviderT + { + ReactPackageProvider() = default; + + void CreatePackage(IReactPackageBuilder const& packageBuilder) noexcept; + }; +} + +namespace winrt::NativeModuleSample::factory_implementation +{ + struct ReactPackageProvider : ReactPackageProviderT {}; +} +``` + +`ReactPackageProvider.cpp`: + +```cpp +#include "pch.h" +#include "ReactPackageProvider.h" +#include "ReactPackageProvider.g.cpp" + +#include + +// NOTE: You must include the headers of your native modules here in +// order for the AddAttributedModules call below to find them. +#include "FancyMath.h" + +namespace winrt::NativeModuleSample::implementation +{ + void ReactPackageProvider::CreatePackage(IReactPackageBuilder const& packageBuilder) noexcept + { + AddAttributedModules(packageBuilder, true); + } +} +``` + +If `REACT_MODULE_NOREG` is used instead of `REACT_MODULE`, `AddAttributedModules` will not register this module for you. Such module should be registered manually: +```cpp +packageBuilder.AddTurboModule(L"FancyMath", MakeModuleProvider()); +``` + +Here we've implemented the `CreatePackage` method, which receives `packageBuilder` to build contents of the package. Since we use macros and templates to discover and bind native module, we call `AddAttributedModules` function to register all native modules in our DLL that have the `REACT_MODULE` macro-attribute. Specifying true here will register all the native modules as TurboModules rather than Native Modules. This will avoid some additional serialization that happens with Native Module calls. If for some reason you need the modules to continue to run as Native Modules, you can specify false here. + +See [Native Modules vs Turbo Modules](native-modules-vs-turbo-modules.md) for more details on TurboModules. + + +Now that we have the `ReactPackageProvider`, it's time to register it within our `ReactApplication`. We do that by simply adding the provider to the `PackageProviders` property. + +`App.cpp`: + +```c++ +#include "pch.h" + +#include "App.h" +#include "ReactPackageProvider.h" + +#include "winrt/NativeModuleSample.h" + +namespace winrt::SampleApp::implementation { + +App::App() noexcept { + /* Other Init Code */ + + PackageProviders().Append(make()); // Includes all modules in this project + PackageProviders().Append(winrt::NativeModuleSample::ReactPackageProvider()); + + /* Other Init Code */ +} + +} // namespace winrt::SampleApp::implementation +``` + +This example assumes that the `NativeModuleSample::ReactPackageProvider` we created above is in a different project (assembly) than our application. However you'll notice that by default we also added a `SampleApp::ReactPackageProvider`. + +The `SampleApp::ReactPackageProvider` is a convenience that makes sure that all native modules and view managers defined within the app project automatically get registered. So if you're creating your native modules directly within the app project, you won't actually want to define a separate `ReactPackageProvider`. + + +### JavaScript and Windows Runtime strings +Note that JavaScript strings are UTF8 (i.e. `std::string`) but WinRT strings are UTF16 (i.e. `winrt::hstring` in C++/WinRT), so when inter-operating between JavaScript and WinRT APIs, you will need to convert between these two encodings. +See [String handling in C++/WinRT](https://docs.microsoft.com/en-us/windows/uwp/cpp-and-winrt-apis/strings), specifically [`winrt::to_string`](https://docs.microsoft.com/uwp/cpp-ref-for-winrt/to-string) and [`winrt::to_hstring`](https://docs.microsoft.com/uwp/cpp-ref-for-winrt/to-hstring). + + + +### 5. Using your Native Module in JS + +Now we have a Native Module which is registered with React Native Windows. How do we access it in JS? Here's a simple RN app: + +`NativeModuleSample.js`: + +```js +import React, { Component } from 'react'; +import { + AppRegistry, + Alert, + Text, + View, +} from 'react-native'; + +import FancyMath from './NativeFancyMath' +import { NativeEventEmitter } from 'react-native'; + +const FancyMathEventEmitter = new NativeEventEmitter(FancyMath); + +class NativeModuleSample extends Component { + + componentDidMount() { + // Subscribing to FancyMath.AddEvent + FancyMathEventEmitter.addListener('AddEvent', eventHandler, this); + } + + componentWillUnmount() { + // Unsubscribing from FancyMath.AddEvent + FancyMathEventEmitter.removeListener('AddEvent', eventHandler, this); + } + + eventHandler(result) { + console.log("Event was fired with: " + result); + } + + _onPressHandler() { + // Calling FancyMath.add method + FancyMath.add( + /* arg a */ FancyMath.getConstants().Pi, + /* arg b */ FancyMath.E, + /* callback */ function (result) { + Alert.alert( + 'FancyMath', + `FancyMath says ${FancyMath.getConstants().Pi} + ${FancyMath.getConstants().E} = ${result}`, + [{ text: 'OK' }], + {cancelable: false}); + }); + } + + render() { + return ( + + FancyMath says PI = {FancyMath.getConstants().Pi} + FancyMath says E = {FancyMath.getConstants().E} +