Paver.JS

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 8)

Image layout library for JavaScript

Paver.JS Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Paver.JS
========

Библиотека для укладки изображений (или любых других прямоугольных тайлов, допускающих масштабирование) на JavaScript.

Демо: http://denull.github.io/Paver.JS

# Предназначение и суть работы

По принципу работы библиотека ближе всего к тому, как Google выкладывает результаты поиска картинок: изображения укладываются последовательно горизонтально, масштабируясь под общую высоту ряда, пока ряд (при условии, что он растянут до заданной ширины) не станет ниже определенной высоты *`maxRowHeight`*.

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

Однако, с моей точки зрения, такой алгоритм (а ля Google.Images) можно улучшить: прежде чем класть новое фото в ряду справа от предыдущего, Paver.JS пытается разместить его под ним, создавая вертикальную «стопку» внутри ряда. Это помогает уменьшить дискриминацию вертикальных фото в исходном алгоритме: если горизонтальные (ландшафтные) фотографии выкладывать не объединяя в «стопки», они оказываются раза в два больше по площади, чем портретные.

Формирование вертикальных «стопок» ограничивается двумя параметрами: минимальная ширина стопки *`minStackWidth`* (так как добавление в неё новых фото делает её уже) и минимальная высота отдельной фотографии *`minTileHeight`* (так как вся стопка будет масштабирована к искомой высоте формируемого ряда).

Наконец, у библиотеки есть ещё более «умный» режим, основанный на площади тайлов, и в котором высота ряда не является фиксированной, а подбирается, исходя из четырех параметров: *`minRowHeight`* и *`maxRowHeight`* ограничивают диапазон возможных значений высоты, *`optimizeSteps`* задают число шагов между ними, *`preferredArea`* -- оптимальная площадь каждого тайла после укладки. Для каждого ряда будет произведено *`optimizeSteps`* попыток уложить фотографии (варьируя высоту ряда) и будет выбран тот вариант, при котором среднее отклонение площади тайла от оптимальной будет минимально. Например, для ряда с вертикальными фото может быть выбрана высота побольше, с горизонтальными -- поменьше.

# Использование

Для использования библиотеки необходимо подключить *paver.js*.

Создание укладчика:

````js
Paver(dataSource, width, opts);
````

*`dataSource`* -- источник данных. Либо обычный массив с объектами, из которых нужно сделать тайлы, либо объект с двумя методами: *`count()`* -- получить количество элементов и *`get(i)`* -- получить i-й элемент.

Каждый объект, описывающий данные тайла, должен содержать поля *`width`* и *`height`* с размерами исходного фото. В качестве альтернативы среди опций может быть передана функция *`getRatio`*, принимающая данные тайла и его индекс и возвращающая его пропорции (отношение ширины к высоте).

*`width`* -- ширина контейнера в пикселях.

*`opts`* -- объект с опциями. Список всех возможных опций (все необязательные):

* *`preferredArea`* -- оптимальная площадь тайлов. При указании используется более медленный алгоритм, перебирающий несколько (а именно *`optimizeSteps`*) высот каждого ряда от *`minRowHeight`* до *`maxRowHeight`* и выбирающий из них наиболее оптимальную.
* *`getPreferredArea`* -- функция, принимающая два параметра (данные тайла и его номер) и возвращающая его искомую площадь. Позволяет попытаться сделать некоторые фотографии больше других, если это возможно.
* *`optimizeSteps`* -- число итераций при переборе высоты ряда. Используется только если указана искомая площадь *`preferredArea`*.
* *`minRowHeight`* -- минимальная высота ряда при переборе. Используется только если указана искомая площадь *`preferredArea`*.
* *`maxRowHeight`* -- максимальная высота ряда при переборе. Если не указана искомая площадь *`preferredArea`*, считается целевой высотой ряда (все ряды будут почти такой высоты или чуть ниже).
* *`minStackWidth`* -- минимальная ширина стопки. Ограничивает стопки от того, чтобы они становились слишком вытянутыми вертикально (слишком узкими). Фото не будет добавлено в стопку, если это сделает её ширину меньше минимального значения.
* *`minTileHeight`* -- минимальная высота тайла. Ограничивает стопки от того, чтобы фотографии в них становились слишком низкими. Фото не будет добавлено в стопку, если это сделает его высоту меньше минимального значения.
* *`maxRatio`* -- максимальное отношение ширины к высоте тайла. Если на вход передано фото с пропорциями выше этого значения (слишком широкое), то его ширина будет обрезана.
* *`minRatio`* -- минимальное отношение ширины к высоте тайла. Если на вход передано фото с пропорциями ниже этого значения (слишком высокое), то его высота будет обрезана.
* *`margin`* -- ширина отступов между тайлами (по вертикали и по горизонтали).
* *`noStacks`* -- если установлено в *`true`*, то вертикальные стопки в рядах формироваться не будут.
* *`renderTile`* -- функция, которая будет использована для отрисовки каждого тайла. В качестве параметров ей будут переданы данные тайла (из исходного массива *`dataSource`*) и объект *`path`* с полями *`row`*, *`stack`* и *`tile`* -- индексом ряда (0 -- верхний), стопки в ряду (0 -- самая левая) и тайла в стопке (0 -- верхний). Функция должна вернуть HTML-элемент, соответствующий тайлу.
* *`getRatio`* -- функция, возвращающая пропорции переданного в неё тайла. Первыми аргументом передаются данные из массива *`dataSource`*, вторым -- индекс в этом массиве. Вернуть следует одно число, отношение ширины тайла к высоте.
* *`defaultSize`* -- размеры тайла по умолчанию (если у тайла отсутствуют поля *`width`* и *`height`*). Объект с полями *`width`* и *`height`*.

У объекта, возвращенного в результате вызова функции *`Paver(dataSource, width, opts)`* есть три метода:
* *`build(fromRow)`* -- выполнить укладку заново с ряда *`fromRow`* (пока не поддерживается).
* *`rebuild()`* -- выполнить укладку заново.
* *`render(element)`* -- отрисовать результат укладки в элементе *`element`*.

Все три метода возвращают тот же объект.

Обратите внимание, что при вызове *`Paver(dataSource, width, opts)`* (а также *`build(fromRow)`* и *`rebuild()`*) производится только укладка, но не создание визуальных элементов -- для этого необходимо вызвать метод *`render(element)`*, который в свою очередь будет вызывать переданную в качестве опции функцию *`renderTile(tile, path)`*:

````js
Paver(dataSource, width, opts).render(element);
````

Paver.JS

Paver.JS Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Paver.JS

Paver.JS Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README