Overlay 弹层

用于生成弹层的工具类集合.

开发指南

Overlay 提供了一系列组件用于创建弹层。其中包含:

Overlay

Overlay 可以在页面中弹出一个浮层,封装了定位,动画及其他一些可用性的功能。Overlay 被设计为无状态的组件,其本身并不控制自己显示和隐藏的状态。

注意:

  • 类似 canCloseby* 的配置也需要配合 onRequestClose 才能关闭弹层。

  • 在默认情况下(弹层直接渲染在body里),由于弹层的位置是根据触发器的位置来动态计算的,其初始位置在窗口中的左上角。如果弹层中存在自动获取焦点的元素,那么当该元素在初始的窗口左上角时,系统会因该元素获取焦点而滚动页面到该位置。这可能会造成再次定位时,弹层因页面滚动到最顶部而不在可视区。所以,对于这种情况,建议不要将元素自动获取焦点,或者保证弹层的位置不会二次调整(通过container渲染到trigger处)。

安全节点

Overlay 提供了点击弹层外文档中节点隐藏该弹层的功能,如果想让某个节点点击后不隐藏弹层(如:触发弹层打开的节点),请将该节点传入 safeNode 属性。

定位

  1. align 的值可以是由空格隔开的字符串,如 tl bl,其中 tl 代表目标元素的左上方,bl 代表基准元素的左下方,所以 tl bl 的意思是目标元素的左上方对齐基准元素左下方。其中定位的可选值有 tl, tc, tr, cl, cc, cr, bl, bc, brttop 的缩写,bbottom 的缩写,ccenter 的缩写,lleft 的缩写,rright 的缩写.

  2. align 支持的 Boolean 值仅为 false,在设置为 false 时,不使用 JS 定位,这样你可以根据你的需要传入 style 或者 className 进行 CSS 定位。

  3. rtl情况下会自动翻转 r(right)与 l(left), 例如 rtl状态下tl bl与 非rtl状态下tr br等效 下面的例子演示了如何将弹层定位到页面的右上角:

<Overlay visible align="tr tr"><span>123</span></Overlay>

Popup

Popup 是对 Overlay 的封装,它接收某个节点作为触发节点,弹出一个浮层,这个浮层默认情况下使用这个节点作为定位的参照对象。

基本

弹出一个弹层。

遮罩

带有遮罩的弹层。


触发的弹层

使用 Popup 弹出一个弹层。


触发的弹层受控显示隐藏

展示了 Popup 受控显示隐藏的用法。

弹层嵌套

有弹层嵌套需求时,请使用 container 属性将第二个弹层渲染到第一个弹层内部。

弹层跟随滚动

弹层默认参照 document.body 绝对定位,如果弹层显示隐藏的触发元素所在容器(一般为父节点)有滚动条,那么当容器滚动时,会发生触发元素与弹层相分离的情况,解决的办法是将弹层渲染到触发元素所在的容器中。(触发元素所在的容器,必须设置 position 样式,以完成弹层的绝对定位。)

normal example




dir=rtl example

对齐

可以自定义对齐方式

API

Overlay

参数说明类型默认值
children弹层内容any-
visible是否显示弹层Booleanfalse
needListenResize是否监听resize事件Booleantrue
onRequestClose弹层请求关闭时触发事件的回调函数

签名:
Function(type: String, e: Object) => void
参数:
type: {String} 弹层关闭的来源
e: {Object} DOM 事件
Functionfunc.noop
target弹层定位的参照元素anyPosition.VIEWPORT
align弹层相对于参照元素的定位, 详见开发指南的定位部分String/Boolean'tl bl'
offset弹层相对于trigger的定位的微调, 接收数组hoz, ver, 表示弹层在 left / top 上的增量
e.g. 100, 100 表示往右(RTL 模式下是往左) 、下分布偏移100px
Array0, 4
container渲染组件的容器,如果是函数需要返回 ref,如果是字符串则是该 DOM 的 id,也可以直接传入 DOM 节点(采用字符串或者DOM节点时,请确保在render时该容器已在dom结构中存在)any-
hasMask是否显示遮罩Booleanfalse
canCloseByEsc是否支持 esc 按键关闭弹层Booleantrue
canCloseByOutSideClick点击弹层外的区域是否关闭弹层,不显示遮罩时生效Booleantrue
canCloseByMask点击遮罩区域是否关闭弹层,显示遮罩时生效Booleantrue
beforeOpen弹层打开前触发事件的回调函数

