弹层

@alifd/overlay

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

如何使用

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

Overlay

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

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

安全节点 safeNode

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

定位

points 的值可以是由空格隔开的字符串，如 ['tl', 'bl']，其中 tl 代表目标元素的左上方，bl 代表基准元素的左下方，所以 ['tl', 'bl'] 的意思是目标元素的左上方对齐基准元素左下方。其中定位的可选值有 tl, tc, tr, cl, cc, cr, bl, bc, br。t 为 top 的缩写，b 为 bottom 的缩写，c 为 center 的缩写，l 为 left 的缩写，r 为 right 的缩写。

Popup

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

API

Overlay

参数	说明	类型	默认值
children	弹层内容	ReactElement	-
visible	是否显示弹层	Boolean	false
onRequestClose	弹层请求关闭时触发事件的回调函数	Function	() => {}
target	弹层定位的参照元素	Function	（）=> document.body
points	弹层相对于参照元素的定位	[point, point]	['tl', 'bl']
placement	部分 points 的简写模式可选值: 't'(上，对应 points: ['bc', 'tc']) 'r'(右，对应 points: ['lc', 'rc']) 'b'(下，对应 points: ['tc', 'bc']) 'l'(左，对应 points: ['rc', 'lc']) 'tl'(上左，对应 points: ['bl', 'tl']) 'tr'(上右，对应 points: ['br', 'tr']) 'bl'(下左，对应 points: ['tl', 'bl']) 'br'(下右，对应 points: ['tr', 'br']) 'lt'(左上，对应 points: ['rt', 'lt']) 'lb'(左下，对应 points: ['rb', 'lb']) 'rt'(右上，对应 points: ['lt', 'rt']) 'rb'(右下，对应 points: ['lb', 'rb'])	Enum	'bl'
offset	弹层相对于 trigger 的定位的微调，接收数组[hoz, ver], 表示弹层在 left / top 上的增量 e.g. [100, 100] 表示往右、下分布偏移 100px	Array	[0, 0]
container	渲染组件的容器，如果是函数需要返回 ref，如果是字符串则是该 DOM 的 id，也可以直接传入 DOM 节点	any	-
hasMask	是否显示遮罩	Boolean	false
canCloseByEsc	是否支持 esc 按键关闭弹层	Boolean	true
canCloseByOutSideClick	点击弹层外的区域是否关闭弹层，不显示遮罩时生效	Boolean	true
canCloseByMask	点击遮罩区域是否关闭弹层，显示遮罩时生效	Boolean	true
onOpen	弹层打开时触发事件的回调函数	Function	noop
onClose	弹层关闭时触发事件的回调函数	Function	noop
beforePosition	弹层定位完成前触发的事件	Function	noop
onPosition	弹层定位完成时触发的事件签名: Function(config: Object) => void 参数: config: {Object} 定位的参数 config.config.points: {Array} 对齐方式，如 ['cc', 'cc']（如果开启 needAdjust，可能和预先设置的 points 不同） config.style.top: {Number} 距离视口顶部距离 config.style.left: {Number} 距离视口左侧距离	Function	noop
autoFocus	弹层打开时是否让其中的元素自动获取焦点	Boolean	false
autoAdjust	当弹层由于页面滚动等情况不在可视区域时，是否自动调整定位以出现在可视区域	Boolean	true
autoHideScrollOverflow	当 trigger 外面有滚动条，滚动到不可见区域后隐藏弹窗	Boolean	true
cache	隐藏时是否保留子节点	Boolean	false
safeNode	安全节点，当点击 document 的时候，如果包含该节点则不会关闭弹层，如果是函数需要返回 ref，如果是字符串则是该 DOM 的 id，也可以直接传入 DOM 节点，或者以上值组成的数组	any	-
wrapperClassName	弹层的根节点的样式类	String	-
wrapperStyle	弹层的根节点的内联样式	Object	-

Overlay.Popup

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

