js360 v1.0.53

JS360

Note. English version of docs is coming soon...

See Demo

Компонент, имитирующий работу 3D модели с помощью массива закодированных в base64 изображений на входе и канваса на выходе.

Оглавление

• Входящие данные
• Быстрый старт
• Возможности
• API
  • Methods
    • load
    • play
    • stop
    • toggle
  • Events
    • onLoad
    • onRotateStart
    • onRotate
    • onRotateEnd
    • onPlayStart
    • onPlay
    • onPlayEnd
  • Flags
    • isLoaded
    • isPending
    • isMoving
    • isStopped
    • isPlayed
  • Options
    • autoPlay
    • baseUrl
    • controlLoad
    • controlPlay
    • height
    • loadEvents
    • preloader
    • preview
    • retinaUrl
    • rotateEvents
    • speed
    • target
    • url
    • width

Входящие данные (REST output)

[
  "data:image/jpeg;base64,/9j/4AA...",
  "data:image/jpeg;base64,/9j/4Af...",
  "data:image/jpeg;base64,/9j/3sf...",
  "data:image/jpeg;base64,/9j/1gf..."
]

Быстрый старт

1. Установка

npm install --save js360
yarn add js360

2. Создаем контейнер, в который будет добавлен канвас.

<div class="simple-js360"></div>

3. Канвас и изображение, добавляемое в него, получат размеры добавленного выше контейнера. Поэтому, у контейнера должны быть заданы минимальные стили.

.simple-js360 {
  width: 320px;
  height: 180px;
}

4. Создаем объект модели и рендерим.

import { JS360 } from 'js360';

const js360 = new JS360({ // options
  baseUrl: 'http://myrest', // без замыкающего слеша (проверки пока нет, но будет)
  target:  '.simple-js360',
  preview: '.assets/product.jpeg',
  url:     'product.json'
});

js360.render();

• baseUrl - базовый url к массиву изображений
• target - селектор css - контейнер, куда будет добавлен канвас
• preview - изображение для предпоказа. Пока целевой массив закодированных изображений еще не получен или загрузка не активирована
• url - путь до самого файла на сервере
• В итоге файл будет скачан по пути http://myrest/product.json

Мы получим контейнер, с шириной 320px и высотой 180px. В контейнере будет содержаться канвас, в котором будет рендериться изображение. При клике на канвас произойдет запрос на сервер по адресу http://myrest/product.json.

Note. Запрос пока простейший на XMLHttpRequest. Хедеры не поддерживает, но будет.

Возможности

• Добавить канвас можно как на 1 компонент, так и на массив
• Кастомные события для загрузки и прокрутки контента
• Для retina можно загружать отдельный массив изображений. К примеру, если window.devicePixelRatio === 2 загружаем изображения 720×480, в ином случае 320x180
• Скорость прокрутки
• Автопросмотр после загрузки
• Возможность включить и выключить кнопки управления (загрузка / остановка / ускорение)
• Много чего в планах, разработка ведется

API

Methods

• load(index)

  type: (index) => Promise.all

Ручная загрузка массива изображений. На вход метод получает массив индексов, определяющий для каких именно кансасов нужно выгрузить изображения. Если не передано ничего, изображения загружаются для всех кансасов объекта. Возвращает Promise, который резолвится, когда все запрошенные массивы получены.

const js360 = new JS360({
  baseUrl: 'http://my_rest',
  target:  document.querySelectorAll('.js360')
});

js360.render();
js360.load().then(() => {
    // some code ...
    js360.play();
});

• play(index)

  type: index

Ручной запуск автопросмотра. Метод получает на вход массив индексов, определяющий для каких именно кансасов нужно запустить просмотр. Если не передано ничего, просмотр запускается для всех кансасов объекта.

const js360 = new JS360({
  baseUrl: 'http://my_rest',
  target:  document.querySelectorAll('.js360')
});

js360.render();
js360.load().then(() => {
    // some code ...
    js360.play();
});

• stop(index)

  type: index

Ручная остановка автопросмотра. Метод получает на вход массив индексов, определяющий для каких именно кансасов нужно остановить просмотр. Если не передано ничего, просмотр останавливается для всех кансасов объекта.

const js360 = new JS360({
  baseUrl: 'http://my_rest',
  target:  document.querySelectorAll('.js360'),
  autoPlay: true
});

js360.render();

setTimeout(() => {
    js360.stop([3]);
}, 2000);

Через 2 секунды после инициализации, просмотр будет остановлен для канваса с индексом 3.

• toggle(index)

  type: index

Переключение режимов play / stop. Также получает на вход массив индексов, к которым нужно применить метод. Если ничего не передано - метод будет передан для всех канвасов данного объекта.

const js360 = new JS360({
  baseUrl: 'http://my_rest',
  target:  document.querySelectorAll('.js360'),
  autoPlay: true
});

