In this article, we will discuss how to enable your app to show toast notifications, which you can use to notify the user that something needs their attention, or to notify them that a long running operation has completed.<\/p>\n
This article assumes you have some familiarity with React Native for Windows native modules. If you need a refresher, check out the native modules documentation<\/a>.<\/p>\n The Windows toast notification API is fairly rich: it includes a number of UI templates<\/em> that an app can use to customize how it wants the notification to look.\nSome templates include text only, while others include text and images. Every template has some combination of these. You can see a list of the available templates here<\/a>.<\/p>\n We will create a native module which will have a single method, For the purpose of our demo, we will add a native module directly to a C++\/WinRT example app. If you prefer, you can follow the steps below and apply them to a separate native module project. Note that you can also use C# to write native modules in a similar manner. For more information about choosing between C++\/WinRT and C#, see Native code language choice<\/a>.\nWe will start with our standard native module setup, by adding a Then in our app’s In our JavaScript ( So now we have the basic setup, and you can set a breakpoint in the C++ code and validate that clicking on the button breaks into the C++ Note that it is necessary to convert the string values we get from JavaScript (as The code above will enable us to specify a Here is how you’d use this complete version from JavaScript:<\/p>\n In this article we have learned how to write a native module to call into the native Toast Notification APIs, and how to use the JSValue APIs to inspect values sent from the JavaScript side to the native module<\/p>\n You can find the If you\u2019re interested in getting started with React Native for Windows, check out our website at aka.ms\/reactnative<\/a>.<\/p>\nraise<\/code>. The Windows toast notification API takes an XML document as input, which will specify the text and image sources that we want to show. However, it would be much more natural for us to work with JavaScript objects and JSON instead of XML markup.\nSo our raise<\/code> method will take a JS object, which will include what template the app wants to use, as well as arrays of text and images that apply to the template. We will take the information in this JS object, and use it to construct the XML that we need to pass to the platform API.<\/p>\nCreate a module<\/h3>\n
Notifications.h<\/code> file to our example app project. In this initial version, we’ll use the simplest static Toast template (one string of text), so we’ll have our raise<\/code> method take a string:<\/p>\n#pragma once\n#include <NativeModules.h>\n#include <winrt\/Windows.UI.Notifications.h>\n#include <winrt\/Windows.Data.Xml.Dom.h>\n\nusing namespace winrt::Windows::UI::Notifications;\nusing namespace winrt::Windows::Data::Xml::Dom;\n\nREACT_MODULE(Notifications)\nstruct Notifications {\n\n REACT_INIT(Initialize);\n void Initialize(React::ReactContext const& context) noexcept {\n m_context = context;\n }\n\n REACT_METHOD(Raise, L\"raise\");\n void Raise(const std::string& text) noexcept\n {\n }\n\nprivate:\n React::ReactContext m_context;\n};<\/code><\/pre>\nReactPackageProvider.cpp<\/code>, we just include our new header:<\/p>\n#include \"pch.h\"\n#include \"ReactPackageProvider.h\"\n#include \"NativeModules.h\"\n+#include \"Notifications.h\"\nusing namespace winrt::Microsoft::ReactNative;\n\nnamespace winrt::example::implementation\n{\n\nvoid ReactPackageProvider::CreatePackage(IReactPackageBuilder const &packageBuilder) noexcept\n{\n AddAttributedModules(packageBuilder);\n}\n\n} \/\/ namespace winrt::example::implementation<\/code><\/pre>\nStarting simple<\/h3>\n
App.tsx<\/code> or App.js<\/code>), we will import NativeModules and add a button that calls into our raise<\/code> API when clicked. Here we are using a react-native-xaml<\/a> Button component, but you can use any UI component and toolkit you’d like.\nNormally, you would call the raise<\/code> API in response to some other event, like an upload\/download operation completing.<\/p>\nimport {\n \/\/ ...\n NativeModules,\n} from \"react-native\";\nimport { Button } from \"react-native-xaml\";\n\n\/\/ ...\n<Button\n onClick={() => {\n NativeModules.Notifications.raise(\"hello\");\n }}\n content=\"click me to send a toast\"\n\/>;<\/code><\/pre>\nRaise<\/code> method.\nNow we get to have fun. First let’s try the simplest static Toast template, ToastText01<\/code>. This template just has one value for us to fill out, the text we want to show.\nHere’s the logic to send a toast using this template, in C++:<\/p>\n REACT_METHOD(Raise, L\"raise\");\n void Raise(const std::string& textToShow) noexcept\n {\n auto xml = ToastNotificationManager::GetTemplateContent(ToastTemplateType::ToastText01);\n for (auto& element : xml.GetElementsByTagName(L\"text\")) {\n element.AppendChild(xml.CreateTextNode(winrt::to_hstring(textToShow)));\n }\n\n auto toast = ToastNotification(xml);\n ToastNotificationManager::CreateToastNotifier().Show(toast);\n }<\/code><\/pre>\nComplete solution<\/h3>\n
std::string<\/code> values which are UTF-8) onto platform strings (winrt::hstring<\/code>), which are UTF-16, so we use the winrt::to_hstring<\/code> helper for that.\nNow that we have the simple case, it’s time to crank it up a notch: we want to be able to use any of the available toast templates, which can have a number of text strings and images. The image elements have a src<\/code> attribute as well as an alt<\/code> attribute for accessibility.<\/p>\n REACT_METHOD(Raise, L\"raise\");\n void Raise(const React::JSValue& notification) noexcept\n {\n\n ToastTemplateType type = ToastTemplateType::ToastText01;\n\n React::JSValueObject obj;\n if (notification.Type() == React::JSValueType::String)\n {\n obj[\"text\"] = notification.AsString();\n }\n else {\n obj = notification.AsObject().Copy();\n }\n\n auto typeEntry = obj.find(\"template\");\n if (typeEntry != obj.end() && typeEntry->second.Type() == React::JSValueType::Int64) {\n type = static_cast<ToastTemplateType>(typeEntry->second.AsInt32());\n }\n\n auto xml = ToastNotificationManager::GetTemplateContent(type);\n\n for (const auto& entry : obj)\n {\n const auto tagName = winrt::to_hstring(entry.first);\n auto xmlElements = xml.GetElementsByTagName(tagName);\n\n if (entry.second.Type() == React::JSValueType::String) {\n React::JSValueArray strToArray;\n strToArray.push_back(entry.second.AsString());\n FillXmlElements(xml, xmlElements, strToArray);\n }\n else if (entry.second.Type() == React::JSValueType::Object) {\n React::JSValueArray objToArray;\n objToArray.push_back(entry.second.AsObject().Copy());\n FillXmlElements(xml, xmlElements, objToArray);\n } else {\n FillXmlElements(xml, xmlElements, entry.second.AsArray());\n }\n }\n\n auto toast = winrt::Windows::UI::Notifications::ToastNotification(xml);\n ToastNotificationManager::CreateToastNotifier().Show(toast);\n }\n\nprivate:\n React::ReactContext m_context;\n\n void FillXmlElements(const XmlDocument& xml, const XmlNodeList& xmlElements, const React::JSValueArray& arr) {\n int i = 0;\n for (const auto& arrValue : arr) {\n auto node = xmlElements.GetAt(i++);\n if (arrValue.Type() == React::JSValueType::String) {\n const auto value = winrt::to_hstring(arrValue.AsString());\n node.AppendChild(xml.CreateTextNode(value));\n }\n else if (arrValue.Type() == React::JSValueType::Object) {\n const auto& arrValueObj = arrValue.AsObject();\n for (const auto& entry : arrValueObj) {\n auto attrName = winrt::to_hstring(entry.first);\n auto attr = node.Attributes().GetNamedItem(attrName);\n if (!attr) {\n attr = xml.CreateAttribute(attrName);\n node.Attributes().SetNamedItem(attr);\n }\n\n attr.NodeValue(winrt::box_value(winrt::to_hstring(entry.second.AsString())));\n }\n }\n }\n }<\/code><\/pre>\ntemplate<\/code> attribute, that we will set to be the numeric value of the template we want to use. You can find a table of such values in the ToastTemplateType docs<\/a>. For example, ToastText01<\/code> has a value of 4, so we’d specify template: 4<\/code>.\nIt will also iterate through the rest of our JavaScript object parameter to discover the key\/value pairs we want to set and apply them to the underlying XML that we will later pass to the platform.<\/p>\n<Button\n onClick={() => {\n NativeModules.Notifications.raise({\n template: 0, \/\/ ToastImageAndText01 - see https:\/\/docs.microsoft.com\/uwp\/api\/Windows.UI.Notifications.ToastTemplateType\n \/\/ The template schema can be found at https:\/\/docs.microsoft.com\/previous-versions\/windows\/apps\/hh761494(v=win.10)\n text: \"hello world\",\n image: {\n src: \"https:\/\/microsoft.github.io\/react-native-windows\/img\/header_logo.svg\",\n alt: \"React logo\",\n },\n });\n }}\n content=\"click me to send a toast\"\n\/><\/code><\/pre>\nWrapping up<\/h3>\n
Notifications.h<\/code> header used in this article as a GitHub Gist<\/a>.<\/p>\n