参数	说明	类型	默认值
children	触发弹层显示或隐藏的元素	ReactNode	-
overlay	弹层内容	ReactElement	-
triggerType	触发弹层显示或隐藏的操作类型，可以是 'click'，'hover'，'focus'，或者它们组成的数组，如 ['hover', 'focus']	String/Array	'hover'
triggerClickKeycode	当 triggerType 为 click 时才生效，可自定义触发弹层显示的键盘码	Number/Array	[KEYCODE.SPACE, KEYCODE.ENTER]
visible	弹层当前是否显示	Boolean	-
defaultVisible	弹层默认是否显示	Boolean	false
onVisibleChange	弹层显示或隐藏时触发的回调函数签名: Function(visible: Boolean, type: String, e: Object) => void 参数: visible: {Boolean} 弹层是否显示 type: {String} 触发弹层显示或隐藏的来源 fromTrigger 表示由 trigger 的点击触发；docClick 表示由 document 的点击触发 e: {Object} DOM 事件	Function	noop
disabled	设置此属性，弹层无法显示或隐藏	Boolean	false
delay	弹层显示或隐藏的延时时间（以毫秒为单位），在 triggerType 被设置为 hover 时生效	Number	200
mouseEnterDelay	鼠标移入弹层显示的延时时间（以毫秒为单位），在 triggerType 被设置为 hover 时生效，优先级高于 delay	Number	-
mouseLeaveDelay	鼠标移出弹层隐藏的延时时间（以毫秒为单位），在 triggerType 被设置为 hover 时生效，优先级高于 delay	Number	-
followTrigger	是否跟随 trigger 滚动	Boolean	false

Overlay

Overlay 使用。

fixed dialog

fixed 模式的dialog，带有遮罩的弹层。

import { useState, useRef } from 'react';
import Overlay from '@alifd/overlay';

const maskStyle = {
  position: 'fixed',
  top: 0,
  right: 0,
  bottom: 0,
  left: 0,
  height: '100%',
  backgroundColor: '#00000073',
};

const Demo = () => {
  const [visible, setVisible] = useState(false);
  const [visible2, setVisible2] = useState(false);

  const dialogRef = useRef(null);

  const onClose = (e) => {
    if (e.type === 'click' && dialogRef.current && dialogRef.current.contains(e.target)) {
      return;
    }
    setVisible(false);
  };

  const onClose2 = (e) => {
    setVisible2(false);
  };

  return (
    <div>
      <button onClick={() => setVisible(true)}> 超出滚动 </button>
      <button onClick={() => setVisible2(true)} style={{ marginLeft: 8 }}>
        {' '}
        内部滚动{' '}
      </button>
      <Overlay
        visible={visible}
        maskClassName="next-overlay-mask"
        maskStyle={maskStyle}
        hasMask
        canCloseByMask
        fixed
        offset={[0, 0]}
        onRequestClose={onClose}
        autoFocus
      >
        <div
          style={{
            position: 'fixed',
            top: 0,
            left: 0,
            bottom: 0,
            right: 0,
            overflow: 'auto',
          }}
          onClick={onClose}
        >
          <div
            style={{
              position: 'relative',
              top: 100,
              width: '100vw',
              pointerEvents: 'none',
              paddingBottom: 24,
            }}
          >
            <div
              role="dialog"
              ref={dialogRef}
              style={{
                pointerEvents: 'auto',
                margin: '0 auto',
                width: 500,
                background: '#fff',
                borderRadius: 2,
                boxShadow:
                  '0 3px 6px -4px #0000001f, 0 6px 16px #00000014, 0 9px 28px 8px #0000000d',
              }}
            >
              with long content
              <br />
              <input />
              <div style={{ padding: '1400px 8px 8px 8px' }}>
                <button onClick={onClose}>ok</button>
                <button onClick={onClose} style={{ marginLeft: 8 }}>
                  cancel
                </button>
              </div>
            </div>
          </div>
        </div>
      </Overlay>

      <Overlay
        visible={visible2}
        maskClassName="next-overlay-mask"
        maskStyle={maskStyle}
        hasMask
        canCloseByMask
        fixed
        autoFocus
        offset={[0, 100]}
        onRequestClose={onClose2}
      >
        <div
          style={{
            position: 'relative',
            width: '100vw',
            pointerEvents: 'none',
          }}
        >
          <div
            role="dialog"
            style={{
              pointerEvents: 'auto',
              margin: '0 auto',
              width: 500,
              maxHeight: 'calc(100vh - 120px)',
              overflow: 'auto',
              background: '#fff',
              borderRadius: 2,
              boxShadow: '0 3px 6px -4px #0000001f, 0 6px 16px #00000014, 0 9px 28px 8px #0000000d',
            }}
          >
            <p>with long content</p>
            <input />
            <div style={{ padding: '1400px 8px 8px 8px' }}>
              <button onClick={onClose}>ok</button>
              <button onClick={onClose} style={{ marginLeft: 8 }}>
                cancel
              </button>
            </div>
          </div>
        </div>
      </Overlay>
    </div>
  );
};

