【山竹记账】日期选择组件弹性动画分析

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

手指按下
  ↓
停止尚未结束的动画，读取列表当前可见位移
  ↓
记录：手指起点 + 列表起点
  ↓
手指移动
  ↓
getDragTranslateY：计算原始位移
  ↓
getResistedTranslateY：压缩越界部分
  ↓
springApi.set：立即设置可见位移
  ↓
animated.ol：更新 transform

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

手指松开
  ↓
读取列表当前可见位移
  ↓
getNearestDateTimeIndex：找到最近的合法索引
  ↓
目标位移 = -索引 × 行高
  ↓
springApi.start：弹簧动画移动到目标位移
  ↓
同时通过 onChange 通知父组件新的选中值

1
2
3
4
5

日期列容器：裁剪超出区域的内容
  ├─ 列表定位层：把第一行放到选中框位置
  │    └─ 动画列表：通过 translateY 上下移动
  ├─ 上下渐变遮罩：弱化非选中区域
  └─ 中央选中框：始终保持不动

1
2
3
4
5
6
7

<div className="picker-positioner w-full absolute top-[calc(50%-var(--half-date-item-height))]">
  <animated.ol
    style={{ transform: springs.y.to((y) => `translate3d(0, ${y}px, 0)`) }}
    className="date-time-picker text-center">
    {/* 每一项的高度和行高都等于 dateItemHeight */}
  </animated.ol>
</div>

1

H / 2 - h / 2

1

y(i) = -i × h

1
2
3

minTranslateY = -(listLength - 1) × itemHeight

minTranslateY ≤ translateY ≤ 0

1
2
3
4
5

export const getDragTranslateY = (
  startTranslateY: number,
  startPointerY: number,
  currentPointerY: number
) => startTranslateY + currentPointerY - startPointerY

1

原始列表位移 = 手势开始时的列表位移 + 手指从按下到现在的总移动距离

1
2
3
4
5

第一次：原始越界 36px → 阻尼后约 22.76px

第二次手指再向下移动 1px：
错误地用 22.76 + 1 作为原始位移，再做一次阻尼
结果反而只有约 17.4px

1
2
3
4
5
6

手指起点：100px
列表起点：0px

手指到 136px → 原始位移 36px → 显示约 22.76px
手指回到 100px → 原始位移 0px → 显示 0px
手指继续到 90px → 原始位移 -10px → 显示 -10px

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

export const getResistedTranslateY = (
  translateY: number,
  listLength: number,
  itemHeight: number
) => {
  if (listLength <= 0 || itemHeight <= 0) {
    return 0
  }

  const minTranslateY = -(listLength - 1) * itemHeight

  if (translateY > 0) {
    return itemHeight * (1 - Math.exp(-translateY / itemHeight))
  }

  if (translateY < minTranslateY) {
    const overscroll = minTranslateY - translateY
    return minTranslateY - itemHeight * (1 - Math.exp(-overscroll / itemHeight))
  }

  return translateY
}

1

minTranslateY ≤ translateY ≤ 0

1

R(d) = h × (1 - exp(-d / h))，其中 d ≥ 0

1

d = minTranslateY - translateY

1

可见位移 = minTranslateY - R(d)

1
2
3
4
5
6
7
8

listLength = 5
itemHeight = 36px
minTranslateY = -144px
原始位移 = -180px

越界距离 = -144 - (-180) = 36px
压缩后拉伸量 ≈ 22.76px
最终显示位移 ≈ -144 - 22.76 = -166.76px

1

R(0) = h × (1 - 1) = 0

1
2

R'(d) = exp(-d / h)
R'(0) = 1

1
2

exp(-d / h) ≈ 1 - d / h
R(d) ≈ d

1

R''(d) = -exp(-d / h) / h < 0

1

当 d → +∞ 时，R(d) → h

1
2
3

         ⎧ R(y)          ，y > 0
F(y)  =  ⎨ y             ，m ≤ y ≤ 0
         ⎩ m - R(m - y)  ，y < m

1

minTranslateY - itemHeight ≤ 可见位移 ≤ itemHeight

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

export const getNearestDateTimeIndex = (
  translateY: number,
  listLength: number,
  itemHeight: number
) => {
  if (listLength <= 0 || itemHeight <= 0) {
    return 0
  }

  const minTranslateY = -(listLength - 1) * itemHeight
  const boundedTranslateY = Math.max(minTranslateY, Math.min(0, translateY))
  return Math.max(0, Math.min(listLength - 1, Math.round(-boundedTranslateY / itemHeight)))
}

