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/dialog.md.
lynx-ui logo
lynx-ui
  • 简体中文
  • Dialog

    一个适用于 ReactLynx 的无样式对话框组件,提供遮罩渲染、开关状态管理以及进出场动画基础能力。
    Info

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

    弹窗组件,可以设置背景遮罩层。

    基础用法

    结构

    <DialogRoot>
      <DialogTrigger />
      <DialogView>
        <DialogBackdrop />
        <DialogContent>
          <DialogClose />
        </DialogContent>
      </DialogView>
    </DialogRoot>

    组件 API

    DialogRoot

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

    debugLogiOSAndroidHarmony
    类型boolean
    显示调试日志。发现 bug 时开启。
    defaultShowiOSAndroidHarmony
    类型boolean·默认值false
    确定弹窗是否默认显示。使用此属性意味着弹窗处于非受控模式。
    forceMountiOSAndroidHarmony
    类型boolean·默认值false
    即使弹窗未显示,也会挂载弹窗并渲染内容。此时内部状态处于 closed
    onCloseiOSAndroidHarmony
    类型() => void
    当弹出框实际关闭且可能的动画结束时触发。
    onOpeniOSAndroidHarmony
    类型() => void
    当弹出框实际显示且可能的动画结束时触发。
    onShowChangeiOSAndroidHarmony
    类型(open: boolean) => void
    当弹窗即将关闭时触发,可通过点击背景或关闭按钮触发。在受控模式下(提供了 show 属性),您应该使用此处理器来更新控制弹窗可见性的状态。在非受控模式下,此处理器是可选的,会在弹窗内部状态更新之前调用。
    showiOSAndroidHarmony
    类型boolean
    是否显示弹出框。如果未设置此属性,弹出框将处于受控模式,这意味着 defaultShow 属性将无效。并且你必须控制点击关闭按钮和背景的行为。
    childreniOSAndroidHarmony
    类型ReactNode | (status: {animating?: boolean, closed?: boolean, entering?: boolean, leaving?: boolean, open?: boolean}) => ReactNode
    子元素

    基于状态的样式与渲染

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

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

    DialogRoot exposes the following render prop states.

    渲染属性类型说明
    animatingboolean弹层正在执行动画。仅在 transition:true 时生效。
    closedboolean弹层处于关闭状态。如果开启了 forceMount,初始状态会是 ui-closed。
    enteringboolean弹层正在执行进入动画。仅在 transition:true 时生效。
    leavingboolean弹层正在执行离开动画。仅在 transition:true 时生效。
    openboolean弹层处于打开状态。

    DialogTrigger

    The trigger of the dialog. Controls the display of the popper.

    classNameiOSAndroidHarmony
    类型string
    类名
    disablediOSAndroidHarmony
    类型boolean·默认值false
    确定触发组件是否被禁用。当值为 true 时,组件将处于禁用状态,无法进行交互。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名
    childreniOSAndroidHarmony
    类型ReactNode | (status: {active: boolean, busy: boolean}) => ReactNode
    触发组件的内容。它可以是一个返回 ReactNode 的函数,也可以是一个 ReactNode 本身。

    UI variants applied by DialogTrigger based on its render state.

    类名渲染属性类型说明
    ui-activeactiveboolean组合的弹窗按钮处于按下态且未被禁用时生效。
    ui-animating—boolean当 status.animating 为 true 时生效,可用于 `.ui-animating { ... }`。
    ui-busybusyboolean弹窗正在进入或离开时生效。
    ui-closed—boolean当 status.closed 为 true 时生效,可用于 `.ui-closed { ... }`。
    ui-disabled—boolean弹窗按钮被显式禁用或弹窗处于忙碌状态时生效。
    ui-entering—boolean当 status.entering 为 true 时生效,可用于 `.ui-entering { ... }`。
    ui-leaving—boolean当 status.leaving 为 true 时生效,可用于 `.ui-leaving { ... }`。
    ui-open—boolean当 status.open 为 true 时生效,可用于 `.ui-open { ... }`。

    DialogBackdrop

    The backdrop mask of the dialog.

    childreniOSAndroidHarmony
    类型ReactNode
    子元素
    classNameiOSAndroidHarmony
    类型string
    类名
    clickToCloseiOSAndroidHarmony
    类型boolean·默认值true
    确定点击背景是否关闭弹窗。此属性作为背景点击事件的行为开关。当值为 true 时,如果弹窗处于非受控模式(未提供 show 属性),点击背景将触发 onClose 回调并关闭弹窗。当值为 false 时,点击背景将没有任何效果。
    delayed
    类型boolean
    如果内容需要延迟首屏进行首次渲染,则需要将此属性设置为 true。
    dialogBackdropPropsiOSAndroidHarmony
    类型ViewProps
    DialogBackdrop 支持将原始 view 属性直接展开到这个属性中。
    onClickiOSAndroidHarmony
    类型() => void
    点击背景时触发。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名

    UI variants applied by DialogBackdrop.

    类名说明
    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 { ... }`。

    DialogView

    View container. When 'container' is set correctly, the underlying layer will be replaced with overlay; otherwise, it will be a regular view. When the underlying layer is overlay, the 'level' property can be used to control the hierarchical relationship. For a regular view, use 'z-index' to control the hierarchical relationship. If this dialog needs to be used outside of LynxView, consider enabling overlay.

    classNameiOSAndroidHarmony
    类型string
    类名
    containeriOSAndroidHarmony
    类型string
    如果你想在 LynxView 外部使用弹出框,则需要设置此属性。值为原生容器的名称。
    debugLogiOSAndroidHarmony
    类型boolean
    显示调试日志。发现 bug 时开启。
    dialogViewPropsiOSAndroidHarmony
    类型ViewProps | OverlayProps
    将被直接传递到底层 OverlayView 元素的额外 view 或 overlay 属性
    idiOSAndroidHarmony
    类型string
    标识符
    overlayLeveliOSAndroidHarmony
    类型1 | 2 | 3 | 4
    仅当 'container' 设置为非空字符串时有效。调整附近元素的显示层级。
    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 DialogView 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 { ... }`。

    DialogContent

    The main content of the dialog.

    childreniOSAndroidHarmony
    类型ReactNode
    子元素
    classNameiOSAndroidHarmony
    类型string
    类名
    delayed
    类型boolean
    如果内容需要延迟首屏进行首次渲染,则需要将此属性设置为 true。
    dialogContentPropsiOSAndroidHarmony
    类型ViewProps
    DialogContent 支持将原始 view 属性直接展开到这个属性中。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名

    UI variants applied by DialogContent.

    类名说明
    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 { ... }`。

    DialogClose

    The close component of the Dialog, used to close the dialog.

    classNameiOSAndroidHarmony
    类型string
    类名
    disablediOSAndroidHarmony
    类型boolean·默认值false
    确定关闭组件是否被禁用。 当值为 true 时,组件将处于禁用状态,无法进行交互。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    transitioniOSAndroidHarmony
    类型boolean
    如果设置为 true,则 className 会包含 'ui-entering', 'ui-leaving', 'ui-animating' 等动画相关类名
    childreniOSAndroidHarmony
    类型ReactNode | (status: {active: boolean, busy: boolean}) => ReactNode
    关闭组件的内容。它可以是一个返回 ReactNode 的函数,也可以是一个 ReactNode 本身。

    UI variants applied by DialogClose based on its render state.

    类名渲染属性类型说明
    ui-activeactiveboolean组合的弹窗按钮处于按下态且未被禁用时生效。
    ui-animating—boolean当 status.animating 为 true 时生效,可用于 `.ui-animating { ... }`。
    ui-busybusyboolean弹窗正在进入或离开时生效。
    ui-closed—boolean当 status.closed 为 true 时生效,可用于 `.ui-closed { ... }`。
    ui-disabled—boolean弹窗按钮被显式禁用或弹窗处于忙碌状态时生效。
    ui-entering—boolean当 status.entering 为 true 时生效,可用于 `.ui-entering { ... }`。
    ui-leaving—boolean当 status.leaving 为 true 时生效,可用于 `.ui-leaving { ... }`。
    ui-open—boolean当 status.open 为 true 时生效,可用于 `.ui-open { ... }`。
    除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。