参数

参数	类型	默认值	说明
placement	'above' | 'below' | 'start' | 'end' | MaybeRefOrGetter	'below'	浮层落在触发器的哪一侧。逻辑方向：start / end 在 RTL 下自动镜像。空间不够时翻到对面。
alignment	'start' | 'center' | 'end' | MaybeRefOrGetter	'start'	沿方位轴的对齐方式。
isOpen	boolean | undefined | MaybeRefOrGetter	—	受控的打开状态。不传就由 hook 自己管。
isEnabled	boolean | MaybeRefOrGetter	true	触发器点击是否打开浮层。
hasLightDismiss	boolean | MaybeRefOrGetter	true	点击外部是否关闭。
hasEscapeDismiss	boolean | MaybeRefOrGetter	true	按 Escape 是否关闭。
hasAutoFocus	boolean | MaybeRefOrGetter	true	打开后是否把焦点移到内容里第一个真正的操作控件。对话框里没有可聚焦元素时，焦点落到内容容器上。
closeButtonSelector	string	—	初始焦点要跳过的控件选择器，比如组件自带的关闭按钮。
dialogLabel	string | MaybeRefOrGetter	—	弹出层对话框的无障碍名称。没有可见标题时要传。
role	'dialog' | 'none' | MaybeRefOrGetter	'dialog'	内容容器的 ARIA role。菜单、列表框这类自己带 role、且触发器自己保留焦点的弹层用 none。
isModal	boolean | MaybeRefOrGetter	true	role="dialog" 时是否模态（aria-modal）。
onShow	() => void	—	浮层显示后调用。
onHide	() => void	—	浮层隐藏后调用。需要时用它把焦点还给触发器。

返回值

字段	类型	说明
isOpen	Ref<boolean>	浮层当前是否打开。
triggerRef	Ref<HTMLElement | null>	负责打开浮层的元素。用 :ref 绑上去，hook 会挂事件和 ARIA 属性。
anchorRef	Ref<HTMLElement | null>	定位用的锚点。没设时退回到 triggerRef。
contentRef	Ref<HTMLElement | null>	浮层内容容器，焦点陷阱和关闭逻辑都靠它。
id	string	浮层的唯一 ID，用于 aria-controls。
anchorId	string	锚点的 CSS 标识，用于高级定位场景。
contentStyle	ComputedRef<CSSProperties>	浮层的内联坐标，摊到内容元素的 style 上。
resolvedPlacement	ComputedRef<'above' | 'below' | 'start' | 'end'>	考虑空间翻转之后实际生效的方位。
surfaceProps	ComputedRef<Record<string, unknown>>	内容元素的属性：id、role、aria-modal、aria-label、tabindex。
triggerProps	ComputedRef<Record<string, unknown>>	hook 自动写到 triggerRef 上的 ARIA 属性：aria-haspopup、aria-expanded、aria-controls。
show	() => void	主动打开浮层。
hide	() => void	主动关闭浮层。
toggle	() => void	在打开和关闭之间切换。