js360.render();

setTimeout(() => {
    js360.toggle();

    setTimeout(() => {
        js360.toggle();
    }, 2000);
}, 2000);

Через 2 секунды после инициализации, просмотр будет остановлен для всех канвасов. И будет запущен новый таймер на 2 секунды, для возобновления автопросмотра.

Events

• onLoad

  type: function

Вызывается после удачной загрузки изображений.

const js360 = new JS360({
  baseUrl: 'http://my_rest',
  target:  document.querySelectorAll('.js360'),
  onLoad: () => console.log('images is loaded')
});

js360.render();

Успешная загрузка контента вызовет функцию onLoad.

• onRotateStart

  type: function

const js360 = new JS360({
  target:  document.querySelectorAll('.js360'),
  onRotateStart: () => console.log('rotate is started')
});

js360.render();

Активация прокрутки мышью вызовет функцию onRotateStart.

• onRotate

  type: function

const js360 = new JS360({
  target:  document.querySelectorAll('.js360'),
  onRotate: () => console.log('rotating happens now')
});

js360.render();

Каждый поворот модели вызовет функцию onRotate.

• onRotateEnd

  type: function

const js360 = new JS360({
  target:  document.querySelectorAll('.js360'),
  onRotateEnd: () => console.log('rotating is finished')
});

js360.render();

По завершению поворота модели будет вызвано событие onRotateEnd.

• onPlayStart

  type: function

const js360 = new JS360({
  target:  document.querySelectorAll('.js360'),
  onPlayStart: () => console.log('autoPlay is started')
});

js360.render();

Активация автопросмотра вызовет функцию onPlayStart.

• onPlay

  type: function

const js360 = new JS360({
  target:  document.querySelectorAll('.js360'),
  onPlay: () => console.log('autoPlay is happening now')
});

js360.render();

Каждая атоматическая смена изображения в канвасе активирует функцию onPlay.

• onPlayEnd

  type: function

const js360 = new JS360({
  target:  document.querySelectorAll('.js360'),
  onPlayEnd: () => console.log('autoPlay is finished')
});

js360.render();

Остановка автопросмотра вызывает событие onPlayEnd.

Flags

• isLoaded

  type: function => boolean

const js360 = new JS360({ target:  document.querySelectorAll('.js360') });

js360.render();
js360.isLoaded();

false - изображения не загружены
true - изображения загружены

• isPending

  type: function

const js360 = new JS360({ target:  document.querySelectorAll('.js360') });

js360.render();
js360.isPending();

false - изображения не загружаются в данный момент
true - изображения загружаются в данный момент

• isMoving

  type: function => boolean

const js360 = new JS360({ target:  document.querySelectorAll('.js360') });

js360.render();
js360.isMoving();

false - ручной разворот подели не происходит
true - происходит ручной поворот модели

• isStopped

  type: function => boolean

const js360 = new JS360({ target:  document.querySelectorAll('.js360') });

js360.render();
js360.isStopped();

false - автопросмотр включен
true - автопросмотр выключен

• isPlayed

  type: function => boolean

const js360 = new JS360({ target:  document.querySelectorAll('.js360') });

js360.render();
js360.isPlayed();

false - автопросмотр выключен
true - автопросмотр включен

Options

Настраивать компонент можно с помощью свойств объекта options, передаваемого в конструктор new JS360(options) или через data атрибуты в html шаблоне. Данные, переданные через data атрибуты приоритетнее, и при одинаковых свойствах, они перезапишут свойства объекта options переданного в конструктора JS.

• autoPlay || data-auto-play

  type: boolean
  обязательное: нет
  по-умолчанию: undefined

Запускает автоматическую прокрутку изображений после их загрузки.

const js360 = new JS360({
  baseUrl: 'http://my_rest',
  target:  '.js360',
  url:     'product.json',
  autoPlay: true
});

js360.render();

• baseUrl || data-base-url

  type: string
  обязательное: да

Определяет левую часть url, по которому будет запрошен массив изображений.

<div class="js360" data-base-url="http://my_first_rest" data-url="product.json"></div>

const js360 = new JS360({
  baseUrl: 'http://my_second_rest',
  target:  '.js360'
});

js360.render();

При одновременном указании baseUrl && data-base-url приоритет будет у baseUrl.
Массив закодированных изображений будет получен по адресу http://my_first_rest/product.json.

• controlLoad

  type: boolean
  обязательное: нет

Определяет кнопку управления загрузкой, которая перехватит на себя событие loadEvent (mousemove по-умолчанию).
Если не определена - загрузка активируется через контейнер.
Для корректной отрисовки, необходимо подключить style.css.

import 'js360/style.css';

const js360 = new JS360({
  baseUrl:     'http://my_rest',
  target:      '.js360',
  url:         'product.json',
  controlLoad: true
});

