Lynx UI logo
Lynx UI

<Sheet>

一个适用于 ReactLynx 的方向性 Sheet 组件,支持底部面板、侧边抽屉、拖拽交互和吸附点基础能力。
  • 支持受控与非受控两种显示方式。
  • 支持吸附点配置,包括百分比高度与内容自适应高度。
  • 支持通过 SheetRootRef 进行命令式控制。
Info

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

Sheet 是用于上下文操作、详情面板和临时流程的滑动面板。它支持底部面板、顶部面板、侧边抽屉、吸附点、拖拽、点击遮罩关闭,以及受控和命令式两种使用方式。

基本用法

SheetRootSheetViewSheetBackdropSheetContent 开始。将视觉面板放在 SheetContent 上,再用遮罩和拖拽手势完成自然关闭。

自动高度

当面板高度应跟随内容变化时,使用 fit 吸附点。它适合菜单、短表单,以及高度无法提前确定的内容。

受控状态

当打开状态属于页面时,使用 showonShowChange。如果其他 UI、埋点或导航逻辑需要与面板状态同步,这就是合适的模型。

不同方向

使用 side 选择 Sheet 是底部面板、顶部面板还是抽屉。需要跟随 RTL 布局时优先使用 startend,必须固定物理边缘时使用 leftright

命令式控制

当父级需要直接控制面板时,使用 SheetRootRefopenclosesnapToexpandcollapse 适合工具栏操作或多步骤流程联动。

结构

<SheetRoot>
  <SheetView>
    <SheetBackdrop />
    <SheetContent>
      <SheetHandle />
    </SheetContent>
  </SheetView>
</SheetRoot>

API

SheetRoot

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

children
iOS
Android
Harmony
类型ReactNode
子元素
claimedGestureAngles
类型undefined[]
Sheet 主动接管手势的角度范围(单位:度)。 每个条目都是 [最小角度, 最大角度]。 落在这些范围内的手势会驱动 Sheet 移动,范围外的手势则继续透传给子组件。
className
iOS
Android
Harmony
类型string
类名
defaultShow
iOS
Android
Harmony
类型boolean·默认值false
Sheet 是否默认显示。使用此属性表示 Sheet 处于非受控模式。
dismissThreshold
类型number
Sheet 关闭的阈值。
dragDisabled
类型boolean
是否禁用 Sheet 的拖拽。
enableDragToClose
类型boolean
是否允许拖拽关闭 Sheet。 如果为 true,从最低吸附点向关闭边缘拖动将线性移动并允许关闭。 如果为 false,向关闭边缘拖动将触发橡皮筋效果并回弹。
enableRTL
类型boolean·默认值false
是否以 RTL 模式解析逻辑抽屉方向。为 false 时,start 为左侧、end 为右侧;为 true 时,start 为右侧、end 为左侧。物理 leftright 不受 enableRTL 影响。
forceMount
iOS
Android
Harmony
类型boolean·默认值false
即使 Sheet 未显示也挂载并渲染内容。Sheet 仍保持关闭状态。
handleOnly
类型boolean
是否仅允许通过手柄拖拽。
initialSnap
类型number
初始吸附点索引。
onClose
iOS
Android
Harmony
类型() => void
当 Sheet 完全关闭且退出动画结束时触发。
onOpen
iOS
Android
Harmony
类型() => void
当 Sheet 完全打开且入场动画结束时触发。
onShowChange
iOS
Android
Harmony
类型(open: boolean) => void
当 Sheet 可见性即将改变时触发(例如点击背景、滑动关闭、关闭按钮)。 在受控模式下,使用此回调更新状态。在非受控模式下,此回调可选。
onSnapChange
类型(index: number, value: number) => void
吸附点变化时的回调。 value 表示换算后的像素值。
rubberBand
类型number | boolean | [object Object]
橡皮筋效果配置。 默认情况下,垂直 Sheet(top / bottom)启用橡皮筋效果,水平抽屉(left / right / start / end)禁用。 如果为 true,启用默认橡皮筋效果(系数 0.5)。 如果为 false,禁用橡皮筋效果。 如果为数字,启用指定系数的橡皮筋效果。 如果为对象,允许指定系数和最大距离。
screenHeight
类型number
Sheet 容器的高度(屏幕高度)。 在垂直模式(top / bottom)下,用于计算百分比吸附点和关闭阈值。
screenWidth
类型number
Sheet 容器的宽度(屏幕宽度)。在水平抽屉模式(left / right / start / end)中用于百分比吸附点和关闭计算。
show
iOS
Android
Harmony
类型boolean
是否显示 Sheet。如果设置此属性,Sheet 将处于受控模式,defaultShow 属性将不生效。 您必须根据用户交互更新此属性来控制可见性。
side
类型SheetSide·默认值'bottom'
Sheet 进入的边。bottom 保持现有底部弹层行为,top 提供顶部弹层行为,leftright 提供物理抽屉方向,startend 提供逻辑抽屉方向并根据 enableRTL 解析。
snapPoints
类型undefined[]·默认值['fit']
Sheet 的吸附点。可以是像素数值、百分比或 'fit'。 - 数字被视为像素值 - 百分比(例如 '50%')在 top / bottom 模式下相对于屏幕高度,在 left / right / start / end 模式下相对于屏幕宽度 - 'fit' 在 top / bottom 模式下动态解析为测量的内容高度,在 left / right / start / end 模式下动态解析为测量的内容宽度 索引顺序与该数组顺序一致。
style
iOS
Android
Harmony
类型CSSProperties
样式

