zent-popover

通用的可定位弹层，可以自定义触发方式、弹层显示方式以及定位算法。

组件设计

这是一个通用的基础组件，是基于Portal的一个可定位组件，可以用来实现有交互或者定位需求的弹层，比如select, tooltip等。

组件由三个部分组成：

• Trigger, 用来控制弹层的触发逻辑，内置三个实现：click, hover, focus，除此以外可以实现任意自定义的trigger。
• Position: 用来控制弹层的定位逻辑，内置12种定位（4 x 3，每个方位三种），可以实现自定义的定位。
• Content: 用来控制弹层的绘制，内置一种基于Portal的实现。

使用示例：

<Popover position={Popover.Position.BottomLeft} display="inline">
  <Popover.Trigger.Click>
    <button>click me</button>
  </Popover.Trigger.Click>
  <Popover.Content>
    <div>popover content</div>
    <div>line two</div>
  </Popover.Content>
</Popover>

API

API 主要分为几块：Popover, Trigger, Content, Position以及一些工具函数。

Popover API

| 参数 | 说明 | 类型 | 默认值 | 备选值 | |------|------|------|--------|--------| | position | 定位的方式，参见Popover.Positon | Positon | | | | cushion | 定位的偏移量，通常用来预留空间给小箭头等东西 | number | 0 | | | display | 在文档流里的出现形式 | string | 'block' | 所有CSS中合法的display值 | | onShow | 弹层显示后的回掉函数 | func | noop | | | onClose | 弹层关闭后的回掉函数 | func | noop | | | onBeforeShow | 弹层打开前的回掉函数 | func | noop | | | onBeforeClose | 弹层关闭后的回掉函数 | func | noop | | | containerSelector | 弹层的父节点CSS selector | string | 'body' | 所有合法的CSS selector | | className | 自定义额外类名 | string | '' | '' | | prefix | 自定义前缀 | string | 'zent' | null |

Trigger API

每个trigger都可以有特有的API来控制行为，实现自定义trigger的时候可以按需指定trigger的参数。

Trigger.Click API

| 参数 | 说明 | 类型 | 默认值 | 备选值 | |------|------|------|--------|--------| | autoClose | 是否点击‘外面’自动关闭弹层 | bool | true | false, true | | isOutside | 判断一个节点是否在‘外面’，点击在外面会关闭弹层。默认trigger和弹层以外的节点都是‘外面’ | func: Node => bool | () => false | |

Trigger.Hover API

| 参数 | 说明 | 类型 | 默认值 | 备选值 | |------|------|------|--------|--------| | showDelay | 打开弹层前的延迟（单位毫秒），如果在这段时间内鼠标移出弹层范围，弹层不会打开 | number | 150 | | | hideDelay | 关闭弹层前的延迟（单位毫秒），如果在这段时间内鼠标重新移入弹层范围，弹层不会关闭 | number | 150 | | | isOutside | 判断一个节点是否在‘外面’。默认trigger和弹层以外的节点都是‘外面’ | func: Node => bool | () => false | |

Trigger.Focus API

这个trigger没有参数

Trigger.Base

所有trigger的基类，实现自定义trigger需继承这个类，继承时一般需要重写getTriggerProps方法给trigger添加事件，然后在事件 处理函数中打开／关闭弹层。

Trigger的props上有以下API可以在基类中使用。

| 参数 | 说明 | 类型 | 默认值 | 备选值 | |------|------|------|--------|--------| | getTriggerNode | 获取trigger的DOM node | func: () => Node | | | | getContentNode | 获取弹层的DOM node | func: () => Node | | | | open | 打开弹层 | func: () => () | | | | close | 关闭弹层 | func: () => () | | | | contentVisible | 弹层当前是否打开 | bool | | | | onTriggerRefChange | trigger的ref改变的时候需要调用的回掉函数，只有在重写render函数的时候需要这个函数 | func: instance => () | | |

Content API

没有参数，弹层的内容写在Content里。

Position API

Positon是用来给弹层定位的，内置12种定位，可以自定义定位算法。Popover上的cushion参数会影响定位，通常用来加上一定量的偏移量。

                    TopLeft     TopCenter     TopRight

LeftTop                                                             RightTop


LeftCenter                                                          RightCenter


LeftBottom                                                          RightBottom

                BottomLeft     BottomCenter     BottomRight

Position.create

通过这个工厂函数创建自定义的position，这个函数接受一个函数作为参数，函数的原型：

type Position = {
	getCSSStyle: () => object,
	name: string
}

(anchorBoundingBox, containerBoundingBox, contentDimension, options) => Position

示例：

const position = Popover.Position.create((anchorBoundingBox, containerBoundingBox, contentDimension, options) => {
  return {
    getCSSStyle() {
      return {
        position: 'fixed',
        left: 0,
        top: 0,
        opacity: 0
      };
    },

    name: 'position-example'
  };
});

withPopover 高阶组件

这个高阶组件暴露了Popover内部的几个重要方法，可能的使用场景：在Content内部手动关闭弹层。

| 参数 | 说明 | 类型 | 默认值 | 备选值 | |------|------|------|--------|--------| | getTriggerNode | 获取trigger的DOM node | func: () => Node | | | | getContentNode | 获取弹层的DOM node | func: () => Node | | | | open | 打开弹层 | func: () => () | | | | close | 关闭弹层 | func: () => () | | |

示例：

// 点击close按钮可以关闭弹层
const HoverContent = withPopover(function HoverContent({ popover }) {
  return (
    <div>
      <div>popover content</div>
      <button onClick={popover.close}>close</button>
    </div>
  );
});

<Popover position={Popover.Position.RightTop} display="inline">
  <Popover.Trigger.Hover showDelay={500} hideDelay={200}>
    <button style={{ marginLeft: 100 }}>hover on me</button>
  </Popover.Trigger.Hover>
  <PopoverContent>
    <HoverContent />
  </PopoverContent>
</Popover>