animate

animate() твинит свободное значение — число, цвет, вектор — и кадр за кадром отдаёт его в твой onUpdate: счётчик, громкость, цвет материала, кольцо, которое рисует canvas. Стиль элемента (появление, сдвиг) анимируется его собственными animateTo / animateFrom (Стилизация UI), как и 3D- / 2D-узлы, источники света и камеры; несколько целей на одних часах — это Timeline.

  • досчитать число до счёта или итога
  • дождаться конца анимации перед следующим шагом
  • плавно включить или приглушить музыку
  • заполнить кольцо прогресса, нарисованное на canvas
  • плавно сменить цвет 3D-материала или пульсировать им в цикле
  • поставить анимацию на паузу, продолжить, развернуть или перепрыгнуть внутри неё
  • заморозить твин, пока игра на паузе, или оставить его идти

Обзор

TypeScript
const score = UIText('0').style({ fontSize: 48, color: 'white' })
const badge = UIText('').style({ fontSize: 20, color: '#ffd166' })
UIScreen(score, badge).style({ bgColor: '#101418', alignItems: 'center', justifyContent: 'center', gap: 12 }).open()

const main = async () => {
  const done = await animate({
    from: 0,
    to: 1250,
    duration: 800,                                      // МИЛЛИСЕКУНДЫ
    easing: 'outCubic',                                 // по умолчанию: linear
    onUpdate: (v) => { score.text = String(Math.round(v)) },
  }).finished                                           // true в конце, false при отмене
  if (done) badge.text = 'New record!'
}
main()

Опции: длительность, сглаживание, ключевые кадры, циклы

TypeScript
animate<T extends AnimateValue>({  // AnimateOptions<T>; T — один из видов значений ниже
  from: T, to: T,                  // два конца — или `values`
  values?: T[],                    // ключевые кадры, равномерно, если не задан `times`
  times?: number[],                // по одному смещению 0..1 на ключевой кадр
  duration?: number,               // МИЛЛИСЕКУНДЫ, по умолчанию 225
  delay?: number,                  // мс до того, как значение начнёт меняться
  easing?: EasingInput,            // по умолчанию 'linear' — все формы в easings.md
  loop?: boolean | number,         // true = бесконечно, n = n циклов
  loopMode?: 'ping-pong' | 'restart',  // по умолчанию 'ping-pong': туда и обратно за цикл
  clock?: 'ui' | 'game',           // по умолчанию 'ui' — см. раздел о часах
  onUpdate(value: AnimateOut<T>): void,  // текущее значение: число или Float32Array
  onComplete?(): void,             // после последнего onUpdate прогона, дошедшего до конца
}): Animation

Опции от times до clock значат то же самое в .animateTo() элемента; в Timeline loop, loopMode и clock относятся ко всему таймлайну.

Note

duration и delay — миллисекунды (кадровый dt — секунды; длительности UI .animateTo() тоже в мс). См. Соглашения.

easing преобразует линейный прогресс; см. Функции сглаживания. animate() — единственный твин, у которого по умолчанию linear: прогресс ты преобразуешь сам, и заранее сглаженный наложился бы на кривую, которую ты применяешь. У каждого твина с целью (animateTo / animateFrom / Timeline.add) по умолчанию, наоборот, ease-in-out. С ключевыми кадрами кривая применяется к каждому отрезку между двумя ключами.

  • onUpdate получает текущее значение в кадрах, когда анимация играет: на нативных хостах и в веб-плеере — только когда значение сдвинулось (ничего во время delay или между двумя равными ключевыми кадрами), в вебе — каждый кадр. Записывай значение; не считай вызовы.
  • Не рассчитывай, что придёт начальное значение: вне веба первый вызов приходит на кадр позже. Если начало должно показаться сразу, выстави его сам.
  • onComplete выполняется один раз после последнего onUpdate прогона, дошедшего до конца, — finish() тоже считается, — и никогда после cancel().
  • Задай from и to или values; без них animate() бросает исключение.
  • delay — часть анимации: duration у хэндла его включает, а с loop каждый цикл ждёт его заново.
  • Цикл 'ping-pong' с заданным числом повторов заканчивается там, где начался. Цикл 'restart' с числом повторов заканчивается на начальном значении на нативных хостах и в веб-плеере и на последнем — в вебе; если важно, где значение остановится, выставь его в onComplete.
Note

два вызова animate() никогда не отнимают значение друг у друга — в отличие от animateTo элемента, где свойство принадлежит самой новой анимации. Оба продолжают его писать: отменяй ту, которую заменяешь, как делает затухание музыки ниже.

Плавно включить или приглушить музыку: AudioPlayer.volume

У AudioPlayer нет своего затухания: твинь его volume (0..1). См. Медиа.

TypeScript
const music = new AudioPlayer(asset('./theme.mp3'))
music.loop = true
music.volume = 0
music.play()
const fadeIn = animate({ from: 0, to: 0.8, duration: 2000, onUpdate: (v) => { music.volume = v } })