SheetBackdrop

The backdrop mask of the Sheet.

children
iOS
Android
Harmony
类型ReactNode
子元素
className
iOS
Android
Harmony
类型string
类名
clickToClose
iOS
Android
Harmony
类型boolean·默认值true
点击遮罩时是否关闭 Sheet。
onClick
iOS
Android
Harmony
类型() => void
点击背景时触发。
style
iOS
Android
Harmony
类型CSSProperties
样式

SheetView

The view container of the Sheet. Can be x-overlay-ng or view. Controls the Sheet's overlay layer and stacking order.

children
iOS
Android
Harmony
类型ReactNode
子元素
className
iOS
Android
Harmony
类型string
类名
container
iOS
Android
Harmony
类型'spark' | 'bullet' | 'bulletPopup' | (string & {})
如果需要将 Sheet 渲染到 LynxView 外部,请设置此属性。 'spark''bullet''bulletPopup' 都是原生容器名称。 例如在 TikTok 中通常应设置为 'spark',在抖音中通常应设置为 'bullet'。 在 iOS 上,这个属性也可以是任意一个用于承载 Sheet 的原生视图控制器。 通过它可以将 Sheet 放到正确的原生层级中。
id
iOS
Android
Harmony
类型string
标识符
nativeProps
iOS
Android
Harmony
类型OverlayViewProps | ViewProps
会透传到底层元素的额外属性。
overlayLevel
iOS
Android
Harmony
类型2 | 1 | 3 | 4
仅当 container 为非空字符串时生效。 用于调整周边元素的显示层级。
style
iOS
Android
Harmony
类型CSSProperties
样式

SheetContent

The main content of the Sheet.

children
iOS
Android
Harmony
类型ReactNode
子元素
className
iOS
Android
Harmony
类型string
类名
enterAnimation
类型SheetTransition
Sheet 进入动画配置。
exitAnimation
类型SheetTransition
Sheet 退出动画配置。
innerClassName
iOS
Android
Harmony
类型string
内层容器的 CSS 类名。 用于设置内容区域的布局和尺寸样式。 在水平抽屉模式下,应在这里设置抽屉宽度,这样 'fit' 才能根据测量得到的抽屉宽度完成解析。
innerStyle
iOS
Android
Harmony
类型CSSProperties
内层容器的内联样式。 用于设置内容区域的布局和尺寸样式。 注意:背景、圆角等视觉样式应通过主 style 属性设置,该属性会应用到移动的 surface 层。 在水平抽屉模式下,应在这里设置抽屉宽度,这样 'fit' 才能根据测量得到的抽屉宽度完成解析。
snapAnimation
类型SheetTransition
Sheet 动画的过渡配置。
style
iOS
Android
Harmony
类型CSSProperties
样式
除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。