1

const boundedTranslateY = Math.max(minTranslateY, Math.min(0, translateY))

1

Math.round(-boundedTranslateY / itemHeight)

1

Math.max(0, Math.min(listLength - 1, roundedIndex))

1

springs.y.get()

1
2
3
4

const [springs, springApi] = useSpring(() => ({
  y: currentDateIndex * -dateItemHeight,
  config: { tension: 300, friction: 30 },
}))

1
2
3
4

<animated.ol
  style={{ transform: springs.y.to((y) => `translate3d(0, ${y}px, 0)`) }}>
  {/* 选项 */}
</animated.ol>

1

用 300ms，按某条缓动曲线，从 A 走到 B

1
2

目标在 B，当前位置与 B 有距离，于是产生恢复力；
运动又受到阻力，最终逐渐稳定在 B。

1

m × x'' + c × x' + k × (x - target) = 0

1

config: { tension: 300, friction: 18 }

1
2
3

cCritical = 2 × sqrt(k × m)
          = 2 × sqrt(300)
          ≈ 34.64

1

const gestureRef = useRef<{ pointerY: number; translateY: number } | null>(null)

1
2
3
4
5

settlingTargetRef.current = null
springApi.stop()
const translateY = springs.y.get()
springApi.set({ y: translateY })
gestureRef.current = { pointerY: touch.clientY, translateY }

1
2
3
4
5

手指按下时：250px
列表此刻：-50.4px

手指仍在 250px → 原始位移 -50.4px
手指移到 260px → 原始位移 -40.4px

1
2
3
4

const translateY = getDragTranslateY(gesture.translateY, gesture.pointerY, touch.clientY)
springApi.set({
  y: getResistedTranslateY(translateY, dateTimeList.length, dateItemHeight),
})

1
2

gestureRef.current = null
springApi.start({ y: currentDateIndex * -dateItemHeight })

1
2
3
4
5
6
7

子组件启动吸附动画
  ↓
子组件调用 onChange
  ↓
父组件更新 dateTimeValue
  ↓
子组件渲染，相关 effect 执行

1
2
3
4
5

const settlingTargetRef = useRef<{
  index: number
  itemHeight: number
  listLength: number
} | null>(null)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

useEffect(() => {
  if (gestureRef.current) {
    return
  }

  const settlingTarget = settlingTargetRef.current
  if (settlingTarget) {
    if (
      settlingTarget.index === currentDateIndex &&
      settlingTarget.itemHeight === dateItemHeight &&
      settlingTarget.listLength === dateTimeList.length
    ) {
      return
    }
    settlingTargetRef.current = null
  }

  springApi.start({ y: currentDateIndex * -dateItemHeight })
}, [currentDateIndex, dateItemHeight, dateTimeList.length, springApi])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

const settlingTarget = {
  index: resultIndex,
  itemHeight: dateItemHeight,
  listLength: dateTimeList.length,
}

settlingTargetRef.current = settlingTarget

springApi.start({
  y: resultIndex * -dateItemHeight,
  config: { tension: 300, friction: 18 },
  onRest: () => {
    if (settlingTargetRef.current === settlingTarget) {
      settlingTargetRef.current = null
    }
  },
})

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

import { animated, useSpring } from '@react-spring/web'
import { cn } from 'cn'
import { useEffect, useRef } from 'react'
import type { TouchEventHandler } from 'react'
import {
  getDragTranslateY,
  getNearestDateTimeIndex,
  getResistedTranslateY,
} from './dateTimeColumnMotion'

interface ColumnProps {
  className?: string
  dateItemHeight?: number
  dateTimeValue: string
  dateTimeList: string[]
  onChange: (value: string) => void
}