签名:
Function() => void
Functionfunc.noop
onOpen弹层打开时触发事件的回调函数

签名:
Function() => void
Functionfunc.noop
afterOpen弹层打开后触发事件的回调函数, 如果有动画,则在动画结束后触发

签名:
Function() => void
Functionfunc.noop
beforeClose弹层关闭前触发事件的回调函数

签名:
Function() => void
Functionfunc.noop
onClose弹层关闭时触发事件的回调函数

签名:
Function() => void
Functionfunc.noop
afterClose弹层关闭后触发事件的回调函数, 如果有动画,则在动画结束后触发

签名:
Function() => void
Functionfunc.noop
beforePosition弹层定位完成前触发的事件

签名:
Function() => void
Functionfunc.noop
onPosition弹层定位完成时触发的事件

签名:
Function(config: Object, node: Object) => void
参数:
config: {Object} 定位的参数
config.align: {Array} 对齐方式,如 'cc', 'cc'(如果开启 needAdjust,可能和预先设置的 align 不同)
config.top: {Number} 距离视口顶部距离
config.left: {Number} 距离视口左侧距离
node: {Object} 定位参照的容器节点
Functionfunc.noop
shouldUpdatePosition是否在每次弹层重新渲染后强制更新定位信息,一般用于弹层内容区域大小发生变化时,仍需保持原来的定位方式Booleanfalse
autoFocus弹层打开时是否让其中的元素自动获取焦点Booleanfalse
needAdjust当弹层由于页面滚动等情况不在可视区域时,是否自动调整定位以出现在可视区域Booleantrue
disableScroll是否禁用页面滚动Booleanfalse
cache隐藏时是否保留子节点Booleanfalse
safeNode安全节点,当点击 document 的时候,如果包含该节点则不会关闭弹层,如果是函数需要返回 ref,如果是字符串则是该 DOM 的 id,也可以直接传入 DOM 节点,或者以上值组成的数组any-
wrapperClassName弹层的根节点的样式类String-
wrapperStyle弹层的根节点的内联样式Object-
animation配置动画的播放方式,支持 { in: 'enter-class', out: 'leave-class' } 的对象参数,如果设置为 false,则不播放动画。 请参考 Animate 组件的文档获取可用的动画名Object/Boolean{ in: 'expandInDown', out: 'expandOutUp' }

Overlay.Popup

继承 Overlay 的 API,除非特别说明

参数说明类型默认值
children弹层内容ReactNode-
trigger触发弹层显示或隐藏的元素ReactElement-
triggerType触发弹层显示或隐藏的操作类型,可以是 'click','hover','focus',或者它们组成的数组,如 'hover', 'focus'String/Array'hover'
triggerClickKeycode当 triggerType 为 click 时才生效,可自定义触发弹层显示的键盘码Number/ArrayKEYCODE.SPACE, KEYCODE.ENTER
visible弹层当前是否显示Boolean-
defaultVisible弹层默认是否显示Booleanfalse
onVisibleChange弹层显示或隐藏时触发的回调函数

签名:
Function(visible: Boolean, type: String, e: Object) => void
参数:
visible: {Boolean} 弹层是否显示
type: {String} 触发弹层显示或隐藏的来源 fromTrigger 表示由trigger的点击触发; docClick 表示由document的点击触发
e: {Object} DOM事件
Functionfunc.noop
disabled设置此属性,弹层无法显示或隐藏Booleanfalse
delay弹层显示或隐藏的延时时间(以毫秒为单位),在 triggerType 被设置为 hover 时生效Number200
canCloseByTriggertrigger 是否可以关闭弹层Booleantrue
target弹层定位的参照元素anytarget 属性,即触发元素
followTrigger是否跟随trigger滚动Booleanfalse

Popup实例方法

参数说明
getOverlay获取底层的Overlay实例

ARIA and KeyBoard

说明: 此组件需要结合其他组件使用,会有提示。参考上文无障碍