@react-native-ohos/react-native-popover-view
v6.1.2
Published
A <Popover /> component for react-native iOS, Android, and Web
Readme
文档模板:v0.4.2
本项目基于 react-native-popover-view 开发。
该第三方库的仓库已迁移至 AtomGit,且支持直接从 npm 下载,新的包名为:@react-native-ohos/react-native-popover-view,版本所属关系如下:
| 三方库名称 | 三方库版本(npm地址) | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | 源码地址 | | --- | --- | --- | --- | --- | --- | --- | --- | | @react-native-ohos/react-native-popover-view | ~ 6.1.2(开发中) | AtomGit Releases | 0.77.* / 0.82.* / 0.84.* / 0.86.* | 否 | API12+ | 6.1.0 | master | | @react-native-ohos/react-native-popover-view | ~ 5.1.8 | AtomGit Releases | 0.72.* | 否 | API12+ | 5.1.7 | br_rnoh0.72 | | @react-native-oh-tpl/react-native-popover-view | ~ 5.1.7@deprecated | GitHub Releases(deprecated) | 0.72.* | 否 | API12+ | 5.1.7 | sig |
简介
轻量级、可适配的 <Popover> 弹出层组件,用于 React Native,无第三方依赖。在锚点元素旁弹出带箭头与遮罩的浮层,支持 RN Modal / JS Modal / Tooltip 三种模式。本项目是其在 React Native OpenHarmony 平台的适配实现。
下载安装
进入到工程目录并输入以下命令:
npm
npm install @react-native-ohos/react-native-popover-viewyarn
yarn add @react-native-ohos/react-native-popover-view[!TIP] 本库为纯 JS/TS 组件库(无 NativeModule 与 har 产物),无需 Link 配置,安装后按 RN 应用正常流程编译运行即可。
约束与限制
兼容性
本文档内容基于以下版本验证通过:
- RNOH: 0.86.1; SDK: HarmonyOS 7.0.0 Release SDK; IDE: DevEco Studio 6.1.1 Release; ROM: 7.0.0.109 SP6;
- RNOH: 0.84.1; SDK: HarmonyOS 7.0.0 Release SDK; IDE: DevEco Studio 6.1.1 Release; ROM: 7.0.0.109 SP6;
- RNOH: 0.82.1; SDK: HarmonyOS 6.1.0 Release SDK; IDE: DevEco Studio 6.0.2.636; ROM: 6.1.0.117;
- RNOH: 0.77.18; SDK: HarmonyOS 5.1.1 Release SDK; IDE: DevEco Studio 5.1.1.840; ROM: 6.0.0;
权限要求
本库为纯 JS/TS 组件库,无需申请任何系统权限。
使用示例
下面的代码展示了这个库的基本使用场景:
[!WARNING] 使用时 import 的库名不变。
import React, { useState } from 'react';
import { View, TouchableOpacity, Text, Button, Easing } from 'react-native';
import Popover, { PopoverMode, PopoverPlacement, Rect } from 'react-native-popover-view';
const PopoverDemo = () => {
const [showPopoverA, setShowPopoverA] = useState(false);
const [showPopoverB, setShowPopoverB] = useState(false);
const [showPopoverB2, setShowPopoverB2] = useState(false);
const [showPopoverC, setShowPopoverC] = useState(false);
const [onOpenStart, setOnOpenStart] = useState(111);
const [onOpenComplete, setOnOpenComplete] = useState(111);
const [onCloseStart, setOnCloseStart] = useState(111);
const [onCloseComplete, setOnCloseComplete] = useState(111);
const [offsetValue, setOffsetValue] = useState(10);
const [changeCount, setChangeCount] = useState(0);
return (
<View>
{/* 用例 A:from、isVisible */}
<TouchableOpacity>
<Text>用例A:from、isVisible</Text>
<Button title="testA" onPress={() => setShowPopoverA(true)} color="#841584" />
</TouchableOpacity>
<Popover
from={new Rect(5, 100, 20, 40)}
isVisible={showPopoverA}
onRequestClose={() => setShowPopoverA(false)}
>
<Text>This is the contents of the popoverA</Text>
</Popover>
{/* 用例 B:mode、offset、placement、样式、箭头、动画 */}
<TouchableOpacity>
<Text>用例B:mode、offset、placement、样式、箭头、动画</Text>
<Button title="testB" onPress={() => setShowPopoverB(true)} color="#cc15cc" />
</TouchableOpacity>
<Popover
from={new Rect(5, 100, 20, 40)}
isVisible={showPopoverB}
mode={PopoverMode.RN_MODAL}
offset={10}
placement={PopoverPlacement.TOP}
popoverStyle={{ backgroundColor: '#f00' }}
backgroundStyle={{ backgroundColor: '#00f' }}
arrowSize={{ width: 30, height: 8 }}
arrowShift={0.6}
animationConfig={{ duration: 600, easing: Easing.inOut(Easing.quad) }}
onRequestClose={() => setShowPopoverB(false)}
>
<Text>This is the contents of the popoverB</Text>
</Popover>
{/* 用例 B2:FLOATING 定位与 popoverShift(仅 FLOATING 生效,无需 from) */}
<TouchableOpacity>
<Text>用例B2:FLOATING 定位、popoverShift</Text>
<Button title="testB2" onPress={() => setShowPopoverB2(true)} color="#0be052" />
</TouchableOpacity>
<Popover
isVisible={showPopoverB2}
placement={PopoverPlacement.FLOATING}
popoverShift={{ x: -0.5, y: -0.5 }}
popoverStyle={{ backgroundColor: 'rgba(91, 81, 231, 1)' }}
onRequestClose={() => setShowPopoverB2(false)}
>
<Text>This is the contents of the popoverB2</Text>
</Popover>
{/* 用例 C:displayArea、displayAreaInsets、回调、onPositionChange */}
<TouchableOpacity>
<Text>用例C:displayArea、displayAreaInsets、回调、onPositionChange</Text>
<Button title="testC" onPress={() => setShowPopoverC(true)} color="#87cc94" />
</TouchableOpacity>
<Popover
from={new Rect(5, 100, 20, 40)}
isVisible={showPopoverC}
offset={offsetValue}
displayArea={new Rect(0, 0, 360, 640)}
displayAreaInsets={{ top: 20 }}
onOpenStart={() => setOnOpenStart(222)}
onOpenComplete={() => setOnOpenComplete(222)}
onRequestClose={() => setShowPopoverC(false)}
onCloseStart={() => setOnCloseStart(222)}
onCloseComplete={() => setOnCloseComplete(222)}
onPositionChange={() => setChangeCount(count => count + 1)}
>
<Text>This is the contents of the popoverC</Text>
</Popover>
<Text>onOpenStart {onOpenStart}</Text>
<Text>onOpenComplete {onOpenComplete}</Text>
<Text>onCloseStart {onCloseStart}</Text>
<Text>onCloseComplete {onCloseComplete}</Text>
<Text>onPositionChange 触发次数 {changeCount}</Text>
<Button
title="change position"
onPress={() => setOffsetValue(offsetValue === 10 ? 20 : 10)}
color="#876664"
/>
</View>
);
};
export default PopoverDemo;使用说明
三种模式
<Popover mode={PopoverMode.RN_MODAL}> // 系统模态层(默认,全局同时只能显示一个)
<Popover mode={PopoverMode.JS_MODAL}> // JS 绝对定位层(可多实例并存,层级由插入位置决定)
<Popover mode={PopoverMode.TOOLTIP}> // 无遮罩轻提示from 的五种形态
<Popover from={new Rect(5, 100, 20, 40)}> // 静态矩形坐标
<Popover from={new Point(15, 120)}> // 点坐标
<Popover from={this.buttonRef}> // 元素引用(RefObject),实测锚点
<Popover from={<Button title="打开" onPress={() => {}} />}> // React 元素
<Popover from={(ref, showPopover) => (<Button onPress={showPopover} />)}> // 渲染函数requestClose()
非受控用法(不传 isVisible)下,通过 ref 主动关闭弹层:
const popoverRef = useRef<any>(null);
<Popover ref={popoverRef} from={<Button title="打开" onPress={() => {}} />}>
<Button title="关闭" onPress={() => popoverRef.current?.requestClose()} />
</Popover>接口说明
[!TIP] "平台"列表示该属性在原三方库上支持的平台。
[!TIP] "OpenHarmony平台支持"列为 "是" 表示 OpenHarmony 平台支持该属性;"否" 则表示不支持;"部分支持" 表示仅实现了功能的一部分。使用方法跨平台一致,效果对标 iOS 或 Android 的效果。
组件
| 名称 | 参数类型 | 必填 | 平台 | OpenHarmony平台支持 | 描述 | | --- | --- | --- | --- | --- | --- | | Popover | PopoverProps | 否 | All | 是 | 弹出层组件 |
属性
PopoverProps
| 名称 | 参数类型 | 默认值 | 必填 | 平台 | OpenHarmony平台支持 | 描述 |
| --- | --- | --- | --- | --- | --- | --- |
| from | multiple | 无 | 否 | All | 是 | 弹出层锚点源:Rect / Point / RefObject / React 元素 / 渲染函数,详见使用说明。 |
| isVisible | bool | 无 | 否 | All | 是 | 显示/隐藏弹出层(受控用法)。 |
| mode | string | 'rn-modal' | 否 | All | 是 | 模式:'rn-modal' / 'js-modal' / 'tooltip'。 |
| placement | string / string list | 'auto' | 否 | All | 是 | 定位:'top' / 'bottom' / 'left' / 'right' / 'floating' / 'auto',可传数组按序择优。 |
| offset | number | 无 | 否 | All | 是 | 弹出层偏离锚点的距离(居中时不适用)。 |
| verticalOffset | number | 0 | 否 | OpenHarmony | 是 | 垂直偏移(正值向下)。鸿蒙版新增属性,替代原版 statusBarTranslucent 在 Android 上的状态栏自动偏移。 |
| animationConfig | object | 无 | 否 | All | 是 | 动画配置(同 Animated.timing),覆盖所有动画的默认值。 |
| displayArea | rect | 无 | 否 | All | 是 | 允许显示弹出层的区域,默认自动计算。 |
| displayAreaInsets | object | 无 | 否 | All | 是 | 显示区域内边距。 |
| popoverStyle | object | {} | 否 | All | 是 | 弹出层自身样式。 |
| popoverShift | object | 无 | 否 | All | 是 | 按比例平移弹出层,{ x, y } 取值 -1~1(floating 定位下适用)。 |
| backgroundStyle | object | {} | 否 | All | 是 | 背景视图样式(默认黑色 0.5 透明)。 |
| arrowSize | object | { width: 16, height: 8 } | 否 | All | 是 | 箭头尺寸,{ width: 0, height: 0 } 隐藏箭头。 |
| arrowShift | number | 无 | 否 | All | 是 | 箭头沿边平移量(-1~1)。 |
| onOpenStart | function | 无 | 否 | All | 是 | 打开动画开始时触发。 |
| onOpenComplete | function | 无 | 否 | All | 是 | 打开动画结束时触发。 |
| onRequestClose | function | 无 | 否 | All | 是 | 点击弹层外部(背景)或系统返回键时触发。 |
| onCloseStart | function | 无 | 否 | All | 是 | 弹出层开始关闭时触发。 |
| onCloseComplete | function | 无 | 否 | All | 是 | 弹出层完全关闭后触发。 |
| onPositionChange | function | 无 | 否 | All | 是 | 弹出层位置移动完成后触发。 |
| statusBarTranslucent | bool | 无 | 否 | Android | 否 | 原库 Android 属性。鸿蒙版已从公开 API 移除(RNOH 的 Modal 无对应机制,传值无效果),如需调整与状态栏的相对位置请使用 verticalOffset。 |
| debug | bool | false | 否 | All | 是 | 开启调试日志。 |
API
| 名称 | 类型 | 参数类型 | 返回值 | 必填 | 平台 | OpenHarmony平台支持 | 描述 | | --- | --- | --- | --- | --- | --- | --- | --- | | requestClose | function | / | / | 否 | All | 是 | 非受控用法下通过 ref 主动关闭弹层(触发 onRequestClose 后置内部 isVisible 为 false)。 |
遗留问题
无
其他
相对上游 6.1.0 的接口差异:删除了 statusBarTranslucent 公开属性(Android 专用,鸿蒙无对应机制);新增 verticalOffset 属性作为替代;requestClose() 方法与无障碍属性已恢复与上游对齐。
目录结构
/rntpc_react-native-popover-view # 项目根目录
├── example # 示例工程(演示用例 + README 使用示例镜像)
├── src # RN 侧纯 JS/TS 实现(Popover / BasePopover / AdaptivePopover 等)
│ └── index.ts # 入口
├── jest # 单元测试(jest 配置 / mock / 用例)
├── CHANGELOG.md # 变更记录
├── COMMITTERS.md # 提交人列表
├── OAT.xml # 开源治理文件
├── README.OpenSource # 开源申明
├── README.md # 中文文档
├── README_en.md # 英文文档
└── LICENSE # MIT贡献代码
使用过程中发现任何问题都可以提交 Issue,当然,也非常欢迎提交 PR。
开源协议
本项目基于 MIT License ,请自由地享受和参与开源。
