Элементы и бенто-спаны

Карточка — это любой DOM-элемент, который уже находится под вашим контролем — движок только измеряет его и никогда не трогает содержимое, только position/width-или-height/transform для расстановки.

Описание карточки

MasonryItemDescriptor

id

string

Уникальный id карточки.

el

HTMLElement | (() => HTMLElement | null) · опционально

Собственный элемент карточки, либо резолвер для него (например, ещё не смонтированный Vue/React ref). Карточка, у которой el не задан, либо резолвер сейчас возвращает null, пропускается до тех пор, пока не разрешится — это не ошибка, и это не блокирует упаковку остальных.

colSpan

number · по умолчанию: 1

Сколько соседних колонок занимает карточка при direction: 'vertical', ограничивается диапазоном [1, число колонок] при каждом пересчёте — colSpan шире текущего числа колонок (например, на узком экране) тихо обрезается, а не переполняет сетку.

rowSpan

number · по умолчанию: 1

То же самое, что colSpan, используется при direction: 'horizontal'.

aspectRatio

number · опционально

Предварительный размер по главной оси (до того, как у элемента появится реальный измеренный размер — первое монтирование, или ещё не отрендерен), вычисляется делением (vertical) или умножением (horizontal) размера карточки по поперечной оси на это соотношение. Без него такая карточка вообще выпадает из раскладки, пока не появится способ её измерить — если только не включён virtualize, тогда вместо этого включаются estimatedSize/MasonryOptions.estimateSize. Один частый случай «нет измерения» — элемент, который сам является (или содержит) непрогруженный <img>: движок не доверяет его текущему размеру и сам подписывается на load/error картинки, а не полагается только на ResizeObserver — так что галерея изображений без единого aspectRatio раскладывается верно, просто карточки появляются по одной, по мере догрузки. Полную цепочку оценки размера смотрите на странице Виртуализация.

estimatedSize

number · опционально

Явная оценка размера по главной оси в px, используется только пока включён virtualize и у карточки ещё нет реального измерения — имеет приоритет над aspectRatio. Игнорируется при выключенном virtualize.

order

number · опционально

Явный порядок упаковки; по умолчанию — позиция карточки в массиве, переданном в setItems.

Пример — все поля сразу:

engine.setItems([
  {
    id: 'hero', // уникальный id
    el: heroEl, // собственный элемент этой карточки
    colSpan: 2, // занимает 2 соседние колонки при 'vertical' (игнорируется при 'horizontal' — там действует rowSpan)
    aspectRatio: 16 / 9, // предварительная высота (crossSize / aspectRatio) до того, как элемент реально измерен
    order: 0, // упаковывается первым, независимо от позиции в массиве
  },
])

Бенто-спаны

colSpan/rowSpan шире 1 участвует в точно такой же skyline-упаковке, что и обычная карточка — движок перебирает все допустимые стартовые колонки для этого спана и выбирает ту, что минимизирует самый высокий край среди покрываемых колонок, а затем поднимает все эти колонки до нового края разом:

engine.setItems([
  { id: 'hero', el: heroEl, colSpan: 2 }, // вдвое шире обычной карточки
  { id: 'a', el: aEl },
  { id: 'b', el: bEl },
])

Отдельного CSS Grid-шаблона, который нужно держать в синхроне с данными, здесь нет — более широкая карточка это просто ещё одна запись в том же вызове setItems(), а упаковка сама решает, куда её поставить, исходя из текущей заполненности колонок — точно так же, как решила бы для карточки с colSpan: 1.