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

    一个适用于 ReactLynx 的 Slider 组件包,优先提供可组合的基础能力,同时支持单值滑块和双拇指区间滑块。
    Info

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

    基础用法

    使用基础原语组合不同样式、禁用状态和从右到左的滑块。

    示例

    受控模式

    从外部控制滑块值,跳转到预设值,并按固定步长吸附。

    动态宽度

    在滑块容器宽度变化时正确重新测量轨道。

    Facade

    将滑块原语封装为可复用组件,并支持替换拇指内容。

    价格区间

    构建带实时值、提交值和预设选项的步进双拇指区间滑块。

    进度

    省略拇指,将滑块原语复用为只读进度指示器。

    形状

    通过定制轨道、指示器和拇指样式构建不同视觉形态。

    与 ScrollView 组合

    在横向与纵向嵌套滚动区域中保持滑块的水平拖动手势。

    结构

    单值滑块使用一个拇指。

    <SliderRoot>
      <SliderTrack>
        <SliderIndicator />
        <SliderThumb />
      </SliderTrack>
    </SliderRoot>

    区间滑块使用两个带索引的拇指。

    <SliderRoot value={range}>
      <SliderTrack>
        <SliderIndicator />
        <SliderThumb index={0} />
        <SliderThumb index={1} />
      </SliderTrack>
    </SliderRoot>

    组件 API

    SliderRoot

    Root primitive props for a single-value or range slider. The generic selects the value shape and defaults to number for existing single-value usage. A range slider must provide its tuple through either value or defaultValue so the runtime can determine the shape. Range-thumb collision behavior is intentionally non-crossing: thumbs may meet, but the active thumb stops at the other value without swapping or pushing the other thumb.

    children
    类型ReactNode
    子原语组件组合,通常为:SliderTrack 内包含 SliderIndicator 以及可选的 SliderThumb。
    classNameiOSAndroidHarmony
    类型string
    类名
    defaultValue
    类型number | SliderRangeValue·默认值0
    非受控模式下的初始值。省略时,单值滑块从 0 开始;区间滑块必须提供二元组。
    disabled
    类型boolean·默认值false
    禁用滑块,阻止指针/触摸交互。
    enableRTL
    类型boolean·默认值false
    启用从右到左的布局。为 true 时,滑块范围从右向左增长。
    onDragging
    类型(value: number | SliderRangeValue) => void
    拖拽状态变化时触发,传入当前滑块值。开始拖拽和结束拖拽时都会触发。
    onValueChange
    类型(value: number | SliderRangeValue, source: SliderValueChangeSource) => void
    由滑块自身驱动的值更新后触发,包括拖拽和 SliderRef.updateValue。在受控模式下,请通过此回调让外部 value 属性与渲染值保持同步。
    onValueCommit
    类型(value: number | SliderRangeValue) => void
    拖拽交互结束时以最终值触发。适用于只需要最终提交值的场景,例如持久化到后端。
    step
    类型number
    步进间隔,范围 [0, 1]。设置后值会吸附到最近的 step 倍数。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式
    value
    类型number | SliderRangeValue
    受控滑块值。传入范围 [0, 1] 内的数值或有序的下限/上限二元组。请勿与 defaultValue 同时使用。

    基于状态的样式与渲染

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

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

    UI variants applied by SliderRoot.

    类名说明
    ui-active从指针或触摸交互开始到结束期间生效。
    ui-disabled滑块被禁用时生效。

    SliderTrack

    Track primitive props.

    SliderTrack establishes the measurement/layout coordinate space and renders the base rail.

    children
    类型ReactNode
    通常包含 SliderIndicator 以及可选的 SliderThumb。
    classNameiOSAndroidHarmony
    类型string
    类名
    styleiOSAndroidHarmony
    类型CSSProperties
    样式

    UI variants applied by SliderTrack.

    类名说明
    ui-active从指针或触摸交互开始到结束期间生效。
    ui-disabled滑块被禁用时生效。

    SliderIndicator

    Indicator primitive props.

    SliderIndicator is a pure visual layer. It fills from zero to the value in single-value mode and spans the selected interval in range mode.

    classNameiOSAndroidHarmony
    类型string
    类名
    styleiOSAndroidHarmony
    类型CSSProperties
    样式

    UI variants applied by SliderIndicator.

    类名说明
    ui-active从指针或触摸交互开始到结束期间生效。
    ui-disabled滑块被禁用时生效。

    SliderThumb

    Thumb primitive props.

    SliderThumb is positioned by the current ratio inside SliderTrack and does not own interaction logic.

    children
    类型ReactNode
    自定义拇指内容。
    classNameiOSAndroidHarmony
    类型string
    类名
    indexiOSAndroidHarmony
    类型SliderThumbIndex·默认值0
    此拇指对应的值索引。单值滑块使用默认索引 0;区间滑块使用 0 表示下限拇指,使用 1 表示上限拇指。
    styleiOSAndroidHarmony
    类型CSSProperties
    样式

    UI variants applied by SliderThumb.

    类名说明
    ui-active从指针或触摸交互开始到结束期间,仅在当前选中的拇指上生效。
    ui-disabled滑块被禁用时生效。

    SliderRef

    Imperative methods exposed by SliderRoot for the selected value shape. The generic defaults to number for compatibility with existing single-value refs; use SliderRef<SliderRangeValue> for a range slider.

    getValue
    类型() => number | SliderRangeValue
    使用所选值形态读取当前滑块值。
    updateValue
    类型(value: number | SliderRangeValue, options?: SliderUpdateValueOptions) => void
    命令式地设置滑块值。所选值形态中的每个数值都使用标准化范围 [0, 1]。

    辅助类型

    SliderRangeValue

    SliderRangeValue
    类型readonly [number, number]
    区间滑块的下限值和上限值。两个值都使用标准化的 [0, 1] 范围。 拖拽时,下限和上限拇指可以相遇,但不会交叉、交换身份或推动彼此。

    SliderValue

    SliderValue
    类型number | SliderRangeValue
    SliderRoot 接受的值:单个标准化数值,或有序的下限/上限二元组。

    SliderThumbIndex

    SliderThumbIndex
    类型0 | 1
    滑块拇指的索引。单值滑块使用索引 0;区间滑块使用索引 0 表示下限、索引 1 表示上限。

    SliderValueChangeSource

    SliderValueChangeSource
    类型external | drag
    值变更的来源。 - external:通过命令式 API 调用更新。 - drag:通过指针/触摸拖拽更新。

    SliderUpdateValueOptions

    Options used by SliderRef.updateValue.

    force
    类型boolean·默认值false
    跳过拖拽保护,在拖拽过程中也强制更新。
    source
    类型SliderValueChangeSource·默认值'external'
    标记更新来源,用于分析或逻辑分支。
    除非另有说明,本项目采用知识共享署名 4.0 国际许可协议进行许可,代码示例采用 Apache License 2.0 许可协议进行许可。