ReactDOM.render(<Demo />, mountNode);

Popup弹层

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

触发方式

通过 triggerType 属性设置触发方式。

受控显示隐藏

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

import Overlay from '@alifd/overlay';

const { Popup } = Overlay;

const style = {
  width: 400,
  height: 100,
  padding: 10,
  background: '#fff',
  borderRadius: 2,
  boxShadow: '2px 2px 20px rgba(0, 0, 0, 0.15)',
};

const DemoOverlay = React.forwardRef((props, ref) => {
  return (
    <span {...props} style={{ ...style, ...props.style }} ref={ref}>
      Hello World From Popup!
    </span>
  );
});

class Demo extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      visible: false,
      visible3: false,
    };
  }

  onVisibleChange = (visible) => {
    this.setState({
      visible,
    });
  };

  onGroupVisibleChange = (groupVisible) => {
    this.setState({
      groupVisible,
    });
  };

  render() {
    return (
      <div>
        <div>
          <Popup
            overlay={<DemoOverlay />}
            triggerType="click"
            visible={this.state.visible}
            onVisibleChange={this.onVisibleChange}
          >
            <button>Open</button>
          </Popup>
        </div>
        <br />
        <div>
          <Popup
            overlay={
              <DemoOverlay
                ref={(ref) => {
                  this.overlay1 = ref;
                }}
              />
            }
            triggerType="click"
            visible={this.state.groupVisible}
            safeNode={[() => this.btn2, () => this.overlay2]}
            onVisibleChange={this.onGroupVisibleChange}
          >
            <button
              style={{ marginRight: '50px' }}
              ref={(ref) => {
                this.btn1 = ref;
              }}
            >
              Paired Popup 1
            </button>
          </Popup>
          <Popup
            overlay={
              <DemoOverlay
                ref={(ref) => {
                  this.overlay2 = ref;
                }}
              />
            }
            triggerType="click"
            visible={this.state.groupVisible}
            safeNode={[() => this.btn1, () => this.overlay1]}
            onVisibleChange={this.onGroupVisibleChange}
          >
            <button
              ref={(ref) => {
                this.btn2 = ref;
              }}
            >
              Paired Popup 2
            </button>
          </Popup>
        </div>
        <br />
        <div>
          <Popup
            target={() => this.divref}
            overlay={<DemoOverlay />}
            visible={this.state.visible3}
            safeNode={() => this.btn3}
            onVisibleChange={(visible) => this.setState({ visible3: visible })}
          ></Popup>

          <button
            onClick={() => this.setState({ visible3: true })}
            ref={(ref) => {
              this.btn3 = ref;
            }}
          >
            target
          </button>
          <div
            ref={(ref) => (this.divref = ref)}
            style={{
              width: 20,
              height: 20,
              background: 'blue',
              display: 'inline-block',
              marginLeft: 100,
            }}
          />
        </div>
      </div>
    );
  }
}

ReactDOM.render(<Demo />, mountNode);

悬停点击弹出窗口

显示如何创建可悬停和单击的弹出窗口。

弹层嵌套

有弹层嵌套需求时，请使用 container 属性将第二个弹层渲染到第一个弹层内部, 这样不会因为点击第二个弹窗导致第一个弹窗消失。

followTrigger:

对齐

通过 placement 可以自定义对齐方式。

自动更换位置

能够根据空间大小自动更换 placement

若调整后位置始终不符合预期，可能是渲染过程中overlay内容宽度发生了变化导致计算错误，可以尝试固定overlay内容宽度来解决

import { useState } from 'react';
import Overlay from '@alifd/overlay';

const { Popup } = Overlay;
const style = {
  width: 200,
  height: 100,
  padding: 10,
  background: '#fff',
  borderRadius: 2,
  boxShadow: '2px 2px 20px rgba(0, 0, 0, 0.15)',
};

