diff --git a/docs/getting-started.md b/docs/getting-started.md index c8546ad02..dca7a3a0e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -69,8 +69,6 @@ npx react-native init-windows --overwrite > **Note:** RNW templates contain a customized `metro.config.js` file, which is meant to merge cleanly into the default config provided by the standard React Native project template. If you are starting a new app, overwriting `metro.config.js` should have no impact. However, if you are adding Windows to an existing app with an already modified `metro.config.js` file, please make sure to back up and re-apply your modifications after adding RNW. -> **Note:** Previous versions of the RNW Getting Started steps recommend the use of the `react-native-windows-init` command, which is being phased out. For documentation of that command, 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. @@ -134,6 +132,3 @@ Follow these steps to build a version of your app that you can install or publis > 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/docs/native-api/EmitEventSetterDelegate-api-windows.md b/docs/native-api/EmitEventSetterDelegate-api-windows.md new file mode 100644 index 000000000..b540ee370 --- /dev/null +++ b/docs/native-api/EmitEventSetterDelegate-api-windows.md @@ -0,0 +1,18 @@ +--- +id: EmitEventSetterDelegate +title: EmitEventSetterDelegate +--- + +Kind: `delegate` + +A delegate gets the arguments for an event emit on a EventEmitter. + +## Invoke +void **`Invoke`**([`JSValueArgWriter`](JSValueArgWriter) argWriter) + + + + + +## Referenced by +- [`EventEmitterInitializerDelegate`](EventEmitterInitializerDelegate) diff --git a/docs/native-api/EventEmitterInitializerDelegate-api-windows.md b/docs/native-api/EventEmitterInitializerDelegate-api-windows.md new file mode 100644 index 000000000..0b6d67e45 --- /dev/null +++ b/docs/native-api/EventEmitterInitializerDelegate-api-windows.md @@ -0,0 +1,18 @@ +--- +id: EventEmitterInitializerDelegate +title: EventEmitterInitializerDelegate +--- + +Kind: `delegate` + +A delegate to call a turbo module EventEmitter. + +## Invoke +void **`Invoke`**([`EmitEventSetterDelegate`](EmitEventSetterDelegate) emitter) + + + + + +## Referenced by +- [`IReactModuleBuilder`](IReactModuleBuilder) diff --git a/docs/native-api/IReactModuleBuilder-api-windows.md b/docs/native-api/IReactModuleBuilder-api-windows.md index 868531ec0..832c0f952 100644 --- a/docs/native-api/IReactModuleBuilder-api-windows.md +++ b/docs/native-api/IReactModuleBuilder-api-windows.md @@ -20,6 +20,13 @@ Adds a constant provider method to define constants for the native module. See [ +### AddEventEmitter +void **`AddEventEmitter`**(string name, [`EventEmitterInitializerDelegate`](EventEmitterInitializerDelegate) emitter) + +Adds an EventEmitter to the turbo module. See [`EventEmitterInitializerDelegate`](EventEmitterInitializerDelegate). + + + ### AddInitializer void **`AddInitializer`**([`InitializerDelegate`](InitializerDelegate) initializer) diff --git a/docs/native-api/JSValueArgWriter-api-windows.md b/docs/native-api/JSValueArgWriter-api-windows.md index f522d21da..47d3c778f 100644 --- a/docs/native-api/JSValueArgWriter-api-windows.md +++ b/docs/native-api/JSValueArgWriter-api-windows.md @@ -16,6 +16,7 @@ void **`Invoke`**([`IJSValueWriter`](IJSValueWriter) writer) ## Referenced by +- [`EmitEventSetterDelegate`](EmitEventSetterDelegate) - [`IReactContext`](IReactContext) - [`ReactRootView`](ReactRootView) - [`ReactViewOptions`](ReactViewOptions) diff --git a/docs/native-api/index-api-windows.md b/docs/native-api/index-api-windows.md index 78c75d5a4..c3760474e 100644 --- a/docs/native-api/index-api-windows.md +++ b/docs/native-api/index-api-windows.md @@ -112,6 +112,8 @@ sidebar_label: Full reference - [`AccessibilityActionEventHandler`](AccessibilityActionEventHandler) - [`AccessibilityInvokeEventHandler`](AccessibilityInvokeEventHandler) - [`ConstantProviderDelegate`](ConstantProviderDelegate) +- [`EmitEventSetterDelegate`](EmitEventSetterDelegate) +- [`EventEmitterInitializerDelegate`](EventEmitterInitializerDelegate) - [`InitializerDelegate`](InitializerDelegate) - [`JSValueArgWriter`](JSValueArgWriter) - [`JsiByteArrayUser`](JsiByteArrayUser) diff --git a/website/.unbroken_exclusions b/website/.unbroken_exclusions index 28ffe9034..6823f2d8c 100644 --- a/website/.unbroken_exclusions +++ b/website/.unbroken_exclusions @@ -14,6 +14,7 @@ !versioned_docs/version-0.73/native-api/*-api-windows*.md !versioned_docs/version-0.74/native-api/*-api-windows*.md !versioned_docs/version-0.75/native-api/*-api-windows*.md +!versioned_docs/version-0.76/native-api/*-api-windows*.md # See Issue 410 File not found IReactContext while parsing versioned_docs/version-0.64/native-modules-advanced.md @@ -25,8 +26,24 @@ File not found IViewManagerCreateWithProperties while parsing versioned_docs/ver File not found native-api/IReactPackageProvider-api-windows.md while parsing versioned_docs/version-0.72/coreapp.md File not found native-api/IReactContext-api-windows.md while parsing versioned_docs/version-0.72/native-modules-advanced.md File not found native-api/ReactNativeHost-api-windows.md while parsing versioned_docs/version-0.72/native-modules-advanced.md +File not found IViewManagerCreateWithProperties while parsing versioned_docs/version-0.76/view-managers.md #fix-unbroken.js auto-generated do not edit this line or below +File not found autolink-windows-cli.md while parsing versioned_docs/version-0.76/getting-started.md +File not found getting-started.md while parsing versioned_docs/version-0.76/getting-started.md +File not found init-windows-cli.md while parsing versioned_docs/version-0.76/getting-started.md +File not found run-windows-cli.md while parsing versioned_docs/version-0.76/getting-started.md +File not found native-modules.md while parsing versioned_docs/version-0.76/getting-started.md +File not found rnw-dependencies.md while parsing versioned_docs/version-0.76/getting-started.md +File not found getting-started.md while parsing versioned_docs/version-0.76/new-architecture.md +File not found init-windows-cli.md while parsing versioned_docs/version-0.76/new-architecture.md +File not found getting-started.md while parsing versioned_docs/version-0.76/nuget.md +File not found init-windows-cli.md while parsing versioned_docs/version-0.76/nuget.md +File not found supported-community-modules.md while parsing versioned_docs/version-0.76/nuget.md +File not found getting-started.md while parsing versioned_docs/version-0.76/view-managers.md +File not found init-windows-cli.md while parsing versioned_docs/version-0.76/view-managers.md +File not found native-modules-setup.md while parsing versioned_docs/version-0.76/view-managers.md +File not found native-modules.md while parsing versioned_docs/version-0.76/view-managers.md File not found run-windows-cli.md while parsing versioned_docs/version-0.75/autolink-windows-cli.md File not found run-windows-cli.md while parsing versioned_docs/version-0.75/debugging-javascript.md File not found getting-started.md while parsing versioned_docs/version-0.75/getting-started.md diff --git a/website/pages/en/support.js b/website/pages/en/support.js index 90cffdc7b..0f4a52a5d 100644 --- a/website/pages/en/support.js +++ b/website/pages/en/support.js @@ -16,7 +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.75](https://www.npmjs.com/package/react-native-windows/v/latest) | [Active](#active-support) | 8/19/2024 | 8/19/2024 | *TBD* | *TBD* | +| [0.76](https://www.npmjs.com/package/react-native-windows/v/latest) | [Active](#active-support) | 11/11/2024 | 11/11/2024 | *TBD* | *TBD* | +| [0.75](https://www.npmjs.com/package/react-native-windows/v/v0.75-stable) | [Active](#active-support) | 8/19/2024 | 8/19/2024 | 12/31/2024 | 02/28/2025 | | [0.74](https://www.npmjs.com/package/react-native-windows/v/v0.74-stable) | [Maintenance](#maintenance-support) | 4/29/2024 | 4/29/2024 | 9/30/2024 | 11/30/2024 | | [0.73](https://www.npmjs.com/package/react-native-windows/v/v0.73-stable) | [Unsupported](#unsupported) | 12/11/2023 | 12/11/2023 | 5/31/2024 | 7/31/2024 | | [0.72](https://www.npmjs.com/package/react-native-windows/v/v0.72-stable) | [Unsupported](#unsupported) | 06/23/2023 | 06/23/2023 | 01/31/2024 | 03/31/2024 | diff --git a/website/siteConfig.js b/website/siteConfig.js index d55c71844..853dfcc52 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.75"; +const defaultVersionShown = "0.76"; const repoUrl = "https://github.com/microsoft/react-native-windows"; const siteConfig = { diff --git a/website/versioned_docs/version-0.74/getting-started.md b/website/versioned_docs/version-0.74/getting-started.md index d9f19ee39..b9362d4d3 100644 --- a/website/versioned_docs/version-0.74/getting-started.md +++ b/website/versioned_docs/version-0.74/getting-started.md @@ -24,7 +24,7 @@ Remember to call `@react-native-community/cli init` from the place you want your ```bat -npx --yes @react-native-community/cli@latest init --version "latest" +npx --yes @react-native-community/cli@latest init --version "0.74-stable" ``` ### Navigate into this newly created directory diff --git a/website/versioned_docs/version-0.75/getting-started.md b/website/versioned_docs/version-0.75/getting-started.md index 887f0d68a..790c89958 100644 --- a/website/versioned_docs/version-0.75/getting-started.md +++ b/website/versioned_docs/version-0.75/getting-started.md @@ -24,7 +24,7 @@ Remember to call `@react-native-community/cli init` from the place you want your ```bat -npx --yes @react-native-community/cli@next init --version "latest" +npx --yes @react-native-community/cli@latest init --version "0.75-stable" ``` ### Navigate into this newly created directory diff --git a/website/versioned_docs/version-0.76/getting-started.md b/website/versioned_docs/version-0.76/getting-started.md new file mode 100644 index 000000000..991326730 --- /dev/null +++ b/website/versioned_docs/version-0.76/getting-started.md @@ -0,0 +1,136 @@ +--- +id: version-0.76-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). + +> **Interested in migrating to [React Native's New Architecture](https://reactnative.dev/architecture/landing-page)?** New Architecture support in React Native for Windows is now available to preview in 0.76. Note there are several key changes, so if you’d like to be an early adopter, check out the information in the [New Architecture Guide](new-architecture.md). + +## Create a new React Native project + +Remember to call `@react-native-community/cli init` from the place you want your project directory to live. + + + + + + + + + + +```bat +npx --yes @react-native-community/cli@latest init --version "latest" +``` + +### Navigate into this newly created directory + +React Native will have created your project in a new sub-directory, which you must enter before continuing. + +```bat +cd +``` + +### Add React Native Windows to your project's dependencies + + + + + + + + + + +```bat +yarn add react-native-windows@^0.76.0 +``` + + + +```bat +npm install --save react-native-windows@^0.76.0 +``` + + + +### Initialize the React Native Windows native code and projects + +Lastly, initialize the React Native for Windows application with the [init-windows command](init-windows-cli.md): + +```bat +npx react-native init-windows --overwrite +``` + +> **Note:** RNW templates contain a customized `metro.config.js` file, which is meant to merge cleanly into the default config provided by the standard React Native project template. If you are starting a new app, overwriting `metro.config.js` should have no impact. However, if you are adding Windows to an existing app with an already modified `metro.config.js` file, please make sure to back up and re-apply your modifications after adding RNW. + +## 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 the [run-windows command](run-windows-cli.md): + + ```bat + npx react-native run-windows + ``` + + A new Command Prompt window will open with the React packager as well as your React Native for 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 [autolink-windows command](autolink-windows-cli.md), 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.76/native-api/EmitEventSetterDelegate-api-windows.md b/website/versioned_docs/version-0.76/native-api/EmitEventSetterDelegate-api-windows.md new file mode 100644 index 000000000..684414b09 --- /dev/null +++ b/website/versioned_docs/version-0.76/native-api/EmitEventSetterDelegate-api-windows.md @@ -0,0 +1,19 @@ +--- +id: version-0.76-EmitEventSetterDelegate +title: EmitEventSetterDelegate +original_id: EmitEventSetterDelegate +--- + +Kind: `delegate` + +A delegate gets the arguments for an event emit on a EventEmitter. + +## Invoke +void **`Invoke`**([`JSValueArgWriter`](JSValueArgWriter) argWriter) + + + + + +## Referenced by +- [`EventEmitterInitializerDelegate`](EventEmitterInitializerDelegate) diff --git a/website/versioned_docs/version-0.76/native-api/EventEmitterInitializerDelegate-api-windows.md b/website/versioned_docs/version-0.76/native-api/EventEmitterInitializerDelegate-api-windows.md new file mode 100644 index 000000000..861061936 --- /dev/null +++ b/website/versioned_docs/version-0.76/native-api/EventEmitterInitializerDelegate-api-windows.md @@ -0,0 +1,19 @@ +--- +id: version-0.76-EventEmitterInitializerDelegate +title: EventEmitterInitializerDelegate +original_id: EventEmitterInitializerDelegate +--- + +Kind: `delegate` + +A delegate to call a turbo module EventEmitter. + +## Invoke +void **`Invoke`**([`EmitEventSetterDelegate`](EmitEventSetterDelegate) emitter) + + + + + +## Referenced by +- [`IReactModuleBuilder`](IReactModuleBuilder) diff --git a/website/versioned_docs/version-0.76/native-api/IReactModuleBuilder-api-windows.md b/website/versioned_docs/version-0.76/native-api/IReactModuleBuilder-api-windows.md new file mode 100644 index 000000000..434a3248a --- /dev/null +++ b/website/versioned_docs/version-0.76/native-api/IReactModuleBuilder-api-windows.md @@ -0,0 +1,58 @@ +--- +id: version-0.76-IReactModuleBuilder +title: IReactModuleBuilder +original_id: IReactModuleBuilder +--- + +Kind: `interface` + + + +Builds native module inside of ReactNative code based on the provided meta-data. +See [Native Modules](native-modules) for more usage information. + + + +## Methods +### AddConstantProvider +void **`AddConstantProvider`**([`ConstantProviderDelegate`](ConstantProviderDelegate) constantProvider) + +Adds a constant provider method to define constants for the native module. See [`ConstantProviderDelegate`](ConstantProviderDelegate). + + + +### AddEventEmitter +void **`AddEventEmitter`**(string name, [`EventEmitterInitializerDelegate`](EventEmitterInitializerDelegate) emitter) + +Adds an EventEmitter to the turbo module. See [`EventEmitterInitializerDelegate`](EventEmitterInitializerDelegate). + + + +### AddInitializer +void **`AddInitializer`**([`InitializerDelegate`](InitializerDelegate) initializer) + +Adds an initializer method called on the native module initialization. +It provides the native module with the [`IReactContext`](IReactContext) for the running ReactNative instance. See [`InitializerDelegate`](InitializerDelegate). +There can be multiple initializer methods which are called in the order they were registered. + + + +### AddMethod +void **`AddMethod`**(string name, [`MethodReturnType`](MethodReturnType) returnType, [`MethodDelegate`](MethodDelegate) method) + +Adds an asynchronous method to the native module. See [`MethodDelegate`](MethodDelegate). + + + +### AddSyncMethod +void **`AddSyncMethod`**(string name, [`SyncMethodDelegate`](SyncMethodDelegate) method) + +Adds a synchronous method to the native module. See [`SyncMethodDelegate`](SyncMethodDelegate). + + + + + + +## Referenced by +- [`ReactModuleProvider`](ReactModuleProvider) diff --git a/website/versioned_docs/version-0.76/native-api/JSValueArgWriter-api-windows.md b/website/versioned_docs/version-0.76/native-api/JSValueArgWriter-api-windows.md new file mode 100644 index 000000000..6fa090853 --- /dev/null +++ b/website/versioned_docs/version-0.76/native-api/JSValueArgWriter-api-windows.md @@ -0,0 +1,25 @@ +--- +id: version-0.76-JSValueArgWriter +title: JSValueArgWriter +original_id: JSValueArgWriter +--- + +Kind: `delegate` + +The `JSValueArgWriter` delegate is used to pass values to ABI API. +In a function that implements the delegate use the provided `writer` to stream custom values. + +## Invoke +void **`Invoke`**([`IJSValueWriter`](IJSValueWriter) writer) + + + + + +## Referenced by +- [`EmitEventSetterDelegate`](EmitEventSetterDelegate) +- [`IReactContext`](IReactContext) +- [`ReactRootView`](ReactRootView) +- [`ReactViewOptions`](ReactViewOptions) +- [`XamlHelper`](XamlHelper) +- [`XamlUIService`](XamlUIService) diff --git a/website/versioned_docs/version-0.76/native-api/QuirkSettings-api-windows.md b/website/versioned_docs/version-0.76/native-api/QuirkSettings-api-windows.md new file mode 100644 index 000000000..1af617b08 --- /dev/null +++ b/website/versioned_docs/version-0.76/native-api/QuirkSettings-api-windows.md @@ -0,0 +1,88 @@ +--- +id: version-0.76-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.76/native-api/ReactPointerEventArgs-api-windows.md b/website/versioned_docs/version-0.76/native-api/ReactPointerEventArgs-api-windows.md new file mode 100644 index 000000000..d987cf4ca --- /dev/null +++ b/website/versioned_docs/version-0.76/native-api/ReactPointerEventArgs-api-windows.md @@ -0,0 +1,50 @@ +--- +id: version-0.76-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.76/native-api/index-api-windows.md b/website/versioned_docs/version-0.76/native-api/index-api-windows.md new file mode 100644 index 000000000..73dfc0220 --- /dev/null +++ b/website/versioned_docs/version-0.76/native-api/index-api-windows.md @@ -0,0 +1,132 @@ +--- +id: version-0.76-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) +- [`AriaRole`](AriaRole) +- [`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) +- [`ITimer`](ITimer) +- [`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) +- [`DevMenuControl`](DevMenuControl) +- [`DynamicAutomationPeer`](DynamicAutomationPeer) +- [`DynamicAutomationProperties`](DynamicAutomationProperties) +- [`DynamicValueProvider`](DynamicValueProvider) +- [`GaussianBlurEffect`](GaussianBlurEffect) +- [`HttpSettings`](HttpSettings) +- [`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) +- [`Timer`](Timer) +- [`ViewControl`](ViewControl) +- [`ViewPanel`](ViewPanel) +- [`XamlHelper`](XamlHelper) +- [`XamlMetaDataProvider`](XamlMetaDataProvider) +- [`XamlUIService`](XamlUIService) +## Delegates +- [`AccessibilityActionEventHandler`](AccessibilityActionEventHandler) +- [`AccessibilityInvokeEventHandler`](AccessibilityInvokeEventHandler) +- [`ConstantProviderDelegate`](ConstantProviderDelegate) +- [`EmitEventSetterDelegate`](EmitEventSetterDelegate) +- [`EventEmitterInitializerDelegate`](EventEmitterInitializerDelegate) +- [`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) +- [`TimerFactory`](TimerFactory) +- [`UIBatchCompleteCallback`](UIBatchCompleteCallback) diff --git a/website/versioned_docs/version-0.76/new-architecture.md b/website/versioned_docs/version-0.76/new-architecture.md new file mode 100644 index 000000000..a9c7ef732 --- /dev/null +++ b/website/versioned_docs/version-0.76/new-architecture.md @@ -0,0 +1,129 @@ +--- +id: version-0.76-new-architecture +title: New vs. Old Architecture +original_id: new-architecture +--- + +React Native's [New Architecture](https://reactnative.dev/architecture/landing-page) has become the default with [version 0.76](https://reactnative.dev/blog/2024/10/23/the-new-architecture-is-here), bringing many framework improvements including the advanced rendering system [Fabric](https://reactnative.dev/architecture/fabric-renderer). While React Native for Windows isn't quite yet ready to make the New Architecture the default, we've been hard at work and are excited to offer a sneak peek into adopting it on Windows. + +> **Important:** At this stage, React Native for Windows' New Architecture support comes with some important caveats, and is best suited for early adopters comfortable with a work-in-progress experience with incomplete documentation. For those willing to dive in, the New Architecture offers a glimpse into the exciting future of React Native Windows development. + +## From UWP to WinAppSDK + +On Windows, the implementation of the (Old Architecture) Paper render used the [Universal Windows Platform](https://learn.microsoft.com/en-us/windows/uwp/). To meet the requirements of the new Fabric renderer, the Windows implementation now uses the modern [Windows App SDK](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/). This evolution allows us to utilize the upstream React Native cross-platform rendering logic while also enabling us to better implement the Windows-specific platform code. + +This also means that all React Native for Windows New Architecture apps will now be Win32, WinAppSDK-based applications. This aligns with the current recommendations for Windows app development, providing React Native for Windows developers with greater access to the latest Windows' frameworks. + +All React Native for Windows Old Architecture apps will remain UWP applications. It is still possible and supported to create and maintain apps that target the Old Architecture and UWP (see the list of ["old" templates](init-windows-cli.md#templates) still available). + +However, understand that while there are no immediate plans to deprecate support for Old Architecture applications, almost all future investments are focused on the New Architecture, and as React Native eventually deprecates Old Architecture support, so too will React Native for Windows. We will provide clear migration guidance for apps once New Architecture support is better established. + +> **Important:** There are no plans to support New Architecture on UWP nor Old Architecture on WinAppSDK. Previous experimental features that enabled either scenario are not officially supported. + +For more information about the reasoning behind the change from UWP to WinAppSDK, see the [FAQ](#faq) below. + +## Creating a New Architecture application + +Starting a React Native Windows project with the new architecture is simple! Follow the steps outlined in our [Getting Started](getting-started.md) guide, but make sure to use a [New Architecture template](init-windows-cli.md#templates) when initializing your project with init-windows. + +For example, if you previously set up a project using the Old Architecture, you might have used a command like this: + +```bat +yarn react-native init-windows --overwrite +``` + +To create a project with the New Architecture, use the same command but ensure you're specifying a New Architecture template, such as `cpp-app`: + +```bat +yarn react-native init-windows --template cpp-app --overwrite +``` + +> **Note:** There are only two supported New Architecture templates available at this time: `cpp-app` and `cpp-lib`. + +## Development Status + +### The Good Stuff + +Starting with this New Architecture Preview, it is now possible to create a New Architecture application by following the steps above and using the new `cpp-app` template. Developers should expect that the vast majority of core components, APIs, and functionality in React Native (i.e. from the `react-native` package) are already available in React Native for Windows. + +In terms of build developer experience, be sure to look out for drastically improved build speeds and reduced dev machine requirements as we default to using pre-built binaries for New Architecture projects. + +### The Not-So-Good Stuff + +However there are still some important gaps, especially with respect to community module support. First off, community modules that provide UI components by implementing new UI (i.e. via the Paper `IViewManager` interfaces) will not work with New Architecture apps. Those modules will need to implement new Fabric `ComponentView`s, and while technically possible, the experience is not quite ready for wide adoption. + +The story is better for non-UI community modules. Some purely non-UI community modules, built to target the existing Old Architecture apps, may still work "out-of-the-box" with your New Architecture apps. But due to the varied state of Windows support in community modules, you may find that even some of those non-UI modules will need updating. + +> **Note:** We do have a new library template, `cpp-lib`, which can be used to build non-UI community modules targeting the New Architecture. There are even accommodations within that template to continue to support Old Architecture apps simultaneously with one codebase. However, the template does not yet contain any examples for implementing custom UI for either architecture. The goal will be a single library template that supports both Old and New, UI and non-UI, with examples, but it isn't ready yet. + +### Remaining Work + +Our work on React Native Windows' New Architecture follows a series of milestones designed to guide our development priorities. Currently, our focus is on enabling community modules alongside full API parity and improving accessibility features. + +To track real-time progress and specific milestones, visit our [New Architecture for React Native for Windows Issue](https://github.com/microsoft/react-native-windows/issues/12042). This page is regularly updated with our latest development goals, roadmap items, and areas we’re actively working on. We encourage developers to check there for the latest on what’s available, what’s in progress, and what’s coming next. + +## React Native Component Parity + +The New Architecture introduces the most significant updates in how UI is rendered. By moving from UWP to the WinAppSDK, we gain the flexibility to implement components that weren't previously available while also reducing the parity gap for existing components. + +Perhaps the most notable change is we're finally implementing React Native's [`Modal`](https://reactnative.dev/docs/modal), thereby removing the necessity of using the Windows-only[`Flyout`](https://microsoft.github.io/react-native-windows/docs/flyout-component) or [`Popup`](https://microsoft.github.io/react-native-windows/docs/popup-component) components. + +Below you'll find a list of components we plan to support in the New Architecture. + +### Supported Components + +The plan is to support all React Native core host components in React Native for Windows. Each component below links to the corresponding issue label in our GitHub repo that tracks the progress of its parity with the New Architecture: + +- [View](https://github.com/microsoft/react-native-windows/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Area%3A%20View%22%20%20label%3A%22Workstream%3A%20Component%20Parity%22%20label%3A%22Area%3A%20Fabric%22%20) +- [Text](https://github.com/microsoft/react-native-windows/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Area%3A%20Text%22%20%20label%3A%22Workstream%3A%20Component%20Parity%22%20label%3A%22Area%3A%20Fabric%22%20) +- [Image](https://github.com/microsoft/react-native-windows/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Area%3A%20Image%22%20%20label%3A%22Workstream%3A%20Component%20Parity%22%20label%3A%22Area%3A%20Fabric%22%20) +- [TextInput](https://github.com/microsoft/react-native-windows/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Area%3A%20TextInput%22%20%20label%3A%22Workstream%3A%20Component%20Parity%22%20label%3A%22Area%3A%20Fabric%22%20) +- [ScrollView](https://github.com/microsoft/react-native-windows/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Area%3A%20ScrollView%22%20%20label%3A%22Workstream%3A%20Component%20Parity%22%20label%3A%22Area%3A%20Fabric%22%20) +- [Modal](https://github.com/microsoft/react-native-windows/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Area%3A%20Modal%22%20%20label%3A%22Workstream%3A%20Component%20Parity%22%20label%3A%22Area%3A%20Fabric%22&page=1) +- [ActivityIndicator](https://github.com/microsoft/react-native-windows/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Area%3A%20ActivityIndicator%22%20%20label%3A%22Workstream%3A%20Component%20Parity%22%20label%3A%22Area%3A%20Fabric%22%20) +- [Switch](https://github.com/microsoft/react-native-windows/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Area%3A%20Switch%22%20%20label%3A%22Workstream%3A%20Component%20Parity%22%20label%3A%22Area%3A%20Fabric%22%20) +- [RefreshControl](https://github.com/microsoft/react-native-windows/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Area%3A%20RefreshControl%22%20%20label%3A%22Workstream%3A%20Component%20Parity%22%20label%3A%22Area%3A%20Fabric%22%20) + +### Unsupported Components + +The following components were created and included in React Native for Windows Old Architecture in order to tackle the unique compatibility problems posed by using UWP XAML. There is no plan to include built-in support for these Windows-specific components within React Native for Windows (though they may possibly be supported by future community modules). + +- [Flyout](https://github.com/microsoft/react-native-windows/issues/11921) +- [Popup](https://github.com/microsoft/react-native-windows/issues/11921) +- [Glyph](https://github.com/microsoft/react-native-windows/issues/11961) + +## Send us your Feedback + +You're sure to encounter some bumps, challenges and rough edges with trying out the New Architecture. We've already logged many issues tracking properties and features that are on our to-do list, but if you come across significant concerns that aren't yet covered, please [open an issue](https://github.com/microsoft/react-native-windows/issues/new/choose) in the react-native-windows repo. You can also leave comments on [existing issues](https://github.com/microsoft/react-native-windows/issues) to help us prioritize what to tackle first! + +## FAQ + +### Why the change from UWP to Windows App SDK? + +For years, React Native for Windows has built Windows apps using the [Universal Windows Platform](https://learn.microsoft.com/en-us/windows/uwp/) and its [XAML](https://learn.microsoft.com/en-us/windows/uwp/xaml-platform/xaml-overview) technologies. + +However, this implementation has never been perfect. UWP XAML has its own expectations and limitations with rendering UI, which has often come into conflict with React Native's expectations. This has always generated a certain class of issues that simply couldn't be solved by React Native for Windows. + +Furthermore, many requirements of the New Architecture, particularly the faster, more polished UI enabled by the Fabric renderer, would not be possible without extensive, fundamental changes to UWP XAML. + +Now, the current recommendation for new Windows apps is to build using the [Windows App SDK](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/). There are many benefits for Windows developers to migrate their apps off UWP and onto the Windows App SDK. Most importantly for React Native for Windows, the Windows App SDK gives us the tools to implement the New Architecture properly. + +### Why the change from XAML to Composition? + +It is not always possible to adapt the XAML framework, let alone specific controls, to meet the API requirements and expectations of React Native. However, thanks to the Windows App SDK, we're now able to "drop down" and use the layer of UI primitives under XAML, aka Composition, or the [Windows App SDK Scene Graph](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/composition). + +So now, instead of trying to implement React Native components with XAML controls (and perhaps fight their default behavior) we're now able to implement those components more directly in Composition, giving us the power to align with React Native's expectations rather than XAML's. + +## What if I still need/want XAML controls? + +We understand that customers may still want to use XAML controls (whether it's any of the rich controls included with Windows App SDK's WinUI 3, or any of their own existing custom controls) within their React Native for Windows app's UI. + +We are actively working on enabling this, but it's not quite production ready yet. We fully expect to support that developers, especially community module developers, will be able to implement New Architecture `ComponentView`s by loading XAML controls, rather than requiring them to implement the controls "from scratch" using the base Composition APIs. + +## What about C# support? + +We are actively working on adding support for C# app and module developers. The transition from UWP C# to modern .NET C# requires some more extensive project changes than was required for supporting C++. + +## Will the Old Architecture ever support targeting Windows App SDK? + +No. Then plan is, Old Architecture targets UWP, New Architecture targets Windows App SDK. diff --git a/website/versioned_docs/version-0.76/nuget.md b/website/versioned_docs/version-0.76/nuget.md new file mode 100644 index 000000000..0c342b0d2 --- /dev/null +++ b/website/versioned_docs/version-0.76/nuget.md @@ -0,0 +1,19 @@ +--- +id: version-0.76-NuGet +title: Using Microsoft.ReactNative NuGet packages +original_id: NuGet +--- + +>**This documentation and the underlying platform code is a work in progress.** + +Traditionally, the default for React Native Windows has been to build all code from source. This includes building all the code shipped by the team in the npm package from source. The amount of code is quite large and takes both a long time to build as well as requiring a high-performance computer. Some configurations have problems building this code with only 8 GB of memory. Especially if you are used to working only with managed code, this can be a big surprise. + +Starting with the (currently experimental) New Architecture (i.e. Fabric) app and module projects, React Native Windows will default to consuming pre-built binary NuGet packages instead of requiring you to compile everything yourself. + +The benefit of using NuGet packages is that you get improved compilation times for your Windows project and can develop on a less powerful computer. This will also translate into a smoother update experience for newer versions of `react-native-windows`. + +When creating a new project in [Get Started with Windows](getting-started.md), the type of template selected for the [init-windows command](init-windows-cli.md) will determine whether or not the project will built against the `react-native-windows` source or the pre-built NuGet packages. + +> **Note on new projects:** Building from source will remain the default for new Old Architecture projects. This is because there are known compatibility issues with [community modules](supported-community-modules.md), as they often still rely on building the shared code from source, making the parallel use of NuGets problematic. + +> **Note on existing projects:** Previously exposed methods for building Old Architecture projects against NuGets were experimental and are being deprecated, and therefore should not be used. If you're in the process of upgrading an existing Old Architecture project that *did* use those experimental methods, the [init-windows command](init-windows-cli.md) will try to respect that setting until the methods are formally deprecated and removed. diff --git a/website/versioned_docs/version-0.76/view-managers.md b/website/versioned_docs/version-0.76/view-managers.md new file mode 100644 index 000000000..ddbce5c8d --- /dev/null +++ b/website/versioned_docs/version-0.76/view-managers.md @@ -0,0 +1,671 @@ +--- +id: version-0.76-view-managers +title: Native UI Components +original_id: view-managers +--- + +> **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) + +There are tons of native UI widgets out there ready to be used in the latest apps - some of them are part of the platform, others are available as third-party libraries, and still more might be in use in your very own portfolio. React Native has several of the most critical platform components already wrapped, like `ScrollView` and `TextInput`, but not all of them, and certainly not ones you might have written yourself for a previous app. Fortunately, we can wrap up these existing components for seamless integration with your React Native application. + +Like the [native module guide](native-modules.md), this too is a more advanced guide that assumes you are somewhat familiar with UWP programming. This guide will show you how to build a native UI component, walking you through the implementation of a subset of the existing `ImageView` component available in the core React Native library. + +## Overview + +Similarly to authoring native modules, at a high level you must: + +1. Author a view manager which defines a new Component type and understands how to create and interact with the native UI widget. +2. Register your new view manager within the native code of your React Native host application. +3. Reference the new component within your React Native JSX code. + +### Note about UWP XAML controls +Some UWP XAML controls do not support being hosted in environments where 3D transforms are involved (i.e. the [`Transform3D`](https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.uielement.transform3d) property is set on the control or on any of the control's ancestors in the XAML tree). + +Currently, React Native for Windows uses a global `PerspectiveTransform` to provide a 3D look to objects being rotated along the `x` or `y` axes, which means these controls that do not work in 3D environments, will not work out of the box (e.g. [`InkCanvas`](https://docs.microsoft.com/en-us/uwp/api/Windows.UI.Xaml.Controls.InkCanvas)). However, a React Native for Windows app can opt out of the 3D perspective (and in so doing, enable using these controls) by setting the [`IsPerspectiveEnabled`](https://github.com/microsoft/react-native-windows/blob/4e775b9a59c55996d7598aadaeb82c93c40cbb6f/vnext/Microsoft.ReactNative/ReactRootView.idl#L18) property on the `ReactRootView`. + +__Important__: The `IsPerspectiveEnabled` property is experimental and support for it may be removed in the future. + +## Initial Setup + +Prerequisite: 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. + +If you are only planning on adding a native module to your existing React Native Windows app, i.e.: + +1. You followed [Getting Started](getting-started.md), where +1. You used the [init-windows command](init-windows-cli.md) to add Windows to your project, and +1. You are just adding your native code to the app project under the `windows` folder. + +Then you can simply open the Visual Studio solution in the `windows` folder and add the new files directly to the app project. + +If you are instead creating a standalone native module, or adding Windows support to an existing native module, check out the [Native Modules Setup](native-modules-setup.md) guide first. + +## Sample view manager + + + + +### Attributes + +| Attribute | Use | +| --------------------------------- | --------------------------------------------------------------------------------------- | +| `ViewManagerExportedViewConstant` | Specifies a field or property that represents a constant. | +| `ViewManagerProperty` | Specifies a method to be called to set a property on an instance of a native UI widget. | +| `ViewManagerCommand` | Specifies a method that can be called on an instance of a native UI widget. | + +For this sample, assume we have the following `CustomUserControl` that we want to use in React Native. + +`CustomUserControl.cs`: + +```csharp +using Windows.UI.Xaml; +using Windows.UI.Xaml.Controls; + +namespace ViewManagerSample +{ + public sealed class CustomUserControl : Control + { + public static DependencyProperty LabelProperty { get; private set; } + + public string Label + { + get + { + return (string)GetValue(LabelProperty); + } + set + { + SetValue(LabelProperty, value); + } + } + + static CustomUserControl() + { + LabelProperty = DependencyProperty.Register( + nameof(Label), + typeof(string), + typeof(CustomUserControl), + new PropertyMetadata(default(string)) + ); + } + + public CustomUserControl() + { + DefaultStyleKey = typeof(CustomUserControl); + } + } +} +``` + +```xml + + + + +``` + +### 1. Authoring your View Manager + +Here is a sample view manager written in C# called `CustomUserControlViewManager`. + +`CustomUserControlViewManager.cs`: + +```csharp +using Windows.UI.Xaml.Media; +using Windows.UI.Xaml.Controls; + +using Microsoft.ReactNative.Managed; +using System.Collections.Generic; + +namespace ViewManagerSample +{ + internal class CustomUserControlViewManager : AttributedViewManager + { + [ViewManagerProperty("label")] + public void SetLabel(CustomUserControl view, string value) + { + if (null != value) + { + view.Label = value; + } + else + { + view.ClearValue(CustomUserControl.LabelProperty); + } + } + + [ViewManagerProperty("color")] + public void SetColor(CustomUserControl view, Brush value) + { + if (null != value) + { + view.Foreground = value; + } + else + { + view.ClearValue(Control.ForegroundProperty); + } + } + + [ViewManagerProperty("backgroundColor")] + public void SetBackgroundColor(CustomUserControl view, Brush value) + { + if (null != value) + { + view.Background = value; + } + else + { + view.ClearValue(Control.BackgroundProperty); + } + } + + [ViewManagerCommand] + public void CustomCommand(CustomUserControl view, IReadOnlyList commandArgs) + { + // Execute command + } + } +} +``` + +### 2. Registering your View Manager + +As with native modules, we want to register our new `CustomUserControlViewManager` with React Native so we can actually use it. 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 ViewManagerSample +{ + public partial class ReactPackageProvider : IReactPackageProvider + { + public void CreatePackage(IReactPackageBuilder packageBuilder) + { + CreatePackageImplementation(packageBuilder); + } + + /// + /// This method is implemented by the C# code generator + /// + partial void CreatePackageImplementation(IReactPackageBuilder packageBuilder); + } +} +``` + +Here we've implemented the `CreatePackage` method, which receives `packageBuilder` to build contents of the package. + +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 ViewManagerSample.ReactPackageProvider()); + + /* Other Init Code */ + } + } +} +``` + +This example assumes that the `ViewManagerSample.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 view managers directly within the app project, you won't actually want to define a separate `ReactPackageProvider`. + +### More extensibility points + +- In some scenarios, a view manager might need to have more context at view creation time in order to decide what kind of control to instantiate. +This can be achieved by having the view manager implement the [`IViewManagerCreateWithProperties`](IViewManagerCreateWithProperties) interface. The `CreateViewWithProperties` method can then access the properties set in JSX by inspecting the `propertyMapReader`. + +```diff +-internal class CustomUserControlViewManager : AttributedViewManager { ++internal class CustomUserControlViewManager : AttributedViewManager, IViewManagerCreateWithProperties { +// rest of the view manager goes here... ++ // IViewManagerCreateWithProperties ++ public virtual object CreateViewWithProperties(Microsoft.ReactNative.IJSValueReader propertyMapReader) { ++ propertyMapReader.ReaderValue(out IDictionary propertyMap); ++ // create a XAML FrameworkElement based on properties in propertyMap ++ if (propertyMap.ContainsKey("foo)) { ++ return new Button(); ++ } else { ++ return new TextBox(); ++ } ++ } +} ++} +``` + +- Your view manager is also able to declare that it wants to be responsible for its own sizing and layout. +This is useful in scenarios where you are wrapping a native XAML control. To do so, implement the `Microsoft.ReactNative.IViewManagerRequiresNativeLayout` interface: + +```diff +-internal class CustomUserControlViewManager : AttributedViewManager { ++internal class CustomUserControlViewManager : AttributedViewManager, IViewManagerRequiresNativeLayout { +// rest of the view manager goes here... ++ // IViewManagerRequiresNativeLayout ++ virtual bool RequiresNativeLayout() { return true; } +``` + + +For this sample, assume we already have the `CustomUserControl` defined in the C# example. + +### 1. Authoring your View Manager + +Here is a sample view manager written in C++ called `CustomUserControlViewManager`. + +`CustomUserControlViewManager.h`: + +```cpp +#pragma once + +#include "pch.h" + +#include "winrt/Microsoft.ReactNative.h" + +namespace winrt::ViewManagerSample::implementation { + +struct CustomUserControlViewManager : winrt::implements< + CustomUserControlViewManager, + winrt::Microsoft::ReactNative::IViewManager, + winrt::Microsoft::ReactNative::IViewManagerWithNativeProperties, + winrt::Microsoft::ReactNative::IViewManagerWithCommands, + winrt::Microsoft::ReactNative::IViewManagerWithExportedEventTypeConstants, + winrt::Microsoft::ReactNative::IViewManagerWithReactContext> { + public: + CustomUserControlViewManager() = default; + + // IViewManager + winrt::hstring Name() noexcept; + + winrt::Windows::UI::Xaml::FrameworkElement CreateView() noexcept; + + // IViewManagerWithNativeProperties + winrt::Windows::Foundation::Collections:: + IMapView + NativeProps() noexcept; + + void UpdateProperties( + winrt::Windows::UI::Xaml::FrameworkElement const &view, + winrt::Microsoft::ReactNative::IJSValueReader const &propertyMapReader) noexcept; + + // IViewManagerWithCommands + winrt::Windows::Foundation::Collections::IVectorView Commands() noexcept; + + void DispatchCommand( + winrt::Windows::UI::Xaml::FrameworkElement const &view, + winrt::hstring const &commandId, + winrt::Microsoft::ReactNative::IJSValueReader const &commandArgsReader) noexcept; + + // IViewManagerWithExportedEventTypeConstants + winrt::Microsoft::ReactNative::ConstantProviderDelegate ExportedCustomBubblingEventTypeConstants() noexcept; + + winrt::Microsoft::ReactNative::ConstantProviderDelegate ExportedCustomDirectEventTypeConstants() noexcept; + + // IViewManagerWithReactContext + winrt::Microsoft::ReactNative::IReactContext ReactContext() noexcept; + + void ReactContext(winrt::Microsoft::ReactNative::IReactContext reactContext) noexcept; + +private: + winrt::Microsoft::ReactNative::IReactContext m_reactContext{ nullptr }; +}; + +} +``` + +`CustomUserControlViewManager.cpp`: + +```cpp +#include "pch.h" +#include "CustomUserControlViewManager.h" + +#include "JSValueReader.h" +#include "JSValueXaml.h" +#include "NativeModules.h" + +using namespace winrt; +using namespace Microsoft::ReactNative; +using namespace Windows::Foundation; +using namespace Windows::Foundation::Collections; + +using namespace Windows::UI::Xaml; +using namespace Windows::UI::Xaml::Media; +using namespace Windows::UI::Xaml::Controls; + +namespace winrt::ViewManagerSample::implementation { + +// IViewManager +hstring CustomUserControlViewManager::Name() noexcept { + return L"CustomUserControl"; +} + +FrameworkElement CustomUserControlViewManager::CreateView() noexcept { + return winrt::ViewManagerSample::CustomUserControl(); +} + +// IViewManagerWithNativeProperties +IMapView CustomUserControlViewManager::NativeProps() noexcept { + auto nativeProps = winrt::single_threaded_map(); + + nativeProps.Insert(L"label", ViewManagerPropertyType::String); + nativeProps.Insert(L"color", ViewManagerPropertyType::Color); + nativeProps.Insert(L"backgroundColor", ViewManagerPropertyType::Color); + + return nativeProps.GetView(); +} + +void CustomUserControlViewManager::UpdateProperties( + FrameworkElement const &view, + IJSValueReader const &propertyMapReader) noexcept { + if (auto control = view.try_as()) { + + const JSValueObject &propertyMap = JSValue::ReadObjectFrom(propertyMapReader); + + for (auto const &pair : propertyMap) { + auto const &propertyName = pair.first; + auto const &propertyValue = pair.second; + + if (propertyName == "label") { + if (propertyValue != nullptr) { + auto const &value = winrt::box_value(winrt::to_hstring(propertyValue.String())); + control.Label(value); + } else { + control.ClearValue(winrt::ViewManagerSample::CustomUserControl::LabelProperty()); + } + } else if (propertyName == "color") { + if (auto value = propertyValue.To()) { + control.Foreground(value); + } else { + control.ClearValue(Control::ForegroundProperty()); + } + } else if (propertyName == "backgroundColor") { + if (auto value = propertyValue.To()) { + control.Background(value); + } else { + control.ClearValue(Control::BackgroundProperty()); + } + } + } + } +} + +// IViewManagerWithCommands +IVectorView CustomUserControlViewManager::Commands() noexcept { + auto commands = winrt::single_threaded_vector(); + commands.Append(L"CustomCommand"); + return commands.GetView(); +} + +void CustomUserControlViewManager::DispatchCommand( + FrameworkElement const &view, + winrt::hstring const &commandId, + winrt::Microsoft::ReactNative::IJSValueReader const &commandArgsReader) noexcept { + if (auto control = view.try_as()) { + if (commandId == L"CustomCommand") { + const JSValueArray &commandArgs = JSValue::ReadArrayFrom(commandArgsReader); + // Execute command + } + } +} + +// IViewManagerWithExportedEventTypeConstants +ConstantProviderDelegate CustomUserControlViewManager::ExportedCustomBubblingEventTypeConstants() noexcept { + return [](winrt::Microsoft::ReactNative::IJSValueWriter const& constantWriter) { + // use constantWriter to define bubbling events, see ExportedCustomDirectEventTypeConstants + } +} + +ConstantProviderDelegate CustomUserControlViewManager::ExportedCustomDirectEventTypeConstants() noexcept { + return [](winrt::Microsoft::ReactNative::IJSValueWriter const& constantWriter) { + constantWriter.WritePropertyName(L"topMyEvent"); + constantWriter.WriteObjectBegin(); + WriteProperty(constantWriter, L"registrationName", L"onMyEvent"); + constantWriter.WriteObjectEnd(); + }; +} + +// IViewManagerWithReactContext +IReactContext CustomUserControlViewManager::ReactContext() noexcept { + return m_reactContext; +} + +void CustomUserControlViewManager::ReactContext(IReactContext reactContext) noexcept { + m_reactContext = reactContext; +} + +} +``` + + +### More extensibility points + +- In some scenarios, a view manager might need to have more context at view creation time in order to decide what kind of control to instantiate. +This can be achieved by having the view manager implement the [`IViewManagerCreateWithProperties`](IViewManagerCreateWithProperties) interface: +```diff +struct CustomUserControlViewManager : winrt::implements< + CustomUserControlViewManager, + winrt::Microsoft::ReactNative::IViewManager, + winrt::Microsoft::ReactNative::IViewManagerWithNativeProperties, + winrt::Microsoft::ReactNative::IViewManagerWithCommands, + winrt::Microsoft::ReactNative::IViewManagerWithExportedEventTypeConstants, ++ winrt::Microsoft::ReactNative::IViewManagerCreateWithProperties, + winrt::Microsoft::ReactNative::IViewManagerWithReactContext> { ++ // IViewManagerCreateWithProperties ++ winrt::Windows::Foundation::IInspectable CreateViewWithProperties(winrt::Microsoft::ReactNative::IJSValueReader const &propertyMapReader); +``` +The `CreateViewWithProperties` method can then access the properties set in JSX by inspecting the `propertyMapReader` just like it is done in the `UpdateProperties` method. + + +- Your view manager is also able to declare that it wants to be responsible for its own sizing and layout. This is useful in scenarios where you are wrapping a native XAML control. To do so, implement the `winrt::Microsoft::ReactNative::IViewManagerRequiresNativeLayout` interface: + +```diff +struct CustomUserControlViewManager : winrt::implements< + CustomUserControlViewManager, + winrt::Microsoft::ReactNative::IViewManager, + winrt::Microsoft::ReactNative::IViewManagerWithNativeProperties, + winrt::Microsoft::ReactNative::IViewManagerWithCommands, + winrt::Microsoft::ReactNative::IViewManagerWithExportedEventTypeConstants, ++ winrt::Microsoft::ReactNative::IViewManagerRequiresNativeLayout, + winrt::Microsoft::ReactNative::IViewManagerWithReactContext> { ++ // IViewManagerRequiresNativeLayout ++ bool RequiresNativeLayout() { return true; } +``` + + +### 2. Registering your View Manager + +As with native modules, we want to register our new `CustomUserControlViewManager` with React Native so we can actually use it. 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.idl`: + +```cpp +namespace ViewManagerSample +{ + [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::ViewManagerSample::implementation +{ + struct ReactPackageProvider : ReactPackageProviderT + { + ReactPackageProvider() = default; + + void CreatePackage(IReactPackageBuilder const& packageBuilder) noexcept; + }; +} + +namespace winrt::ViewManagerSample::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 "CustomUserControlViewManager.h" + +using namespace winrt::Microsoft::ReactNative; + +namespace winrt::ViewManagerSample::implementation { + +void ReactPackageProvider::CreatePackage(IReactPackageBuilder const& packageBuilder) +noexcept { + packageBuilder.AddViewManager( + L"CustomUserControlViewManager", []() { return winrt::make(); }); +} + +} // namespace winrt::ViewManagerSample::implementation +``` + +Here we've implemented the `CreatePackage` method, which receives `packageBuilder` to build contents of the package. And then we call `AddViewManager` with the name of our view manager and a lambda which returns an instance of the view manager. + +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`: + +```cpp +#include "pch.h" + +#include "App.h" +#include "ReactPackageProvider.h" + +#include "winrt/ViewManagerSample.h" + +namespace winrt::SampleApp::implementation { + +App::App() noexcept { + /* Other Init Code */ + + PackageProviders().Append(make()); // Includes all modules in this project + PackageProviders().Append(winrt::ViewManagerSample::ReactPackageProvider()); + + /* Other Init Code */ +} + +} // namespace winrt::SampleApp::implementation +``` + +This example assumes that the `ViewManagerSample::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`. + + + +### 3. Using your View Manager in JSX + +`ViewManagerSample.js`: + +```js +import React, { Component } from 'react'; +import { + AppRegistry, + Button, + requireNativeComponent, + StyleSheet, + UIManager, + View, +} from 'react-native'; + +let CustomUserControl = requireNativeComponent('CustomUserControl'); + +class ViewManagerSample extends Component { + onPress() { + if (_customControlRef) { + const tag = findNodeHandle(this._customControlRef); + UIManager.dispatchViewManagerCommand(tag, + UIManager.getViewManagerConfig('CustomUserControl').Commands.CustomCommand, + ['arg1', 'arg2']); + } + } + + render() { + return ( + + { this._customControlRef = ref; }} /> +