Popup 弹出层

介绍

弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示。

引入

import { Popup } from "@taroify/core"

代码演示

基础用法

通过 open 控制弹出层是否展示。

const [open, setOpen] = useState(false)

<Popup open={open} onClose={setOpen}>
  内容
</Popup>

弹出位置

通过 placement 属性设置弹出位置，默认居中弹出，可以设置为 top、bottom、left、right。

<Popup defaultOpen placement="top" style={{ height: "30%" }} />

关闭图标 v1.0.2

设置 closeable 属性后，会在弹出层的右上角显示关闭图标。通过 closeIcon 自定义图标，通过 closeIconPlacement 设置图标位置。

<Popup
  defaultOpen
  closeable
  closeIcon={<Close />}
  closeIconPlacement="bottom-right"
  placement="bottom"
  style={{ height: "30%" }}
/>

也可以使用 Popup.Close 自定义关闭图标。

<Popup defaultOpen placement="bottom" style={{ height: "30%" }}>
  <Popup.Close>
    <Close />
  </Popup.Close>
</Popup>

遮罩层 v1.0.2

通过 backdrop 隐藏遮罩层，或传入对象配置遮罩层属性。closeOnClickBackdrop 用于控制点击遮罩层时是否关闭弹出层。

<Popup open backdrop={false} />

<Popup
  open
  backdrop={{
    style: {
      backgroundColor: "rgba(0, 0, 0, 0.7)",
    },
  }}
  closeOnClickBackdrop={false}
/>

关闭前回调 v1.0.2

通过 beforeClose 属性可以在关闭前执行同步或异步逻辑，返回 true 时关闭，返回其他值或 Promise 被拒绝时保持打开。

import type { PopupCloseAction } from "@taroify/core"

function beforeClose(action: PopupCloseAction) {
  return new Promise<boolean>((resolve) => {
    setTimeout(() => resolve(action === "close"), 1000)
  })
}

<Popup open closeable beforeClose={beforeClose} />

销毁内容 v1.0.2

默认情况下，弹出层关闭后内容仍会保留。设置 destroyOnClose 后，内容会在离场动画结束后卸载。

<Popup open={open} destroyOnClose>
  <HeavyContent />
</Popup>

圆角弹窗

设置 rounded 属性后，弹窗会根据弹出位置添加不同的圆角样式。

<Popup open rounded style={{ padding: "64px" }}>
  内容
</Popup>

<Popup open rounded placement="bottom" style={{ height: "30%" }} />

禁止滚动穿透

<Popup lock>
  <View>无法滑动</View>
</Popup>

如果需要内容支持溢出滚动，则需要包裹一层 ScrollView 组件。

<Popup lock>
  <ScrollView scrollY>可以滑动</ScrollView>
</Popup>

API

参数	说明	类型	默认值
defaultOpen	默认是否显示弹出层	boolean	`false`
open	是否显示弹出层	boolean	`false`
placement	弹出位置，可选值为 `top` `bottom` `right` `left` `center`	PopupPlacement	`center`
duration	动画时长，单位毫秒	number	`300`
rounded	是否显示圆角	boolean	`false`
lock	是否锁定背景滚动	boolean	`true`
backdrop v1.0.2	是否显示遮罩层，或传入遮罩层配置	boolean \| Omit<PopupBackdropProps, "open">	`true`
closeOnClickBackdrop v1.0.2	点击遮罩层时是否关闭弹出层	boolean	`true`
closeable v1.0.2	是否显示关闭图标	boolean	`false`
closeIcon v1.0.2	自定义关闭图标	ReactNode	`<Cross />`
closeIconPlacement v1.0.2	关闭图标位置，可选值为 `top-left` `top-right` `bottom-left` `bottom-right`	PopupClosePlacement	`top-right`
beforeClose v1.0.2	关闭前的回调函数，返回 `true` 时关闭	(action: PopupCloseAction) => boolean \| Promise<boolean>	-
destroyOnClose v1.0.2	关闭后是否卸载弹出层内容	boolean	`false`
mountOnEnter	首次打开时是否挂载弹出层内容	boolean	`true`
transitionAppear	首次挂载且已打开时是否执行入场动画	boolean	`true`
transition v1.0.2	动画名称	string	根据 `placement` 自动设置
transitionTimeout v1.0.2	动画超时时间，单位毫秒	PopupTransitionTimeout	`duration`
transaction 待废弃	请使用 `transition`	string	-
transactionTimeout 待废弃	请使用 `transitionTimeout`	PopupTransitionTimeout	-

动画相关参数继承自 Transition 组件，详细属性参见：Transition 组件。

Popup 参数	Transition 对应参数
mountOnEnter	mountOnEnter
transition	name
transitionAppear	appear
transitionTimeout	timeout
onTransitionEnter	onEnter
onTransitionEntered	onEntered
onTransitionExit	onExit
onTransitionExited	onExited

Popup.Backdrop Props

参数	说明	类型	默认值
className	遮罩层类名	string	-
style	遮罩层样式	CSSProperties	-
open	是否显示遮罩层	boolean	`true`
closeable	点击遮罩层后是否关闭弹出层	boolean	`true`
duration	动画时长，单位毫秒	number	`300`
lock	是否锁定背景滚动	boolean	`true`

Popup.Close Props

参数	说明	类型	默认值
placement	关闭图标位置，可选值为 `top-left` `top-right` `bottom-left` `bottom-right`	PopupClosePlacement	`top-right`
children	图标内容	ReactNode	`<Cross />`
onClick v1.0.2	点击关闭图标时触发	(event: ITouchEvent) => void	-

Events

事件名	说明	回调参数
onClick	点击弹出层时触发	event: ITouchEvent
onOpen v1.0.2	打开弹出层且入场动画开始时触发	-
onOpened v1.0.2	入场动画结束时触发	-
onClose	关闭弹出层时触发	opened: boolean
onClosed v1.0.2	离场动画结束时触发	-

类型定义

组件相关类型可从 @taroify/core 直接导入：

import type {
  PopupBackdropProps,
  PopupCloseAction,
  PopupClosePlacement,
  PopupCloseProps,
  PopupPlacement,
  PopupProps,
  PopupThemeVars,
  PopupTransitionTimeout,
} from "@taroify/core"

主题定制

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--popup-z-index	1010	-
--popup-background-color	var(--background-color-light)	-
--popup-animation-duration	var(--animation-duration-base)	-
--popup-rounded-border-radius	16px $hd*	-
--popup-close-icon-z-index	1	-
--popup-close-icon-size	22px $hd*	-
--popup-close-icon-color	var(--gray-5)	-
--popup-close-icon-active-color	var(--gray-6)	-
--popup-close-icon-margin	16px $hd*	-

#Popup 弹出层

#介绍

#引入

#代码演示

#基础用法

#弹出位置

#关闭图标 v1.0.2

#遮罩层 v1.0.2

#关闭前回调 v1.0.2

#销毁内容 v1.0.2

#圆角弹窗

#禁止滚动穿透

#API

#Popup Props

#Popup.Backdrop Props

#Popup.Close Props

#Events

#类型定义

#主题定制

#样式变量