cn hx components Overlay

HxOverlay

基础遮罩层组件——基于 Portal 的模态框/抽屉/提示系统。内容通过 HxOverlayPortalRoot 渲染到 document.body。通常通过更高层组件（HxAlert、HxToast、HxPopup）使用。

定位与滑入动画均使用逻辑属性。RTL 方向下抽屉和提示会镜像到对侧边缘：drawer-left 从行首（右侧）滑入，toast-tr 停靠在左上角对应位置等。抽屉/提示的 role 描述的是 LTR 布局，实际位置随 direction: rtl 翻转。

// 对话框，带遮罩
<HxOverlay role="dialog" width="md" hideOnClickBackdrop hideOnEscape>
  <HxOverlayBackdrop />
  <HxOverlayContent>
    <h2>对话框标题</h2>
    <p>内容在这里</p>
  </HxOverlayContent>
</HxOverlay>

// 右侧抽屉
<HxOverlay role="drawer-right" width="md">
  <HxOverlayBackdrop />
  <HxOverlayContent>
    <HxPanel title="设置">...</HxPanel>
  </HxOverlayContent>
</HxOverlay>

// 或使用薄封装组件
<HxDialog width="md" hideOnClickBackdrop hideOnEscape>...</HxDialog>
<HxDrawer position="right" width="xs">...</HxDrawer>

// 通过 position 定位的 Toast
<HxToast position="top-right" message="已保存" />

Props

Prop	类型	默认值	说明
role	HxOverlayRole	—	遮罩层类型（见下）
width	HxSize（'xs' | 'sm' | 'md' | 'lg' | 'xl'）	—	内容宽度
maxHeight	HxSize（'xs' | 'sm' | 'md' | 'lg' | 'xl'）	—	最大内容高度
zIndex	number	1000	CSS z-index
hideOnClickBackdrop	boolean	false	点击遮罩时关闭
hideOnEscape	boolean	false	按 Escape 键时关闭

Role 值

Role	行为
'alert'	居中模态框，带遮罩
'dialog'	居中模态框，带遮罩
'drawer-left'	从左侧滑入
'drawer-right'	从右侧滑入
'drawer-top'	从顶部滑入
'drawer-bottom'	从底部滑入
'toast-tl'	固定左上角
'toast-tr'	固定右上角
'toast-bl'	固定左下角
'toast-br'	固定右下角

封装组件

组件	写入的 role	额外 prop
HxDialog	role="dialog"	—
HxDrawer	由 position 映射	position: 'top' | 'right' | 'bottom' | 'left'（默认 'right'，或配置中的 drawerPosition）

子组件

组件	作用
HxOverlayBackdrop	半透明遮罩，带 CSS 过渡动画
HxOverlayContent	内容容器，带焦点锁定和页面滚动锁定
HxOverlayPortal	通过 React Portal 渲染到 document.body
HxOverlayPortalRoot	Portal 目标 DOM 节点（每个应用包含一次）
HxOverlayInternalProvider	生命周期状态：entering → entered → exiting → exited

原生 DOM 事件

所有子组件转发标准事件。实际中很少需要——遮罩层行为由 props 控制（hideOnEscape、hideOnClickBackdrop、onConfirmed、onDismissed）。

全局配置

import { configHxOverlay } from '@hx/components';
configHxOverlay({ zIndex: 1000, hideOnClickBackdrop: false, hideOnEscape: false, toastPosition: 'top-right', drawerPosition: 'right' });