export const DateTimeColumn: React.FC<ColumnProps> = ({
  className,
  dateItemHeight = 36,
  dateTimeValue,
  dateTimeList,
  onChange,
}) => {
  const halfDateItemHeight = dateItemHeight / 2
  const itemHeightVarStyle = {
    '--date-item-height': `${dateItemHeight}px`,
    '--half-date-item-height': `${halfDateItemHeight}px`,
    touchAction: 'none',
  }

  const currentDateIndex = dateTimeList.indexOf(dateTimeValue)
  if (currentDateIndex === -1) {
    throw new Error('dateTimeValue is not in dateTimeList')
  }

  const gestureRef = useRef<{ pointerY: number; translateY: number } | null>(null)
  const settlingTargetRef = useRef<{
    index: number
    itemHeight: number
    listLength: number
  } | null>(null)

  const [springs, springApi] = useSpring(() => ({
    y: currentDateIndex * -dateItemHeight,
    config: { tension: 300, friction: 30 },
  }))

  useEffect(() => {
    if (gestureRef.current) {
      return
    }

    const settlingTarget = settlingTargetRef.current
    if (settlingTarget) {
      if (
        settlingTarget.index === currentDateIndex &&
        settlingTarget.itemHeight === dateItemHeight &&
        settlingTarget.listLength === dateTimeList.length
      ) {
        return
      }
      settlingTargetRef.current = null
    }

    springApi.start({ y: currentDateIndex * -dateItemHeight })
  }, [currentDateIndex, dateItemHeight, dateTimeList.length, springApi])

  const onTouchStart: TouchEventHandler<HTMLDivElement> = (e) => {
    const touch = e.touches[0]
    if (!touch) {
      return
    }

    settlingTargetRef.current = null
    springApi.stop()
    const translateY = springs.y.get()
    springApi.set({ y: translateY })
    gestureRef.current = { pointerY: touch.clientY, translateY }
  }

  const onTouchMove: TouchEventHandler<HTMLDivElement> = (e) => {
    const gesture = gestureRef.current
    const touch = e.touches[0]
    if (!gesture || !touch) {
      return
    }

    const translateY = getDragTranslateY(gesture.translateY, gesture.pointerY, touch.clientY)
    springApi.set({
      y: getResistedTranslateY(translateY, dateTimeList.length, dateItemHeight),
    })
  }

  const onTouchEnd: TouchEventHandler<HTMLDivElement> = () => {
    if (!gestureRef.current) {
      return
    }

    gestureRef.current = null
    const resultIndex = getNearestDateTimeIndex(
      springs.y.get(),
      dateTimeList.length,
      dateItemHeight
    )
    const settlingTarget = {
      index: resultIndex,
      itemHeight: dateItemHeight,
      listLength: dateTimeList.length,
    }
    settlingTargetRef.current = settlingTarget

    springApi.start({
      y: resultIndex * -dateItemHeight,
      config: { tension: 300, friction: 18 },
      onRest: () => {
        if (settlingTargetRef.current === settlingTarget) {
          settlingTargetRef.current = null
        }
      },
    })
    onChange(dateTimeList[resultIndex])
  }

  const onTouchCancel: TouchEventHandler<HTMLDivElement> = () => {
    if (!gestureRef.current) {
      return
    }

    gestureRef.current = null
    springApi.start({ y: currentDateIndex * -dateItemHeight })
  }

  return (
    <div
      onTouchStart={onTouchStart}
      onTouchMove={onTouchMove}
      onTouchEnd={onTouchEnd}
      onTouchCancel={onTouchCancel}
      style={itemHeightVarStyle}
      className={cn(
        'date-picker-column h-[var(--popup-height)] overflow-clip relative',
        className
      )}>
      <div className="picker-positioner w-full absolute top-[calc(50%-var(--half-date-item-height))]">
        <animated.ol
          style={{ transform: springs.y.to((y) => `translate3d(0, ${y}px, 0)`) }}
          className="date-time-picker text-center">
          {dateTimeList.map((dateTimeStr) => (
            <li
              key={dateTimeStr}
              className="h-[var(--date-item-height)] leading-[var(--date-item-height)]">
              {dateTimeStr}
            </li>
          ))}
        </animated.ol>
      </div>
    </div>
  )
}

1
2
3

初始位移：-2 × 36 = -72px
手指起点：200px
手指松开位置：180px

1
2
3

原始位移 = -72 + (180 - 200) = -92px
合法范围 = [-144, 0]
可见位移 = -92px

1
2
3

连续索引 = 92 / 36 ≈ 2.556
最近索引 = 3
目标位移 = -3 × 36 = -108px

1
2

初始位移：0px
手指向下移动：72px

1
2
3

原始位移 = 72px
可见位移 = 36 × (1 - exp(-72 / 36))
         ≈ 31.13px

1
2
3

可见位移 31.13px → 截断为 0px
目标索引 = 0
目标位移 = 0px