const stop = UIButton(UIText('Stop music').style({ color: 'white' })).onClick(() => {
  fadeIn.cancel()                                       // иначе громкость будут писать оба
  animate({
    from: music.volume, to: 0, duration: 1000,
    onUpdate: (v) => { music.volume = v },
    onComplete: () => music.pause(),
  })
})
UIScreen(stop).style({ bgColor: '#101418', alignItems: 'center', justifyContent: 'center' }).open()

Заполнить кольцо прогресса, нарисованное на canvas

Canvas перерисовывается из onUpdate: reset(), рисование, update() — UIImage, который его показывает, получает новые пиксели.

TypeScript
const ring = new Canvas(120, 120, { pixelRatio: 2 })
const draw = (p: number) => {                           // p: доля полного оборота, 0..1
  ring.reset()                                          // reset() сбрасывает и состояние: задай его снова
  ring.lineWidth = 12
  ring.lineCap = 'round'
  ring.strokeStyle = '#4f7cff'
  ring.beginPath().arc(60, 60, 48, -Math.PI / 2, -Math.PI / 2 + p * 2 * Math.PI).stroke()
  ring.update()                                         // протолкнуть новые пиксели в изображение
}
draw(0)
UIScreen(UIImage(ring).style({ width: 120, height: 120 }))
  .style({ bgColor: '#101418', alignItems: 'center', justifyContent: 'center' }).open()

animate({ from: 0, to: 0.75, duration: 1200, easing: 'outCubic', onUpdate: draw })

Плавно сменить цвет 3D-материала

У материала нет animateTo: твинь две CSS-строки цвета и каждый кадр пиши [r, g, b, a] (0..1) в material.color. С loop: true цвет пульсирует — туда и обратно, бесконечно.

TypeScript
const scene = new Scene()
const paint = Material.lit({ color: '#1e2230' })
scene.add(Light.sun(), Mesh.box({ material: paint, position: [0, 0, -3] }))
scene.open()

animate({
  from: '#1e2230', to: '#4f7cff', duration: 600,        // строки цвета → [r, g, b, a], 0..1
  loop: true,                                           // бесконечно, туда и обратно ('ping-pong')
  onUpdate: (c) => { paint.color = [c[0], c[1], c[2], c[3]] },
})

Цвета, векторы и повороты: виды значений

Кроме чисел, animate() твинит цвета, векторы, повороты и матрицы. Вид значений выбирает интерполяцию, и все значения одного вызова должны быть одного вида.

значение интерполяция onUpdate получает
number lerp number
CSS-строка цвета ('#e33', 'rgb(…)', 'red', …) по каналам, r g b a в 0..1 Float32Array [r, g, b, a], 0..1
2 числа / Vec2 покомпонентно Float32Array(2)
3 числа / Vec3 покомпонентно Float32Array(3)
4 числа / Quat slerp (по кратчайшей дуге) Float32Array(4) [x, y, z, w]
16 чисел / Float32Array(16) / Mat4 lerp позиции, slerp поворота, lerp масштаба Float32Array(16), по столбцам
Note

все виды, кроме number, приходят как один и тот же Float32Array каждый кадр, перезаписанный на месте. Не храни ссылку; копируй ([...v]), чтобы сохранить значение кадра.

Note

цвета анимируются только строками. Число — всегда число: 0xff0000 твинится как обычное float-значение, а не цвет, — а массив из 3 или 4 чисел — это вектор или кватернион, никогда не RGBA. Строка, которая не CSS-цвет, бросает исключение, как и значения разных видов вперемешку.

Матрица раскладывается на позицию / поворот / масштаб в момент вызова animate() и собирается обратно каждый кадр, так что поворот между двумя концами никогда не даёт скоса, как дал бы поэлементный lerp.

Дождаться конца, пауза, продолжение, реверс: хэндл Animation

Каждая анимация возвращает этот хэндл: await a.finished ждёт её конца перед следующим шагом, а методы ставят на паузу, продолжают, разворачивают или перепрыгивают. Его возвращают animate(), .animateTo() / .animateFrom() и Timeline(); время — в миллисекундах.

TypeScript
a.pause(): this           // заморозить на месте
a.resume(): this          // продолжить; после конца или отмены играет снова с 0
a.play(): this            // перезапустить с 0 — `finished` предыдущего прогона резолвится в false
a.cancel(): this          // остановить на месте: без onComplete, `finished` резолвится в false
a.finish(): this          // перепрыгнуть в конец: onComplete выполняется, `finished` → true
a.seek(ms): this          // перепрыгнуть внутри текущей итерации; играет / на паузе — не меняется
a.onFinish(fn: (done: boolean) => void): this
a.finished: Promise<boolean>  // true в конце, false при отмене или перезапуске; никогда не реджектится
a.duration: number        // одна итерация, мс (`delay` у animate() / animateTo() в неё входит)
a.time: number            // мс от начала текущей итерации; запись = seek
a.progress: number        // 0..1 от всего прогона, включая циклы; запись = seek
a.rate: number            // 1 нормально, 2 вдвое быстрее, 0 заморожено, отрицательное — назад
a.playing: boolean

