触发器 Trigger
用于对元素添加 hover, click, focus 等事件，并且弹出下拉框。
安装
npm install @arco-design/web-react@2.66.18
在入口引入 @arco-design/web-react/dist/css/arco.css，用 ConfigProvider 设置语言。React 19 项目还需在入口最先引入 @arco-design/web-react/es/_util/react-19-adapter，否则 Message、Modal 等命令式 API 无法渲染。
示例
- 基础用法：这个例子展示了触发器的最基础的使用。
Trigger组件默认是没有弹出框的样式的。以下示例均为官网添加的样式。 - 受控用法：这个例子展示了如何完全控制弹出层的展示和隐藏。 可以通过
defaultPopupVisible设置默认的展开状态。 - 多层嵌套：弹出层可以嵌套在另一个弹出层内。
- 多个触发方式：通过
trigger传入数组，可以设置多个触发方式。 - 跟随鼠标显示弹出层：设置
alignPoint属性，可以使弹出层出现在鼠标位置。你可能想要trigger=click时候，在范围内点击时，弹出层一直展示，并根据鼠标位置更新弹出层位置，可以查看下一个示例。 - 更新位置
- 展示箭头元素：通过
showArrow属性，可以展示默认的箭头元素。也可以通过 arrowProps 进行定制。 - 设置弹窗位置偏移量：通过
popupAlign属性，可以设置弹窗在原本位置的基础上进行额外的位置调整。 例如position=top时， 设置popupAlign={top: 20}，弹窗会向上移动20px。设置popupAlign={ top: [100, 20] }，弹窗将会在水平方向移动100px，并向上移动20px。 - 滚动容器：通过设置
updateOnScroll监听容器的滚动。 - 到视口指定距离时调整定位：默认弹出层位置会根据视口边界进行定位及微调，
boundaryDistance参数可以设置到视口边界一定距离时即进行定位调整。仅在 autoFitPosition=true 且 alignPoint=false 生效。 根据position不同传入对应的boundaryDistance。如 position='right' 传入boundaryDistance={right: 200, ['top' | 'bottom']: xxx}，position='top' 传入boundaryDistance={top: 200, ['left' | 'right']: xxx}
示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。
API
Trigger
| 参数名 | 描述 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| alignPoint | 弹出层跟随鼠标位置 | boolean | - | - |
| autoAlignPopupMinWidth | 自动对齐子元素的宽度设置弹出框的最小宽度 | boolean | - | - |
| autoAlignPopupWidth | 自动对齐子元素的宽度设置弹出框的宽度 | boolean | - | - |
| autoFitPosition | 是否根据空间自动调整弹出框的位置。 | boolean | true | - |
| autoFixPosition | 当内容发生变化导致内容区域尺寸发生变化，自动进行重新定位。 | boolean | true | - |
| blurToHide | 是否在触发节点失去焦点的时候关闭弹出框，仅在 trigger 中含有 focus 时生效 | boolean | true | - |
| clickToClose | 是否能通过点击触发节点来关闭弹出框。trigger 包含 click, contextMenu 时，默认为 true。否则为 false | boolean | - | - |
| containerScrollToClose | 是否在容器滚动时关闭弹出框 | boolean | - | 2.34.0 |
| defaultPopupVisible | 默认弹出框开启或关闭 | boolean | - | - |
| disabled | 是否禁用 | boolean | - | - |
| escToClose | 是否允许按 ESC 键关闭弹出框。 | boolean | - | - |
| mouseLeaveToClose | 是否在鼠标移出触发节点和弹出层的时候关闭弹出层 | boolean | true | 2.22.0 |
| popupHoverStay | 是否在鼠标移出触发节点，移入弹出框时保留弹出框。 | boolean | true | - |
| popupVisible | 设置弹出框开启或关闭 | boolean | - | - |
| showArrow | 是否展示箭头元素 | boolean | - | - |
| unmountOnExit | 隐藏后是否销毁 DOM 结构 | boolean | true | - |
| updateOnScroll | 是否在容器滚动时更新弹出框的位置 | boolean | - | 2.32.0 |
| focusDelay | focus 触发延时的毫秒数 | number | - | - |
| mouseEnterDelay | mouseenter 触发延时的毫秒数 | number | 100 | - |
| mouseLeaveDelay | mouseleave 触发延时的毫秒数 | number | 100 | - |
| childrenPrefix | 设置这个参数后，打开弹出后，children 上会添加一个名为 ${childrenPrefix}-open 的类。 | string | - | - |
| classNames | 动画类名 | string | fadeIn | - |
| position | 弹出位置，一共有 12 个方位可供选择 | | 'top'| 'tl'| 'tr'| 'bottom'| 'bl'| 'br'| 'left'| 'lt'| 'lb'| 'right'| 'rt'| 'rb' | bottom | - |
| trigger | 触发方式 | | 'hover'| 'click'| 'focus'| 'contextMenu'| Array<'hover' | 'click' | 'focus' | 'contextMenu'> | hover | - |
| arrowProps | 箭头元素的所有 html 参数 | HTMLAttributes<HTMLDivElement> | - | - |
| boundaryDistance | 默认弹出层位置会根据视口边界进行定位及微调，此参数可以设置到视口边界一定距离时即进行定位调整。仅在 autoFitPosition=true 且 alignPoint=false 生效。 | | { left?: number; bottom?: number }| { left?: number; top?: number }| { right?: number; bottom?: number }| { right?: number; top?: number } | - | 2.59.0 |
| className | 节点类名 | string | string[] | - | - |
| clickOutsideToClose | 是否在点击空白处（触发节点和弹出框以外的区域）时关闭弹出层。 关闭时会触发 onVisibleChange。默认是在冒泡阶段触发该逻辑，可设置 { capture: true } 指定捕获阶段触发 | boolean | { capture: boolean } | true | { capture: boolean } in 2.55.0 |
| duration | 动画过渡时间 | number | { exit?: number; enter?: number; appear?: number } | 200 | - |
| onClickOutside | 点击触发节点和弹出框以外的区域的回调。 | Function | - | - |
| popupAlign | 调整弹出框的位置，有四个属性值，left, right, top, bottom，分别表示向该方向移动几个像素。具体可查看 示例 | {left?: number | [number, number];right?: number | [number, number];top?: number | [number, number];bottom?: number | [number, number];} | {} | - |
| popupStyle | 弹出框（内部）的样式 | CSSProperties | - | - |
| style | 弹出框（外部）的样式 | CSSProperties | - | - |
| getDocument | 在该元素上执行 clickOutside，触发弹出框关闭 | () => Element | () => window.document | - |
| getPopupContainer | 设置弹出内容所插入的父元素 | (node: HTMLElement) => Element | - | - |
| onClick | 按钮点击事件（trigger 包含 click 时生效） | (e) => void | - | - |
| onVisibleChange | 显示或隐藏时触发的回调 | (visible: boolean) => void | - | - |
| popup | 弹出框的内容 | () => ReactNode | - | - |
onVisibleChange的触发时机说明
-
trigger包含click时- 鼠标点击空白处，会触发
onVisibleChange，隐藏弹出层。设置clickOutsideToClose=false可以阻止触发。 - 鼠标点击触发节点，例如示例中的
Button，会触发onVisibleChange，隐藏/显示弹出层。在弹出层展示状态下，如果设置clickToClose=false，则再点击触发节点，将不会隐藏弹出层。
也可以不设置onVisibleChange，完全由外部控制是否显示。
- 鼠标点击空白处，会触发
-
trigger包含contextMenu时- 鼠标点击空白处，会触发
onVisibleChange，隐藏弹出层。设置clickOutsideToClose=false可以阻止触发。 - 在children上鼠标点击右键，会触发
onVisibleChange，显示弹出层。
- 鼠标点击空白处，会触发
-
trigger包含hover时- 鼠标从弹出层移出，并未在
mouseLeaveDelay时间内移入触发节点，会触发onVisibleChange，隐藏弹出层。 - 鼠标从触发节点移出，并未在
mouseLeaveDelay时间内移入弹出层，会触发onVisibleChange，隐藏弹出层。
**如果设置了
popupHoverStay=false，则鼠标无法移入弹出层。在trigger包含hover时，点击空白处不会隐藏弹窗，因为可能引起onVisibleChange被多次触发。可以在 onClickOutside 执行必要的逻辑 ** - 鼠标从弹出层移出，并未在
-
trigger包含focus时- 触发节点失去焦点，就会触发
onVisibleChange，隐藏弹出层。 - 当设置
blurToHide=false时，点击空白处会触发onVisibleChange，隐藏弹出层。设置clickOutsideToClose=false可以阻止触发。
如果不期望失去焦点隐藏弹出层，可设置
blurToHide=false - 触发节点失去焦点，就会触发
常见问题
- 设置了
getPopupContainer后，弹出层位置不对？ 组件默认autoFitPosition属性为true，也就是说组件会根据弹出层的尺寸，在视口中的位置以及所挂载的父元素来自动调整弹出层的位置。 例如设置position=top，但是上方空间不足，弹出层会被遮住，组件就会根据情况来判断是否将弹出层展示在触发元素的下方。 如果设置了getPopupContainer，弹出层的样式属性left最小为0，也就是最小距离父元素的左边界为0，避免超出父元素，导致被遮挡。