1
2
3
4

初始位移：-144px
手指再向上移动：36px
原始位移：-180px
可见位移：约 -166.76px

1
2
3
4

上次目标：-108px
此刻动画位置：-96px
用户重新按下：停止动画，以 -96px 作为新起点
手指向下移动 10px：列表变为 -86px

1

className="h-[var(--date-item-height)] leading-[var(--date-item-height)]"

1

pointer-events: none

1

touchAction: 'none'

1

dateTimeList.includes(dateTimeValue)

1
2
3
4
5
6
7
8
9

计算新的年月日
  ↓
按业务规则规范化日期
  ↓
生成新的合法选项列表
  ↓
传入合法的选中值
  ↓
动画层同步到新位置

1

给定输入 → 返回什么数值

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

import { describe, expect, it } from 'vitest'
import {
  getDragTranslateY,
  getNearestDateTimeIndex,
  getResistedTranslateY,
} from '@/components/form/dateTimeColumnMotion.ts'

const itemHeight = 36
const listLength = 5
const minTranslateY = -(listLength - 1) * itemHeight

describe('dateTimeColumnMotion', () => {
  it('keeps in-range movement at a one-to-one distance', () => {
    expect(getResistedTranslateY(-81, listLength, itemHeight)).toBe(-81)
    expect(getResistedTranslateY(0, listLength, itemHeight)).toBe(0)
    expect(getResistedTranslateY(minTranslateY, listLength, itemHeight)).toBe(minTranslateY)
  })

  it('resists top and bottom overscroll while allowing visible stretch', () => {
    const topStretch = getResistedTranslateY(itemHeight, listLength, itemHeight)
    const bottomStretch = getResistedTranslateY(minTranslateY - itemHeight, listLength, itemHeight)

    expect(topStretch).toBeGreaterThan(0)
    expect(topStretch).toBeLessThan(itemHeight)
    expect(bottomStretch).toBeLessThan(minTranslateY)
    expect(bottomStretch).toBeGreaterThan(minTranslateY - itemHeight)
    expect(Math.abs(topStretch - (minTranslateY - bottomStretch))).toBeLessThan(1e-10)
    expect(getResistedTranslateY(itemHeight * 100, listLength, itemHeight)).toBeLessThanOrEqual(
      itemHeight
    )
  })

  it('supports dragging back across an edge without losing the raw pointer delta', () => {
    expect(getDragTranslateY(12, 100, 90)).toBe(2)
    expect(getResistedTranslateY(getDragTranslateY(0, 100, 90), listLength, itemHeight)).toBe(-10)
  })

  it('starts a new drag at the visible position after an interrupted spring', () => {
    const visibleTranslateY = -itemHeight * 1.4

    expect(
      Math.abs(getDragTranslateY(visibleTranslateY, 250, 250) - visibleTranslateY)
    ).toBeLessThan(1e-10)
    expect(
      Math.abs(getDragTranslateY(visibleTranslateY, 250, 260) - (visibleTranslateY + 10))
    ).toBeLessThan(1e-10)
  })

  it('snaps to the nearest legal item and clamps overscroll to the list', () => {
    expect(getNearestDateTimeIndex(-itemHeight * 1.6, listLength, itemHeight)).toBe(2)
    expect(getNearestDateTimeIndex(itemHeight * 2, listLength, itemHeight)).toBe(0)
    expect(getNearestDateTimeIndex(minTranslateY - itemHeight * 2, listLength, itemHeight)).toBe(4)
    expect(getNearestDateTimeIndex(0, 1, itemHeight)).toBe(0)
  })
})

1

pnpm test src/components/form/__test__/dateTimeColumnMotion.test.ts

1

expect(Math.abs(topStretch - (minTranslateY - bottomStretch))).toBeLessThan(1e-10)

1
2

原本显示：20px
再次映射：36 × (1 - exp(-20 / 36)) ≈ 15.34px

1

v = h × (1 - exp(-d / h))

1

d = -h × ln(1 - v / h)

1

R(d) = L × (1 - exp(-d / L))

1
2

R(d) = A × (1 - exp(-d / B))
R'(0) = A / B

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

采样指针位置与时间
  ↓
估计松手速度
  ↓
用衰减或投影模型预测目标位置
  ↓
把目标限制在合法范围
  ↓
转换成最近的合法索引
  ↓
弹簧吸附到整行位置