const App = () => {
  const [position, setPosition] = useState({});

  return (
    <div
      style={{
        position: 'relative',
        height: 200,
        padding: 20,
        border: '1px solid #eee',
        overflow: 'auto',
      }}
    >
      <div>
        <Popup
          overlay={<div style={style}>上面空间不够</div>}
          placement="tl"
          triggerType="click"
          followTrigger
        >
          <button>TL-> BL</button>
        </Popup>
        <Popup
          overlay={<div style={style}>上面空间不够</div>}
          placement="t"
          triggerType="click"
          followTrigger
        >
          <button style={{ marginLeft: 10 }}>T -> B</button>
        </Popup>
        <Popup
          overlay={<div style={style}>上面空间不够</div>}
          placement="tr"
          triggerType="click"
          followTrigger
        >
          <button style={{ marginLeft: 10 }}>TR -> BR</button>
        </Popup>
        <Popup
          overlay={<div style={style}>上面空间不够</div>}
          placement="tl"
          triggerType="click"
          followTrigger
        >
          <button style={{ marginTop: 0, float: 'right', right: 0 }}>TL-> BR</button>
        </Popup>
      </div>

      <br />
      <div>
        <Popup
          overlay={<div style={style}>左边空间不够</div>}
          placement="lt"
          triggerType="click"
          followTrigger
        >
          <button style={{ marginTop: 0 }}>LT-> RT</button>
        </Popup>
        <Popup
          overlay={<div style={style}>右边空间不够</div>}
          placement="rt"
          triggerType="click"
          followTrigger
        >
          <button style={{ float: 'right', right: 0 }}>RT-> LT</button>
        </Popup>

        <br />
        <br />
        <Popup
          overlay={<div style={style}>左边空间不够</div>}
          placement="lb"
          triggerType="click"
          followTrigger
        >
          <button style={{ marginTop: 0 }}>LB-> RB</button>
        </Popup>
        <Popup
          overlay={<div style={style}>右边空间不够</div>}
          placement="rb"
          triggerType="click"
          followTrigger
        >
          <button style={{ float: 'right', right: 0 }}>RB-> LB</button>
        </Popup>
        <br />
        <br />
        <Popup
          overlay={<div style={style}>左边、下边空间不够</div>}
          placement="l"
          triggerType="click"
          followTrigger
        >
          <button style={{ marginTop: 0 }}>L-> R</button>
        </Popup>
        <Popup
          overlay={<div style={style}>右边空间不够</div>}
          placement="r"
          triggerType="click"
          followTrigger
        >
          <button style={{ float: 'right', right: 0 }}>R-> L</button>
        </Popup>
      </div>

      <br />
      <div>
        <Popup
          overlay={<div style={style}>下边/左边空间都不够</div>}
          placement="b"
          triggerType="click"
          followTrigger
        >
          <button>B -> T</button>
        </Popup>
        <Popup
          overlay={<div style={style}>下边/左边空间都不够</div>}
          placement="br"
          triggerType="click"
          followTrigger
        >
          <button style={{ marginLeft: 10 }}>BR -> TL</button>
        </Popup>
        <Popup
          overlay={<div style={style}>右边空间不够</div>}
          placement="bl"
          triggerType="click"
          followTrigger
        >
          <button style={{ float: 'right', right: 0 }}>BL-> TR</button>
        </Popup>
      </div>
    </div>
  );
};

ReactDOM.render(<App />, mountNode);

在fixed弹窗中滚动

带有遮罩的弹层。

import { useState, useRef } from 'react';
import Overlay from '@alifd/overlay';
const { Popup } = Overlay;

const style = {
  width: 400,
  height: 150,
  padding: 10,
  background: '#fff',
  borderRadius: 2,
  boxShadow: '2px 2px 20px rgba(0, 0, 0, 0.15)',
};

