mapRange для преобразования диапазонов

mapRange — это утилита GSAP, предназначенная для линейного преобразования чисел из одного диапазона в другой. Она используется, когда требуется масштабировать или нормализовать значения, например, для анимации свойств, зависящих от пользовательского ввода или скролла.

Основной синтаксис

gsap.utils.mapRange(inMin, inMax, outMin, outMax, value);

Параметры:

  • inMin — минимальное значение исходного диапазона.
  • inMax — максимальное значение исходного диапазона.
  • outMin — минимальное значение целевого диапазона.
  • outMax — максимальное значение целевого диапазона.
  • value — значение, которое нужно преобразовать.

Возвращаемое значение: число, находящееся в пределах целевого диапазона.

Пример базового использования:

let x = 50;
let mapped = gsap.utils.mapRange(0, 100, 0, 1, x); 
console.log(mapped); // 0.5

Здесь число 50, находящееся в диапазоне [0, 100], преобразуется в значение [0, 1].

Линейная интерполяция и mapRange

Функция mapRange реализует линейную интерполяцию (LERP) между двумя диапазонами. Математически она вычисляется так:

[ = + ]

Это позволяет плавно масштабировать любое число из исходного диапазона в целевой, сохраняя пропорции.

Применение в анимациях

1. Анимация скроллом

С mapRange часто создают эффекты параллакса или привязывают движение объектов к прокрутке страницы:

window.addEventListener("scroll", () => {
  let scroll = window.scrollY;
  let y = gsap.utils.mapRange(0, document.body.scrollHeight - window.innerHeight, 0, 500, scroll);
  gsap.to(".box", { y: y, duration: 0.3 });
});

Здесь mapRange переводит текущую прокрутку в значение смещения элемента по оси Y.

2. Привязка к пользовательскому вводу

Можно использовать mapRange для преобразования значений слайдера:

let slider = document.querySelector("#slider");
slider.addEventListener("input", (e) => {
  let rotation = gsap.utils.mapRange(0, 100, -180, 180, e.target.value);
  gsap.to(".pointer", { rotation: rotation });
});

Значение слайдера [0, 100] масштабируется в диапазон углов [-180, 180].

Ограничение и нормализация значений

mapRange не ограничивает выходное значение автоматически в пределах [outMin, outMax]. Для этого можно использовать комбинацию с clamp:

let normalized = gsap.utils.clamp(0, 1, gsap.utils.mapRange(0, 100, 0, 1, 150));
console.log(normalized); // 1

clamp предотвращает выход за пределы диапазона.

Инвертирование диапазона

Функция позволяет легко инвертировать диапазон. Например, перевернуть движение:

let x = 25;
let inverted = gsap.utils.mapRange(0, 100, 1, 0, x);
console.log(inverted); // 0.75

Это полезно для создания эффектов, где высокая величина исходного диапазона соответствует низкой величине целевого.

Композиция нескольких mapRange

Можно объединять несколько преобразований для сложных анимаций:

let scroll = window.scrollY;
let speed = gsap.utils.mapRange(0, 1000, 0.5, 2, scroll); 
let rotation = gsap.utils.mapRange(0, 1000, 0, 360, scroll);
gsap.to(".wheel", { rotation: rotation, scale: speed });

В этом примере одно и то же значение скролла используется для разных свойств анимации.

Выводы о mapRange

  • Преобразует любое число из одного диапазона в другой.
  • Основана на линейной интерполяции.
  • Используется для скролла, ввода пользователя, комплексных анимаций.
  • Может комбинироваться с clamp для ограничения диапазона.
  • Позволяет инвертировать значения и создавать сложные анимационные эффекты.

mapRange — мощный инструмент для управления анимациями, где необходимо динамическое масштабирование значений без написания громоздких формул вручную.

Оглавление