useSlider

提供一套滑动交互逻辑，可以用于实现大多数的滑动组件，类似滑块或旋纽等。

一个完整的 slider 应至少包含如下三个元素：

容器（root）：包含其它所有元素，响应指针、滚轮及键盘事件，可以获取焦点；
滑轨（rail）：用于限定滑块的滑动区域；
滑块（thumb）：指示当前滑动位置及滑动状态。

具体可查看下面示例的代码。

示例#

横向滑动选择器#

垂直滑动选择器#

将横向滑动选择器改为垂直方向非常简单，只需要在 moving 中将 px 改为 py，剩下的的就都是样式上的调整：

平面滑动选择器#

而同时使用 px 和 py，就可以实现平面滑动选择器了：

表格行列数选择器（常用于富文本编辑器）#

类型定义#

useSlider 所接收参数及返回值类型定义如下：

interface useSlider {
    (props: UseSliderProps): Slider
}

interface UseSliderProps {
    // 一组值，分别对应每个滑块
    value: Value
    // 设置值
    setValue: React.Dispatch<React.SetStateAction<Value>>

    // 数轴
    axis: Axis | { [prop: string]: Axis }

    // 是否禁用
    disabled: boolean

    // 处理指针（鼠标、手指）拖拽事件
    moving: (event: MovingEvent) => ValuePatch

    // 处理滚轮事件
    wheel?: (event: WheelEvent) => ValuePatch

    // 快捷键
    hotkeys?: Hotkey[]
}

interface Slider {
    // 需要分别注入到对应元素上的属性
    rootProps: HTMLAttributes<HTMLElement>
    railProps: HTMLAttributes<HTMLElement>
    thumbProps: HTMLAttributes<HTMLElement>

    // 是否在滑动中
    sliding: boolean

    // 当前正在滑动的滑块索引
    thumb: number | undefined
}

// 每个滑块的值；可以是单个数值，如：`[0, 1]`，
// 也可以是包含一组数值的对象，如：`[ { x: 0, y: 0 }, { x: 1, y: 1 } ]`
type Value = number[] | { [prop: string]: number }[]

// 数轴，用于限定滑块在某个方向上的数值；若滑块值为单个数值，则只能指定一个数轴，
// 而若是包含一组数值的对象，则既可以指定一个通用数轴，也可以分别为每个数值属性指定对应的数轴，
// 如：{ x: { min: 0, max: 100 }, y: { min: 0, max: 60 }  }
interface Axis {
    // 最小值
    min: number

    // 最大值
    max: number

    // 步长
    step?: number

    // 额外数值点
    points?: number[]
}

// 用于更新滑块值，需要在事件处理器中返回，如：
// - 更新到指定数值：`0.2`，或 `{ x: 0.2 }`；
// - 更新到下一个或上一个值：`'next'` 或 `{ x: 'prev' }`；
// - 在当前值的基础上加减指定值：`'+0.2'`，或 `{ x: '-0.2' }`；
// - 自定义更新，如：`prevValue => prevValue / 2` 或 `prevValue => ( { x: prevValue.x / 2 } )`
type ValuePatch =
    | number
    | 'prev' | 'next' | string
    | { [prop: string]: number | 'prev' | 'next' | string }
    | (value: Value) => Value

// 指针拖拽事件
interface MovingEvent {
    // 指针相对于轨道元素的坐标位置
    x: number
    y: number
    breakX: number
    breakY: number

    // 指针相对于轨道元素的位置百分比
    px: number
    py: number
    breakPX: number
    breakPY: number

    // 指针移动方向
    dirX: 'left' | 'right'
    dirY: 'up' | 'down'

    // 指针移动速度
    velocity: number
}

// 滚轮事件
interface WheelEvent {
    // 滚轮滚动值
    deltaX: number
    deltaY: number
    deltaZ: number

    // 修饰键
    altKey: boolean
    ctrlKey: boolean
    metaKey: boolean
    shiftKey: boolean
}

// 快捷键事件
interface Hotkey {
    // 需要监听的快捷键，如： `a, ctrl-a`（特殊值 `ANY`，用于监听任意快捷键）
    keys: string

    // 可选修饰键，如 `{ key: 'ctrl-a', shift: true }` 表示监听快捷键 `ctrl-a` 及 `ctrl-shift-a`。
    shift?: boolean
    ctrl?: boolean
    meta?: boolean
    alt?: boolean

    // 事件处理函数
    handle: (eventData: HotkeyEvent) => ValuePatch | void
}

interface HotkeyEvent {
    // 用户所按下的快捷键，对应在 Hotkey.keys 中配置的某个快捷键
    readonly key: string

    /** 修饰键 */
    readonly ctrl: boolean
    readonly shift: boolean
    readonly meta: boolean
    readonly alt: boolean

    // 停止事件传播
    readonly stopPropagation: () => void

    // 阻止事件默认行为
    readonly preventDefault: () => void

    // 是否已阻止事件默认行为
    readonly defaultPrevented: boolean

    // 是否已匹配并触发某个快捷键
    readonly dispatched: boolean
}

基础样式#

这三者的基础样式可如下所示：

.container {
  position: relative;
}

.rail {
  position: absolute;
  top: 0;
  bottom: 0;
  left: 0;
  right: 0;
}

.thumb {
  width: 40px;
  height: 40px;

  position: absolute;
  left: 0;
  top: 0;

  transform: translate(-20px, 0);
}