const Demo = () => {
  const [visible, setVisible] = useState(false);
  const [visible2, setVisible2] = useState(false);
  const [position, setPosition] = useState({});
  const [position2, setPosition2] = useState({});
  const [position3, setPosition3] = useState({});

  const dialogRef = useRef(null);

  const onClose = (e) => {
    console.log(/onclick/, e.target);
    if (dialogRef.current && dialogRef.current.contains(e.target)) {
      return;
    }
    setVisible(false);
  };

  const onClose2 = (e) => {
    setVisible2(false);
  };

  return (
    <div>
      <button onClick={() => setVisible(true)}> 超出滚动 </button>
      <button onClick={() => setVisible2(true)} style={{ marginLeft: 8 }}>
        {' '}
        内部滚动{' '}
      </button>
      {/*<div style={{position: 'fixed', top: 200, left: 300}}>
                <Popup 
                    overlay={<span style={style}>left: {position3.left} top: {position3.top}</span>} 
                    onPosition={({style}) => setPosition3(style)}
                >
                    <button>打开后滚动试试</button>
                </Popup>
            </div>*/}
      <Overlay
        visible={visible}
        maskClassName="next-overlay-mask"
        maskStyle={{
          position: 'fixed',
          top: 0,
          right: 0,
          bottom: 0,
          left: 0,
          height: '100%',
          backgroundColor: '#00000073',
        }}
        hasMask
        canCloseByMask
        fixed
        offset={[0, 0]}
        onRequestClose={onClose}
      >
        <div
          style={{
            position: 'fixed',
            top: 0,
            left: 0,
            bottom: 0,
            right: 0,
            overflow: 'auto',
          }}
          onClick={onClose}
        >
          <div
            style={{
              position: 'relative',
              top: 100,
              width: '100vw',
              pointerEvents: 'none',
              paddingBottom: 24,
            }}
          >
            <div
              role="dialog"
              ref={dialogRef}
              style={{
                pointerEvents: 'auto',
                margin: '0 auto',
                width: 500,
                background: '#fff',
                borderRadius: 2,
                boxShadow:
                  '0 3px 6px -4px #0000001f, 0 6px 16px #00000014, 0 9px 28px 8px #0000000d',
              }}
            >
              <Popup
                overlay={<span style={style}>{position.transform}</span>}
                onPosition={({ style }) => setPosition(style)}
              >
                <button>打开后滚动试试</button>
              </Popup>
              <div style={{ padding: '1400px 8px 8px 8px' }}>
                <button onClick={onClose}>ok</button>
                <button onClick={onClose} style={{ marginLeft: 8 }}>
                  cancel
                </button>
              </div>
            </div>
          </div>
        </div>
      </Overlay>

      <Overlay
        visible={visible2}
        maskClassName="next-overlay-mask"
        maskStyle={{
          position: 'fixed',
          top: 0,
          right: 0,
          bottom: 0,
          left: 0,
          height: '100%',
          backgroundColor: '#00000073',
        }}
        hasMask
        canCloseByMask
        fixed
        offset={[0, 100]}
        onRequestClose={onClose2}
      >
        <div
          style={{
            position: 'relative',
            width: '100vw',
            pointerEvents: 'none',
          }}
        >
          <div
            role="dialog"
            style={{
              pointerEvents: 'auto',
              margin: '0 auto',
              width: 500,
              maxHeight: 'calc(100vh - 120px)',
              overflow: 'auto',
              background: '#fff',
              borderRadius: 2,
              boxShadow: '0 3px 6px -4px #0000001f, 0 6px 16px #00000014, 0 9px 28px 8px #0000000d',
            }}
          >
            <Popup
              overlay={<span style={style}>{position2.transform}</span>}
              onPosition={({ style }) => setPosition2(style)}
            >
              <button>打开后滚动试试</button>
            </Popup>
            <div style={{ padding: '1400px 8px 8px 8px' }}>
              <button onClick={onClose}>ok</button>
              <button onClick={onClose} style={{ marginLeft: 8 }}>
                cancel
              </button>
            </div>
          </div>
        </div>
      </Overlay>
    </div>
  );
};

ReactDOM.render(<Demo />, mountNode);

弹层滚动自动更新位置

遇到有 overflow 滚动的弹窗，会自动监听滚动实时弹窗计算位置。触发器消失会自动隐藏

更换弹窗挂载容器

可以通过 container 把弹窗挂到指定位置，这样性能更好不会一直计算位置，弹窗也不会超出

Event

Overlay 使用。

Trigger changed

trigger 动态发生变化的时候需要能够准确获取

动态 target

target 动态变化

滚动自动隐藏面板

展示 autoHideScrollOverflow 的用法

Readme
Overlay
fixed dialog
Popup弹层
触发方式
受控显示隐藏
悬停点击弹出窗口
弹层嵌套
对齐
自动更换位置
在fixed弹窗中滚动
弹层滚动自动更新位置
更换弹窗挂载容器
Event
Trigger changed
动态 target
滚动自动隐藏面板