animate
animate() твинит свободное значение — число, цвет, вектор — и кадр за кадром отдаёт его в твой
onUpdate: счётчик, громкость, цвет материала, кольцо, которое рисует canvas. Стиль элемента
(появление, сдвиг) анимируется его собственными animateTo / animateFrom
(Стилизация UI), как и
3D- / 2D-узлы, источники света и камеры; несколько целей на одних часах — это Timeline.
- досчитать число до счёта или итога
- дождаться конца анимации перед следующим шагом
- плавно включить или приглушить музыку
- заполнить кольцо прогресса, нарисованное на canvas
- плавно сменить цвет 3D-материала или пульсировать им в цикле
- поставить анимацию на паузу, продолжить, развернуть или перепрыгнуть внутри неё
- заморозить твин, пока игра на паузе, или оставить его идти
Обзор
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()Опции: длительность, сглаживание, ключевые кадры, циклы
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 относятся ко всему таймлайну.
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.
два вызова animate() никогда не отнимают значение друг у друга — в отличие от
animateTo элемента, где свойство принадлежит самой новой анимации. Оба продолжают его писать:
отменяй ту, которую заменяешь, как делает затухание музыки ниже.
Плавно включить или приглушить музыку: AudioPlayer.volume
У AudioPlayer нет своего затухания: твинь его volume (0..1). См. Медиа.
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, который его показывает, получает новые пиксели.
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 цвет пульсирует — туда и обратно, бесконечно.
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), по столбцам |
все виды, кроме number, приходят как один и тот же Float32Array каждый кадр,
перезаписанный на месте. Не храни ссылку; копируй ([...v]), чтобы сохранить значение кадра.
цвета анимируются только строками. Число — всегда число: 0xff0000 твинится как
обычное float-значение, а не цвет, — а массив из 3 или 4 чисел — это вектор или кватернион, никогда
не RGBA. Строка, которая не CSS-цвет, бросает исключение, как и значения разных видов вперемешку.
Матрица раскладывается на позицию / поворот / масштаб в момент вызова animate() и собирается
обратно каждый кадр, так что поворот между двумя концами никогда не даёт скоса, как дал бы
поэлементный lerp.
Дождаться конца, пауза, продолжение, реверс: хэндл Animation
Каждая анимация возвращает этот хэндл: await a.finished ждёт её конца перед следующим шагом, а
методы ставят на паузу, продолжают, разворачивают или перепрыгивают. Его возвращают animate(),
.animateTo() / .animateFrom() и Timeline(); время — в миллисекундах.
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()
перепрыгивает в конец — одноразовая анимация приходит к последнему значению.
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(…)«запустил и забыл» не нуждается в ссылке. Анимация на паузе живёт, только пока ты держишь её хэндл, — отпусти его, и среда выполнения освободит анимацию.
finish() у анимации на паузе ничего не доводит до конца: onComplete не
выполняется, finished так и не завершается. Сначала вызови resume().
Идти во время паузы игры или замереть вместе с ней: clock
Анимация на clock: 'ui' (по умолчанию) идёт в реальном времени и продолжает идти, пока игра на
паузе, — то, что нужно для меню и HUD. Анимация на clock: 'game' следует Time.scale
(замедление) и замирает, пока Time.paused.
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()Подводные камни
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 })Смотрите также
- Timeline — хореография элементов, 3D- / 2D-узлов, источников света и камер
- Функции сглаживания — имена кривых,
cubicBezier,steps, свои функции - Стилизация UI —
.animateTo()/.animateFrom()у UI-элементов - Time —
Time.scale/Time.paused, чему следуют часы'game' - Медиа —
AudioPlayerи егоvolume - Canvas — рисование,
reset()иupdate() - Соглашения — время — где SDK использует секунды, а где миллисекунды