Отдельного вызова stop нет: cancel() останавливает там, где сейчас значение, finish() перепрыгивает в конец — одноразовая анимация приходит к последнему значению.

TypeScript
const label = UIText('0').style({ fontSize: 40, color: 'white' })
const run = animate({
  from: 0, to: 100, duration: 5000,
  onUpdate: (v) => { label.text = String(Math.round(v)) },
})
const button = (text: string, onTap: () => void) =>
  UIButton(UIText(text).style({ color: 'white' })).style({ p: 12, bgColor: '#2a3140', borderRadius: 8 }).onClick(onTap)

UIScreen(label, UIRow(
  button('Pause', () => run.pause()),
  button('Resume', () => run.resume()),                 // после конца или отмены: снова с 0
  button('Reverse', () => { run.rate = -run.rate }),    // играет обратно к началу
  button('Halfway', () => { run.progress = 0.5 }),      // прыжок; на паузе покажется при resume()
).style({ gap: 8 })).style({ bgColor: '#101418', alignItems: 'center', justifyContent: 'center', gap: 24 }).open()
  • Анимация на паузе не вызывает onUpdate при seek или записи progress; значение снова пойдёт при resume(). Чтобы скрабить — перетаскиванием выставлять progress, — замораживай её через rate = 0: она остаётся играющей, и каждый seek вызывает onUpdate.
  • Отрицательный rate проигрывает назад к началу. Нативные хосты и веб-плеер держат анимацию там незавершённой; веб её там завершает (finished → true).
  • progress охватывает весь прогон цикла с числом повторов. Бесконечный цикл читает 1, как только закончится первый цикл, а запись progress попадает в этот первый цикл; time — позиция в текущем цикле.
  • Играющей анимацией владеет среда выполнения, так что animate(…) «запустил и забыл» не нуждается в ссылке. Анимация на паузе живёт, только пока ты держишь её хэндл, — отпусти его, и среда выполнения освободит анимацию.
Note

finish() у анимации на паузе ничего не доводит до конца: onComplete не выполняется, finished так и не завершается. Сначала вызови resume().

Идти во время паузы игры или замереть вместе с ней: clock

Анимация на clock: 'ui' (по умолчанию) идёт в реальном времени и продолжает идти, пока игра на паузе, — то, что нужно для меню и HUD. Анимация на clock: 'game' следует Time.scale (замедление) и замирает, пока Time.paused.

TypeScript
const scene = new Scene()
const lamp = Material.lit({ color: '#203040' })
scene.add(Light.sun(), Mesh.box({ material: lamp, position: [0, 0, -3] }))

animate({                                               // пульсирует вместе с игрой и вместе с ней замирает
  from: '#203040', to: '#40a0ff', duration: 600, loop: true, clock: 'game',
  onUpdate: (c) => { lamp.color = [c[0], c[1], c[2], c[3]] },
})

const pause = UIButton(UIText('Pause').style({ color: 'white' }))
  .style({ bgColor: '#0008', borderRadius: 8, p: 12 })
  .onClick(() => { Time.paused = !Time.paused })
scene.widgets(UIWidget(pause).style({ top: 48, right: 16 }))
scene.open()
Note

'game' следует Time на iOS, Android, десктопе и в веб-плеере, когда существует 3D Scene — сцена передаёт Time.scale часам движка. В чисто 2D- или UI-приложении, в вебе и в headless-тестах твин на 'game' идёт в реальном времени.

Подводные камни

TypeScript
const score = UIText('0')
const card = UIColumn().style({ opacity: 0 })

// ✗ duration в секундах — твин завершится меньше чем за кадр
animate({ from: 0, to: 100, duration: 0.5, onUpdate: (v) => { score.text = String(Math.round(v)) } })
// ✓ миллисекунды
animate({ from: 0, to: 100, duration: 500, onUpdate: (v) => { score.text = String(Math.round(v)) } })

// ✗ хранение вектора — все записи окажутся одним массивом с финальным значением
const trail: Float32Array[] = []
animate({ from: [0, 0], to: [10, 10], duration: 300, onUpdate: (v) => trail.push(v) })
// ✓ копируй значение кадра
const points: number[][] = []
animate({ from: [0, 0], to: [10, 10], duration: 300, onUpdate: (v) => points.push([...v]) })

// ✗ гонять свойство, которое цель анимирует сама, — запись из JS каждый кадр
animate({ from: 0, to: 1, duration: 300, onUpdate: (v) => { card.style.opacity = v } })
// ✓ элемент твинится нативно
card.animateTo({ opacity: 1, duration: 300 })

Смотрите также