For AI agents: the complete documentation index is available at /next/zh/llms.txt, the full documentation bundle is available at /next/zh/llms-full.txt, and this page is available as Markdown at /next/zh/ui/components/popover.md.
lynx-ui logo
lynx-ui
  • 简体中文
  • Popover

    一个适用于 ReactLynx 的无样式气泡浮层组件,提供定位和锚点追踪基础能力。
    Info

    你可以查看源码来了解它的运行原理,也欢迎大家提 PR 来丰富其能力。

    基础用法

    示例

    动画过渡

    使用弹簧进入与补间退出过渡,为浮层内容添加动画。

    额外锚点

    如果您想添加额外的锚点,可以使用 PopoverAnchor 组件。

    交叉轴偏移调整

    在 PopoverPositioner 上使用 crossAxisOffset 来设置浮动元素的交叉轴偏移量。

    结构

    <PopoverRoot>
      <PopoverTrigger />
      <PopoverAnchor />
      <PopoverPositioner>
        <PopoverBackdrop />
        <PopoverContent>
          <PopoverArrow />
        </PopoverContent>
      </PopoverPositioner>
    </PopoverRoot>

    组件 API

    PopoverRoot

    The root component of the Popover, containing all of its child components.

    childreniOSAndroidHarmony
    类型ReactNode
    子元素
    classNameiOSAndroidHarmony
    类型string
    类名
    debugLogiOSAndroidHarmony
    类型boolean
    开启 Popover 及其子组件的调试日志。
    defaultShowiOSAndroidHarmony
    类型boolean
    确定对话框是否默认显示。使用此属性意味着对话框是非受控的。
    forceMountiOSAndroidHarmony
    类型boolean·默认值false
    即使弹窗未显示,也会挂载弹窗并渲染内容。此时内部状态处于 closed
    onCloseiOSAndroidHarmony
    类型() => void
    当 Popover 关闭时触发
    onOpeniOSAndroidHarmony
    类型() => void
    当 Popover 显示时触发
    onVisibleChangeiOSAndroidHarmony
    类型(visible: boolean) => void
    Popover 显示状态改变时触发的回调,仅在受控模式下被调用。
    showiOSAndroidHarmony
    类型boolean
    确定是否应显示对话框。使用此属性意味着对话框是受控的。请勿与 'defaultShow' 属性一起使用。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式

    PopoverTrigger

    The element that triggers the Popover to show.

    childreniOSAndroidHarmony
    类型ReactNode
    子元素
    classNameiOSAndroidHarmony
    类型string
    类名
    disabled
    类型boolean
    禁用此触发器
    onClickiOSAndroidHarmony
    类型() => void
    组件被点击时触发的回调函数
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名

    基于状态的样式与渲染

    该组件通过以下一种或两种方式暴露运行时状态。下表仅展示每个状态实际支持的方式:

    • UI variant class:支持时,对应组件节点会动态加上 ui-<state> 形式的类名,可用 .ui-<state> { ... } 选择器定制样式;
    • Render-prop 字段:支持时,当 children 传入函数,状态会以 children({ <state>: boolean, ... }) 的形式作为参数传入,便于在运行时做条件渲染。

    UI variants applied by PopoverTrigger.

    类名说明
    ui-active组合的触发按钮处于按下态且未被禁用时生效。
    ui-animating当 status.animating 为 true 时生效,可用于 `.ui-animating { ... }`。
    ui-busyPopover 正在进入或离开时生效。
    ui-closed当 status.closed 为 true 时生效,可用于 `.ui-closed { ... }`。
    ui-disabled触发器被禁用时生效。
    ui-entering当 status.entering 为 true 时生效,可用于 `.ui-entering { ... }`。
    ui-leaving当 status.leaving 为 true 时生效,可用于 `.ui-leaving { ... }`。
    ui-open当 status.open 为 true 时生效,可用于 `.ui-open { ... }`。

    PopoverAnchor

    If this component is used, the Popover will use it rather than PopoverTrigger as the real anchor.

    childreniOSAndroidHarmony
    类型ReactNode
    子元素
    classNameiOSAndroidHarmony
    类型string
    类名
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名

    UI variants applied by PopoverAnchor.

    类名说明
    ui-animating当 status.animating 为 true 时生效,可用于 `.ui-animating { ... }`。
    ui-closed当 status.closed 为 true 时生效,可用于 `.ui-closed { ... }`。
    ui-entering当 status.entering 为 true 时生效,可用于 `.ui-entering { ... }`。
    ui-leaving当 status.leaving 为 true 时生效,可用于 `.ui-leaving { ... }`。
    ui-open当 status.open 为 true 时生效,可用于 `.ui-open { ... }`。

    PopoverPositioner

    Helps position the Content and Arrow correctly.

    autoAdjustiOSAndroidHarmony
    类型size | shift
    Popover 的自动调整策略。默认为 'size',会根据 Popover 大小自动调整 maxHeight/maxWidth;'shift' 会根据 Popover 的宽度/高度自动调整位置。
    classNameiOSAndroidHarmony
    类型string
    类名
    crossAxisOffsetiOSAndroidHarmony
    类型number
    额外的 crossAxis 偏移量。如果设置了此属性,Popover 会在 crossAxis 方向上额外偏移指定的量。
    placementiOSAndroidHarmony
    类型Placement
    Popover 的位置
    placementOffsetiOSAndroidHarmony
    类型number
    Popover 位置的偏移量
    popoverPositionerPropsiOSAndroidHarmony
    类型ViewProps | OverlayProps
    popoverPositioner 支持将原始 view 或 overlay 属性直接展开到这个属性中。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名
    childreniOSAndroidHarmony
    类型ReactNode | (status: {open?: boolean, closed?: boolean, leaving?: boolean, entering?: boolean, animating?: boolean}) => ReactNode
    子元素

    UI variants applied by PopoverPositioner based on its render state.

    类名渲染属性类型说明
    ui-animatinganimatingboolean弹层正在执行动画。仅在 transition:true 时生效。 当 status.animating 为 true 时生效,可用于 `.ui-animating { ... }`。
    ui-closedclosedboolean弹层处于关闭状态。如果开启了 forceMount,初始状态会是 ui-closed。 当 status.closed 为 true 时生效,可用于 `.ui-closed { ... }`。
    ui-enteringenteringboolean弹层正在执行进入动画。仅在 transition:true 时生效。 当 status.entering 为 true 时生效,可用于 `.ui-entering { ... }`。
    ui-leavingleavingboolean弹层正在执行离开动画。仅在 transition:true 时生效。 当 status.leaving 为 true 时生效,可用于 `.ui-leaving { ... }`。
    ui-openopenboolean弹层处于打开状态。 当 status.open 为 true 时生效,可用于 `.ui-open { ... }`。

    PopoverBackdrop

    A transparent backdrop that can be used to close the Popover when clicked.

    childreniOSAndroidHarmony
    类型ReactNode
    子元素
    classNameiOSAndroidHarmony
    类型string
    类名
    onClickiOSAndroidHarmony
    类型() => void
    组件被点击时触发的回调函数
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名

    UI variants applied by PopoverBackdrop.

    类名说明
    ui-active组合的背景按钮处于按下态且未被禁用时生效。
    ui-animating当 status.animating 为 true 时生效,可用于 `.ui-animating { ... }`。
    ui-closed当 status.closed 为 true 时生效,可用于 `.ui-closed { ... }`。
    ui-disabled未使用动画内容且 Popover 正在进入或离开时生效。
    ui-entering当 status.entering 为 true 时生效,可用于 `.ui-entering { ... }`。
    ui-leaving当 status.leaving 为 true 时生效,可用于 `.ui-leaving { ... }`。
    ui-open当 status.open 为 true 时生效,可用于 `.ui-open { ... }`。

    PopoverContent

    The content of the Popover.

    childreniOSAndroidHarmony
    类型ReactNode
    子元素
    classNameiOSAndroidHarmony
    类型string
    类名
    popoverContentPropsiOSAndroidHarmony
    类型ViewProps
    PopoverContent 支持将原始 view 属性直接展开到这个属性中。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名

    UI variants applied by PopoverContent.

    类名说明
    ui-animating当 status.animating 为 true 时生效,可用于 `.ui-animating { ... }`。
    ui-closed当 status.closed 为 true 时生效,可用于 `.ui-closed { ... }`。
    ui-entering当 status.entering 为 true 时生效,可用于 `.ui-entering { ... }`。
    ui-leaving当 status.leaving 为 true 时生效,可用于 `.ui-leaving { ... }`。
    ui-open当 status.open 为 true 时生效,可用于 `.ui-open { ... }`。

    PopoverMotionContent

    Motion-driven content. It owns opacity when an opacity target is specified, and transform when a transform target is specified. It stays mounted until all exit properties complete. Use one motion content per popover root.

    childreniOSAndroidHarmony
    类型ReactNode
    子元素
    classNameiOSAndroidHarmony
    类型string
    类名
    motioniOSAndroidHarmony
    类型PopoverMotionOptions
    Initial, opening and closing values, with an optional shared transition.
    popoverContentPropsiOSAndroidHarmony
    类型ViewProps
    PopoverContent 支持将原始 view 属性直接展开到这个属性中。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名

    UI variants applied by PopoverMotionContent.

    类名说明
    ui-animating当 status.animating 为 true 时生效,可用于 `.ui-animating { ... }`。
    ui-closed当 status.closed 为 true 时生效,可用于 `.ui-closed { ... }`。
    ui-entering当 status.entering 为 true 时生效,可用于 `.ui-entering { ... }`。
    ui-leaving当 status.leaving 为 true 时生效,可用于 `.ui-leaving { ... }`。
    ui-open当 status.open 为 true 时生效,可用于 `.ui-open { ... }`。

    PopoverArrow

    The arrow of the Popover.

    childreniOSAndroidHarmony
    类型ReactNode
    自定义箭头,旋转前朝下,布局尺寸应与 size 一致。color 仅作用于默认三角形。PopoverArrow 应作为 PopoverContent 的直接子节点,确保定位以气泡为参照。
    classNameiOSAndroidHarmony
    类型string
    类名
    coloriOSAndroidHarmony
    类型string·默认值'black'
    箭头的颜色。默认为 'black'
    offsetiOSAndroidHarmony
    类型number·默认值0
    调整箭头在 PopoverContent 边缘上的定位偏移,例如可用于避让圆角。
    sizeiOSAndroidHarmony
    类型number | {height: number, width: number}
    箭头尺寸。数字保持原有正方形定位盒及同等突出距离。自定义箭头的 { width, height } 表示旋转前的底边宽度和突出高度;左右方向由底层自动旋转。未传 children 时,对象尺寸仍取最大值绘制默认三角形。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名

    UI variants applied by PopoverArrow.

    类名说明
    ui-animating当 status.animating 为 true 时生效,可用于 `.ui-animating { ... }`。
    ui-closed当 status.closed 为 true 时生效,可用于 `.ui-closed { ... }`。
    ui-entering当 status.entering 为 true 时生效,可用于 `.ui-entering { ... }`。
    ui-leaving当 status.leaving 为 true 时生效,可用于 `.ui-leaving { ... }`。
    ui-open当 status.open 为 true 时生效,可用于 `.ui-open { ... }`。

    辅助类型

    PopoverOverlayProps

    The view container of the Popover. Can be overlay or view. Controls the z-index of the popover.

    childreniOSAndroidHarmony
    类型ReactNode | (status: {open?: boolean, closed?: boolean, leaving?: boolean, entering?: boolean, animating?: boolean}) => ReactNode
    子元素
    classNameiOSAndroidHarmony
    类型string
    类名
    containeriOSAndroidHarmony
    类型string
    Popover 覆盖层的父容器
    placementiOSAndroidHarmony
    类型Placement
    Popover 的位置
    placementOffsetiOSAndroidHarmony
    类型number
    Popover 覆盖层位置的偏移量
    popoverOverlayPropsiOSAndroidHarmony
    类型ViewProps
    PopoverOverlay 支持将原始 view 属性直接展开到这个属性中。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名

    PopoverMotionOptions

    Motion targets and their shared default transition.

    closeiOSAndroidHarmony
    类型PopoverMotionTarget
    Target values when closing. Its transition overrides the shared default.
    initialiOSAndroidHarmony
    类型PopoverMotionValues
    Visual values applied on each fresh mount.
    openiOSAndroidHarmony
    类型PopoverMotionTarget
    Target values when opening. Its transition overrides the shared default.
    transitioniOSAndroidHarmony
    类型PopoverMotionTransition
    Default transition for targets without their own transition.

    PopoverMotionValues

    Numeric visual properties supported by PopoverMotionContent.

    opacityiOSAndroidHarmony
    类型number
    Opacity.
    rotateiOSAndroidHarmony
    类型number
    Rotation in degrees.
    scaleiOSAndroidHarmony
    类型number
    Uniform scale.
    scaleXiOSAndroidHarmony
    类型number
    Horizontal scale.
    scaleYiOSAndroidHarmony
    类型number
    Vertical scale.
    xiOSAndroidHarmony
    类型number
    Horizontal translation in logical pixels.
    yiOSAndroidHarmony
    类型number
    Vertical translation in logical pixels.

    PopoverMotionTarget

    A visual target and its transition settings.

    opacityiOSAndroidHarmony
    类型number
    Opacity.
    rotateiOSAndroidHarmony
    类型number
    Rotation in degrees.
    scaleiOSAndroidHarmony
    类型number
    Uniform scale.
    scaleXiOSAndroidHarmony
    类型number
    Horizontal scale.
    scaleYiOSAndroidHarmony
    类型number
    Vertical scale.
    transitioniOSAndroidHarmony
    类型PopoverMotionTransition
    Defaults to a spring with stiffness 300, damping 30 and mass 1.
    xiOSAndroidHarmony
    类型number
    Horizontal translation in logical pixels.
    yiOSAndroidHarmony
    类型number
    Vertical translation in logical pixels.

    PopoverMotionTransition

    PopoverMotionTransitioniOSAndroidHarmony
    类型({ type: 'spring', stiffness?: number, damping?: number, mass?: number, velocity?: number } | { type: 'tween', duration?: number, ease?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' })
    Spring physics or tween timing. Durations are in seconds. A tween defaults to 0.3 seconds and easeOut when its duration or easing is omitted.
    除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。