Типы возвращаемых значений

Библиотека SVG.js построена вокруг объектной модели для работы с SVG-элементами, что обеспечивает гибкость и удобство манипуляции графикой через JavaScript. Понимание типов возвращаемых значений функций является ключевым для правильного использования методов и построения сложных сцен.

1. Объекты SVG

Большинство методов SVG.js возвращают объекты, представляющие SVG-элементы. Это позволяет сразу применять к ним цепочку методов.

Примеры объектов:

  • SVG.Doc — корневой SVG-документ или контейнер, создаваемый через SVG().addTo('#container').
  • SVG.Rect, SVG.Circle, SVG.Path, SVG.Line — конкретные геометрические фигуры.
const draw = SVG().addTo('#canvas').size(300, 300);
const rect = draw.rect(100, 100).fill('#f06');

В этом примере метод rect() возвращает объект SVG.Rect, что позволяет сразу вызвать .fill(), .stroke() или .move().

Особенности:

  • Методы, возвращающие объект элемента, поддерживают цепочку вызовов (chaining).
  • Полученный объект можно хранить в переменной и повторно использовать для анимаций, трансформаций и событий.

2. Простые типы данных

Некоторые методы возвращают числа, строки или логические значения, которые отражают текущие свойства элемента.

Примеры:

  • .width() и .height() без параметров возвращают число — текущую ширину или высоту элемента.
  • .x() и .y() без параметров возвращают координаты как числа.
  • .visible() возвращает boolean, показывая, видим элемент или скрыт.
const w = rect.width(); // число
const isVisible = rect.visible(); // true или false

Особенности:

  • При передаче параметра методы превращаются в сеттеры и возвращают объект элемента для цепочек.
  • Без параметров методы выступают как геттеры, возвращая простые типы.

3. Коллекции элементов

Методы, возвращающие несколько элементов, дают объект SVG.Set — коллекцию SVG-элементов.

const group = draw.group();
const rect1 = group.rect(50, 50).fill('red');
const rect2 = group.rect(50, 50).fill('blue');

const children = group.children(); // SVG.Set

Особенности SVG.Set:

  • Поддерживает перебор элементов через .each()
  • Позволяет применять методы сразу ко всей группе элементов
  • Можно комбинировать с цепочкой вызовов для массовых трансформаций.
children.each(function(i, children) {
    this.move(i * 60, 0);
});

4. Анимации и эффекты

Методы анимации, такие как .animate(), возвращают объект SVG.FX, представляющий текущее анимационное состояние элемента.

rect.animate(1000).move(200, 200).fill('#0f0');

Особенности SVG.FX:

  • Позволяет цепочку анимаций: .after(), .during(), .loop()
  • Поддерживает прерывание и перезапуск анимации через .stop() и .finish()
  • Методы .attr() и .transform() можно применять к FX-объекту для динамических изменений

5. Специальные возвращаемые значения

Некоторые методы возвращают специфические объекты или значения, которые важны для сложных взаимодействий:

  • .bbox() — объект с ключами {x, y, width, height}
  • .cx(), .cy() — числа, обозначающие центр элемента
  • .matrix() — объект SVG.Matrix, содержащий матрицу трансформации элемента
const bbox = rect.bbox(); 
console.log(bbox.width, bbox.height); // размеры элемента

Особенности:

  • Эти методы полезны для вычислений позиции и размеров элементов перед анимацией или трансформацией.
  • Возвращаемые объекты можно модифицировать, но напрямую изменения на элемент не применяются без явного вызова сеттера.

6. Итоги по типам возвращаемых значений

Метод / Категория Возвращаемое значение Примечание
Создание элементов (rect, circle) SVG.Element (Rect, Circle) Поддержка цепочек вызовов
Свойства элемента без параметров (width(), x()) число, boolean, строка Геттер
Свойства элемента с параметром (width(100)) SVG.Element Сеттер с цепочкой
Группы и коллекции (group(), .children()) SVG.Set Применение методов ко всем элементам
Анимация (animate()) SVG.FX Для управления анимацией
Геометрия и матрицы (bbox(), matrix()) объект Для вычислений и трансформаций

Понимание типов возвращаемых значений в SVG.js позволяет создавать эффективные, динамичные и легко расширяемые SVG-сцены, управлять цепочками методов и корректно интегрировать анимацию и события.

Оглавление