From 2458863e5cc9888c908e6699fec9e8b40608bf16 Mon Sep 17 00:00:00 2001 From: 01xkp <1903679953@qq.com> Date: Tue, 13 Aug 2024 15:44:15 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9Ereact-native-notifier?= =?UTF-8?q?=E6=8C=87=E5=AF=BC=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- zh-cn/react-native-notifier.md | 224 +++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 zh-cn/react-native-notifier.md diff --git a/zh-cn/react-native-notifier.md b/zh-cn/react-native-notifier.md new file mode 100644 index 00000000..750d0359 --- /dev/null +++ b/zh-cn/react-native-notifier.md @@ -0,0 +1,224 @@ +> 模板版本：v0.2.2 + +

+

react-native-notifier

+

+

+ + Supported platforms + + + License + + +

+ + +>[!TIP] [Github 地址](https://github.com/seniv/react-native-notifier) +## 安装与使用 + +进入到工程目录并输入以下命令： + +#### **npm** + +```bash +npm install react-native-notifier@2.0.0 +``` + +#### **yarn** + +```bash +yarn add react-native-notifier@2.0.0 +``` + + + +下面的代码展示了这个库的基本使用场景： + +```js +import * as React from 'react'; +import { View, Text,SafeAreaView,TouchableOpacity } from "react-native"; + +import {Notifier, NotifierWrapper } from 'react-native-notifier'; + +import { GestureHandlerRootView } from 'react-native-gesture-handler'; + +export const Notifier = () => { + return ( + <> + + + + + Notifier.showNotification({ + title: '基本测试', + description: '基本测试', + }) + }> + onPress + + + + + +) +}; +``` +## Link + +本库 HarmonyOS 侧实现依赖 @react-native-oh-tpl/react-native-gesture-handler 的原生端代码，如已在 HarmonyOS 工程中引入过该库，则无需再次引入，可跳过本章节步骤，直接使用。 + +如未引入请参照[@react-native-oh-tpl/react-native-gesture-handler 文档](/zh-cn/react-native-gesture-handler.md)进行引入 + +### 兼容性 + +本文档内容基于以下版本验证通过: + +1. RNOH: 0.72.28; SDK: HarmonyOS-NEXT-DB1 5.0.0.31; IDE: DevEco Studio 5.0.3.500; ROM: 3.0.0.25; + +## Props + +详细请查看 [react-native-notifier 的文档介绍](https://github.com/seniv/react-native-notifier) + +Both `NotifierWrapper` and `NotifierRoot` receive the same props. + +> [!tip] "Platform"列表示该属性在原三方库上支持的平台。 + +> [!tip] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| ---- | ----------- | ---- | -------- | -------- | ------------------ | +| omitGlobalMethodsHookup | If set to `true`, global `Notifier` methods will not control this component. It's useful in case you have more than one `NotifierWrapper` or `NotifierRoot` rendered. If enabled, the only way to display notifications is using refs. | Boolean | yes | All | No | +| useRNScreensOverlay | use `FullWindowOverlay` component from `react-native-screens` library. If `true`, Notifier will be rendered above NativeStackNavigation modals and RN Modal on iOS. This Option will work only if `react-native-screens` library is installed. iOS Only. | Boolean | yes | iOS | No | +| rnScreensOverlayViewStyle | Style that will be used for RN View that is inside of FullWindowOverlay. iOS Only. | ViewStyle | yes | iOS | No | + +## API + +> [!tip] "Platform"列表示该属性在原三方库上支持的平台。 + +> [!tip] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| ---- | ----------- | ---- | -------- | -------- | ------------------ | +| showNotification | Show notification with params. | Function | yes | All | yes | +| hideNotification |Hide notification and run callback function when notification completely hidden. | Function | yes | All | yes | +| clearQueue |Clear [notifications queue](https://github.com/seniv/react-native-notifier/tree/main?tab=readme-ov-file#queue-mode) and optionally hide currently displayed notification. Might be useful to run after logout, after which queued notifications should not be displayed.| Function | yes | All | yes | + +### `showNotification` +``` +Notifier.showNotification(params: object); +``` + +`params` + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| ------------------- | ------------------------------------------------------------ | -------- | -------- | ----------- | ----------------- | +| title | Title of notification. Passed to Component. | String| Yes | All |Yes | +| description |Description of notification. Passed to Component. | String | Yes | All | Yes | +| duration |Time after notification will disappear. Set to 0 to not hide notification automatically | Number | No |All | Yes +| Component |Component of the notification body. You can use one of the [bin components](https://github.com/seniv/react-native-notifier/tree/main?tab=readme-ov-file#components), or your [custom component](https://github.com/seniv/react-native-notifier/tree/main?tab=readme-ov-file#custom-component). | Component | No |All | Yes +| componentProps | Additional props that are passed to Component. See all available props of built-in components in the [components section](https://github.com/seniv/react-native-notifier/tree/main?tab=readme-ov-file#components). | Object | No |All | Yes +| containerStyle |tyles Object or a Function that will receive translateY: Animated.Value as first parameter and should return Styles that will be used in container. Using this parameter it is possible to create[ your own animations of the notification](https://github.com/seniv/react-native-notifier/tree/main?tab=readme-ov-file#custom-animations). | bool |No | All | Yes +| containerProps | Props of Animated Container | Object |No | All | Yes +| queueMode | Determines the order in which notifications are shown. Read more in the [Queue Mode](https://github.com/seniv/react-native-notifier/tree/main?tab=readme-ov-file#queue-mode) section. | String |No | All | Yes +| swipeEnabled |Can notification be hidden by swiping it out | bool |No | All | Yes +| animationDuration | How fast notification will appear/disappear | Number |No | All | Yes +| showAnimationDuration | How fast notification will appear. | Number |No | All | Yes +| hideAnimationDuration | How fast notification will disappear.| Number |No | All | Yes +| easing | Animation easing. Details:[easing](https://reactnative.dev/docs/easing) | Easing |No | All | Yes +| showEasing | Show Animation easing.| Easing |No | All | Yes +| hideEasing |Hide Animation easing. | Easing |No | All | Yes +| onShown | Function called when entering animation is finished | () => void |No | All | Yes +| onStartHiding | Function called when notification started hiding | () => void |No | All | Yes +| onHidden |Function called when notification completely hidden | () => void |No | All | Yes +| onPress | Function called when user press on notification | () => void |No | All | Yes +| hideOnPress | Should notification hide when user press on it| Boolean |No | All | Yes +| swipePixelsToClose | How many pixels user should swipe-up notification to dismiss it | Number |No | All | Yes +| swipeEasing | Animation easing after user finished swiping | Easing |No | All | Yes +| swipeAnimationDuration | How fast should be animation after user finished swiping | Number |No | All | Yes +| translucentStatusBar | Add additional top padding that equals to StatusBar.currentHeight. Android Only. | Number |No | Android | No + +### `hideNotification` +``` +Notifier.hideNotification(onHiddenCallback?: (result: Animated.EndResult) => void); +``` + +### `clearQueue` +``` +Notifier.clearQueue(hideDisplayedNotification?: boolean); +``` + +## Queue Mode + +Queue mode is used to define the order in which the notification appears in case other notifications are being displayed at the moment. + +For example, if you have some important information like chat messages and you want the user to see all the notifications, then you can use `standby` mode. Or if you want to display something like an error message, then you can use `reset` mode. + +By default, `reset` mode is used, which means every new notification clears the queue and gets displayed immediately. + +In most cases, you will probably use only `reset` or `standby` modes. + +All possible modes: +| Mode | Effect | +| ------------------- | ------------------------------------ | +| reset | Clear notification queue and immediately display the new notification. Used by default. +| standby | Add notification to the end of the queue. +| next | Put notification in the first place in the queue. Will be shown right after the current notification disappears. +| immediate | Similar to next, but also it will hide currently displayed notification. + +## Components + +Currently, there are 2 components out of the box. If none of them fits your needs, then you can easily create your [Custom Component]. + +### `NotifierComponents.Notifications` + +| Name | Type | Default | Description | +| ---- | ----------- | ---- | -------- | +| title | String | null | Title of notification. | +| description | String | null | Description of notification. | +| componentProps.titleStyle | TextStyle | null | The style to use for rendering title. | +| componentProps.descriptionStyle | TextStyle | null |The style to use for rendering description. | +| componentProps.imageSource | Object | null | Passed to as source param. | +| componentProps.imageStyle | ImageStyle | null | The style to use for rendering image. | +| componentProps.containerStyle | ViewStyle | null | The style to use for notification container. | +| componentProps.ContainerComponent | Component | SafeAreaView | A container of the component. Set it in case you use different SafeAreaView than the standard | +| componentProps.maxTitleLines | number | null | The maximum number of lines to use for rendering title. | +| componentProps.maxDescriptionLines | number | null | The maximum number of lines to use for rendering description. | + +### `NotifierComponents.Alert` + +| Name | Type | Default | Description | +| ---- | ----------- | ---- | -------- | +| title | String | null | Title of notification. | +| description | String | null | Description of notification. | +| componentProps.titleStyle | TextStyle | null | The style to use for rendering title. | +| componentProps.descriptionStyle | TextStyle | null |The style to use for rendering description. | +|componentProps.alertType | String | 'success' |Background color will be changed depending on the type. Available values: error(red), success(green), warn(orange) and info(blue). | +| componentProps.backgroundColor | String | null | While the background of the alert depends on alertType, you can also set the other color you want. | +| componentProps.textColor | String | 'white' | Color of title and description. | +| componentProps.ContainerComponent | Component | SafeAreaView | A container of the component. Set it in case you use different SafeAreaView than the standard | +| componentProps.maxTitleLines | number | null | The maximum number of lines to use for rendering title. | +| componentProps.maxDescriptionLines | number | null | The maximum number of lines to use for rendering description. | + +## 遗留问题 + +- [ ] translucentStatusBar状态栏透明在HarmonyOS不支持,useRNScreensOverlay,rnScreensOverlayViewStyle两个属性依赖于react-native-screens，未鸿蒙化 +- [ ] omitGlobalMethodsHookup源库属性未生效 [#102](https://github.com/seniv/react-native-notifier/issues/102) + + +## 其他 + +## 开源协议 + +本项目基于 [The MIT License (MIT)](https://github.com/seniv/react-native-notifier/blob/main/LICENSE) ，请自由地享受和参与开源。 + \ No newline at end of file -- Gitee