js360.render();

• controlPlay

  type: boolean
  обязательное: нет

Создает кнопку управления (старт / пауза) автоматическим просмотром. Для корректной отрисовки, необходимо подключить style.css.

import 'js360/style.css';

const js360 = new JS360({
  baseUrl:     'http://my_rest',
  target:      '.js360',
  url:         'product.json',
  controlPlay: true
});

js360.render();

• height || data-height

  type: integer
  обязательное: нет
  по-умолчанию: container.clientHeight || 180

Если задан - определяет высоту контейнера, которая наследуется в канвас и изображение.

• loadEvents || data-load-events

  type: array, stringified array
  обязательное: нет
  по-умолчанию: ['mousemove']

По-умолчанию, загрузка изображений происходит на событие mousedown. Это поведение можно изменить следующим образом.

const js360 = new JS360({
  baseUrl: 'http://my_rest',
  target:  '.js360',
  url:     'product.json',
  loadEvents: ['mousedown', 'touchstart']
});

js360.render();

Теперь загрузка изображений активируется на события ['mousedown', 'touchstart'].

• preloader || data-preloader

  type: boolean обязательное: нет по-умолчанию: undefined

Если true - в момент начала загрузки изображений в контейнер будет добавлен прелоадер. Note: Чтобы прелоадер корректно отрисовался, необходимо добавить файл styles.css из папки компонента.

import 'js360/styles.css';

const js360 = new JS360({
  baseUrl: 'http://my_rest',
  target:  '.js360',
  url:     'product.json',
  preloader: true
});

js360.render();

• preview || data-preview

  type: string
  обязательное: нет

Определяет изображение для предпоказа модели, пока основной конент еще не загружен или загрузка не инициирована.
Свойство не обязательное, но следует иметь ввиду, если изображение для предпоказа не определено, после инициализации компонента, он будет пустым белым прямоугольником.

const js360 = new JS360({
  baseUrl: 'http://my_rest',
  target:  '.js360',
  preview: '.assets/product.jpeg'
});

js360.render();

• retinaUrl || data-retina-url

  type: string
  обязательное: нет

Определяет правую часть url строки, по которой будет получен массив изображений при следующих условиях:

• window.devicePixelRatio === 2
• заданы параметры retinaUrl || data-retina-url

const js360 = new JS360({
  baseUrl:   'http://my_rest',
  target:    '.js360',
  url:       'product.json',
  retinaUrl: 'retina-product.json'
});

js360.render();

Для устройств devicePixelRatio которых отличается от 2 изображения будут получены по адресу http://my_rest/product.json.
Для ретина экранов изображения будут получены по адресу http://my_rest/retina-product.json.

• rotateEvents || data-rotate-events

  type: array, stringified array
  обязательное: нет
  по-умолчанию: ['mousedown']

По-умолчанию, прокрутка изображений происходит на событие mousedown. Это поведение можно изменить следующим образом.

<div class="js360" data-rotate-events='["mousemove"]'></div>

const js360 = new JS360({
  baseUrl: 'http://my_rest',
  target:  '.js360',
  url:     'product.json'
});

js360.render();

Теперь прокрутка изображений активируется на событие mousemove.

• speed || data-speed

  type: integer, float (округляется до 2х цифр после запятой)
  обязательное: нет
  по-умолчанию: 1

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

const js360Slow = new JS360({
  baseUrl: 'http://my_rest',
  target:  '.js360',
  url:     'product.json',
  speed: 0.5
});

const js360Fast = new JS360({
  baseUrl: 'http://my_rest',
  target:  '.js360',
  url:     'product.json',
  speed: 2
});

js360Slow.render(); // за 1 полную ширину канваса будут прокручены половина всех изображений
js360Fast.render(); // за 1 полную ширину канваса все изображения будут прокручены 2 раза

• target

  type: string, NodeElement, NodeList
  обязательное: да

Определяет контейнеры, в которые будут добавлены канвасы.
Передавать можно css selector, NodeElement или NodeElement

const targetSelector = '.js360';
const targetNodeList = document.querySelectorAll('.js360');
const targetNodeElement = document.querySelector('.js360');

const js360 = new JS360({
  baseUrl: 'http://my_second_rest',
  target:  targetSelector || targetNodeList || targetNodeElement
});

js360.render();

• url || data-url

  type: string
  обязательное: да

Определяет правую часть url строки, по которой будет получен массив изображений.

const js360 = new JS360({
  baseUrl: 'http://my_rest',
  target:  '.js360',
  url:     'product.json'
});

js360.render();

Изображения будут получены по адресу http://my_rest/product.json.

• width || data-width

  type: integer
  обязательное: нет
  по-умолчанию: container.clientWidth || 320

Если задан - определяет ширину контейнера, которая наследуется в канвас и изображение.