Pano2VR JavaScript API – это внешний программный интерфейс приложения, который позволяет управлять проигрывателем извне с помощью кода написанного на JavaScript. API позволяет не только управлять просмотром панорамы/тура, но и сохранять и считывать значения переменных, рисовать поверх панорамы, отслеживать события происходящие при просмотре панорамы и даже создать собственную интерактивную оболочку (скин) для виртуального тура.
Это заключительная часть. Все предыдущие части были актуализированы в соответствии с новой документацией: часть 1, часть 2.
API может использоваться как внутри оформления (скина), так и во внешнем коде страницы сайта. Для доступа к функциям API из оформления все методы следует вызывать от объекта player вместо pano.
Начальные установки
pano.readConfigUrl(url: String, base: String="");
Чтение конфигурации узла или тура (файл .xml) по заданному URL-адресу.
Необязательный аргумент base определяет другой базовый путь, который добавляется к относительным именам файлов и URL-адресам. Это важно, если базовые пути html-файла и xml-файла конфигурации отличаются.
pano.readConfigUrlAsync(url: String, callback: Function, base: String="");
Чтение конфигурацию узла или тура (файл .xml) по заданному URL-адресу. Асинхронный вызов.
Аргумент callback – функция, которая выполнится в после завершения вызова метода.
var startPan = 100; var startTilt = 0; var startFov = 70; pano.readConfigUrlAsync("/virtual_tours/tour_1/tour_config.xml", function() { pano.setPan(startPan); pano.setTilt(startTilt); pano.setFov(startFov); gyro = new pano2vrGyro(pano, "container"); gyro.disable(); gyro.setTrueNorth(true); });
pano.readConfigString(xml: String);
Чтение конфигурации узла или тура из строки (xml-данные).
pano.readConfigXml(xml: Document);
Чтение конфигурации узла или тура из xml-объекта).
pano.getBasePath();
Получение базового пути.
pano.setBasePath(path: string);
Установка базового пути.
pano.setCrossOrigin(s: String);
Установка атрибута crossorigin для всех внешних файлов, таких как конфигурация, изображения, тайлы и встроенные видео. Значение по умолчанию – anonymous.
Работа с медиа-элементами
pano.playSound(id: String);
Воспроизведение звука с указанным идентификатором.
pano.pauseSound(id: String);
Приостановка (пауза) воспроизведения звука с указанным идентификатором.
pano.playPauseSound(id: String, loop: Number);
Последовательное переключение между приостановкой (паузой) и воспроизведением звука с указанным идентификатором.
pano.playStopSound(id: String, loop: Number);
Последовательное переключение между остановкой и воспроизведением звука с указанным идентификатором.
pano.soundGetTime(id: String): Number;
Получение позиции (времени) воспроизводимого в данный момент звука.
pano.soundSetTime(id: String, time: Number);
Установка позиции (времени) воспроизводимого в данный момент звука.
pano.activateSound(id: String, state: Number);
Отображение изображения или видео с указанным идентификатором.
Аргумент state принимает значения:
- 0 – скрыть,
- 1 – показать,
- 2 – переключить.
pano.stopSound(id: String);
Остановка воспроизведения звука с указанным идентификатором мультимедиа.
pano.isPlaying(id: String): Boolean;
Проверяет, воспроизводится ли этот медиа-элемент в данный момент.
pano.setVolume(id: String, volume: Number);
Устанавливает фиксированное значение громкости (от 0,0 до 1,0) для указанного элемента. Если передан id "_main", то изменения касаются общей громкости.
pano.changeVolume(id: String, volumen: Number);
Изменяет фиксированное значение громкости (от 0,0 до 1,0) для указанного элемента. Если передан id "_main", то изменения касаются общей громкости.
pano.disableSoundLoading();
Предотвращение загрузки звуковых медиа-элементов.
pano.setMediaVisibility(id: String, state: Number);
Изменение видимости закрепленного изображения или видео.
Аргумент state принимает значения:
- 0 – скрыть,
- 1 – показать,
- 2 – переключить.
pano.getMediaObject(id: String);
Возвращение исходного объекта определенного закрепленного медиа-элемента.
pano.changeLensflares(v: Number);
Настройка видимости бликов.
Аргумент v принимает значения:
- 0 – скрыть,
- 1 – показать,
- 2 – переключить.
Работа с режимом VR
pano.enterVR(): boolean;
Вход в режим VR.
pano.exitVR(): boolean;
Выход из режима VR.
pano.toggleVR(): boolean;
Переключение (последовательный вход / выход) режима VR.
pano.isInVR(): boolean;
Возвращает true, если проигрыватель в данный момент находится в режиме VR.
pano.hasVR(): boolean;
Возвращает true, если устройство поддерживает режим VR.
Разное
pano.getIsLoading();
Возвращает true, если панорама все еще загружается.
pano.getIsLoaded();
Возвращает true, если панорама полностью загружена.
pano.getPercentLoaded(): Number;
Получение процента загрузки панорамы (число от 0,0 до 1,0).
pano.getIsTileLoading();
Возвращает true, если в текущий момент загружаются плитки с несколькими разрешениями (мультирезолюшн).
pano.setLocked(value: Boolean);
Отключение любого взаимодействия с панорамой.
pano.setLockedMouse(value: Boolean);
Отключение взаимодействия с помощью мыши с панорамой.
pano.setLockedKeyboard(value: Boolean);
Отключение взаимодействия с помощью клавиатуры с панорамой.
pano.setLockedWheel(value: Boolean);
Отключение взаимодействия с помощью колесика мыши с панорамой.
pano.getPositionAngles(x: Number, y: Number): Object;
Получение значений поворота и наклона в точке с указанными координатами в окне проигрывателя. Текущее положение панорамы учитывается. Начало координат – левый верхний угол.
pano.getPositionRawAngles(x: Number, y: Number):Object;
Аналогично предыдущему. Отличие в том, что текущее положение панорамы не учитывается и принимается равным pan = 0, tilt = 0.
{pan: 18.03243237689469, tilt: -21.7158595533179}
pano.setMargins(l: Number, t: Number, r: Number, b: Number);
l, t, r, b – соответственно левый, верхний, правый, нижний край окна проигрывателя.
Установка отступов от краев окна проигрывателя аналогично установке отступов через редактор оформления.
pano.getViewerSize(): Object;
Получение размеров окна проигрывателя в пикселах. Возвращается объект содержащий значения ширины и высоты:
{width: 890, height: 400}
pano.getViewMode(): Number;
Получение текущего режима просмотра (способ захвата изображения курсором или касанием на сенсорном экране).
pano.changeViewMode(v: Number);
Установка режима просмотра (способ захвата изображения курсором или касанием на сенсорном экране).
Значения, возвращаемые функцией getViewMode() и принимаемые аргументом v функции changeViewMode():
- 0 – непрерывный режим,
- 1 – режим перетаскивания,
- 2 – переключение между режимами.
pano.updatePanorama();
Перерисовка (обновление) панорамы.
pano.isTouching();
Проверка, прикасаются ли в данный момент к проигрывателю на мобильном устройстве. Если да, то возвращаемое значение – true.
pano.getIsMobile();
Проверка, работает ли проигрыватель в данный момент в браузере мобильного устройства.
pano.getGyroAvailable():Boolean;
Возвращает true, если на мобильном устройстве доступен датчик гироскоп.
pano.getUseGyro();
Проверка, используется ли в данный момент управление с помощью гироскопа на мобильном устройстве.
pano.setUseGyro(v: Boolean, useRoll: Boolean);
v – активное состояние (true/false).
useRoll – использовать ли угол крена при управлении (true/false).
Включение управления с помощью гироскопа на мобильном устройстве.
pano.getOS(): Number;
Получение названия операционной системы, в которой в данный момент работает проигрыватель.
Возвращаемые значения:
- 0 – Неизвестно,
- 1 – Windows,
- 2 – Mac,
- 3 – Linux,
- 4 – iOS,
- 5 – Android.
pano.getBrowser(): Number;
Получение названия браузера, в котором в данный момент работает проигрыватель.
Возвращаемые значения:
- 0 – Неизвестно,
- 1 – Chrome,
- 2 – Firefox,
- 3 – Safari,
- 4 – Edge,
- 5 – IE.
pano.getVariableValue(varName: String): Any;
Получение значения переменной, используемой в оформлении.
pano.setVariableValue(varName: String, varValue: Any);
Установка значения переменной, используемой в оформлении.
pano.setVariableOptions(varName: String, options: Object): Boolean;
Сохранение значения переменной в Cookie браузера. В случае успеха возвращает значение true.
varName – имя переменной, определенной в списке переменных редактора оформления.
varValue – значение переменной, имеющее один из типов: число, строка и логический (true/false).
options – объект параметров:
- keep – логический тип (true/false). При значении true переменная сохраняется в Сookie браузера и будет считываться при повторном открытии проекта,
- cookiePath – путь Cookie,
- cookieExpireDays – число, количество дней до истечения срока действия Cookie.
javascript: player.setVariableOptions("language",{ keep:true, cookiePath: "/", cookieExpireDays:10 });
pano.setSuperCookie(superCookieName: String, options: Object);
Создание Super Cookie. Эта настройка объединяет несколько Cookie в одну группу и таким образом позволяет обойти ограничение в 50 Cookie на домен.
После определения Super Cookie все дальнейшие сохранения значений переменных с помощью функции setVariableOptions() будут производиться в Super Cookie.
superCookieName – имя Super Cookie.
options – объект параметров:
- cookiePath – путь Cookie,
- cookieExpireDays – число, количество дней до истечения срока действия Cookie.
javascript: pano.setSuperCookie("FirstProjectSettings",{ cookiePath: "/", cookieExpireDays:100 });
pano.getMapsContainingNode(id: String): Array;
Возвращает массив идентификаторов карт (планов этажей), на которых расположен узел с заданным идентификатором.
pano.getMapIDs(): Array;
Возвращает массив всех идентификаторов карт в проекте.
pano.getFloorplanIDs():Array;
Возвращает список всех идентификаторов планов этажей в проекте.
pano.hasMap():Boolean;
Возвращает true, если в проекте есть хотя бы одна карта.
pano.hasFloorplan():Boolean;
Возвращает true, если в проекте есть хотя бы один план этажа.
pano.getFirstMap():String;
Возвращает идентификатор первой карты в проекте.
pano.getFirstFloorplan():String;
Возвращает идентификатор первого плана этажа в проекте.
pano.getLanguage():String;
Возвращает код языка, используемого проигрывателем в данный момент (например, «en» или «en-US»).
pano.setLanguage(langCode:String);
Устанавливает язык проигрывателя по заданному коду языка.
События
pano.addListener(eventName: String, listener: Function);
Регистрация собственного обработчика события.
pano.on(eventName: String, listener: Function);
Регистрация собственного обработчика события.
pano.addListener("projectionchanged", function() { console.log("Изменилась проекция панорамы!"); }); pano.on("changenode", function() { console.log("Вы перешли в другой узел тура!"); });
pano.removeEventListener(eventName: String, listener: Function);
Удаление собственного обработчика события.
pano.triggerEvent(eventName: String);
Ручной вызов собственного обработчика события.
eventName – определенное имя события из списка ниже.
listener – любая функция, которая будет срабатывать всякий раз при возникновении события. В функции removeEventListener() в качестве аргумента listener передается ссылка на функцию, которую нужно сохранить в переменной при вызове функции.
//Создание обработчика pano.addListener("configloaded", func = function() { console.log("Конфигурация загружена!"); }); //Удаление обработчика pano.removeEventListener("configloaded", func);
или так
var func = function() { console.log("Конфигурация загружена!"); } //Создание обработчика pano.addListener("configloaded", func); //Удаление обработчика pano.removeEventListener("configloaded", func);
Список доступных событий:
Название события |
Описание |
configloaded |
Файл конфигурации загружен |
downloadprogress |
Каждый раз при загрузке изображений |
beforechangenode |
Перед изменением узла (панорамы) тура |
changenode |
После изменения узла (панорамы) тура |
sizechanged |
Размер окна проигрывателя изменился |
viewmodechanged |
Режим просмотра изменился |
polymodechanged |
Режим полигональной активной зоны изменился |
gyrochanged |
Изменилось настройки гироскопа на мобильных устройствах (включен / отключен) |
autorotatechanged |
Авторотация запущена / остановлена |
imagesready |
Загрузка панорамы завершена |
timer |
Непрерывный таймер |
positionchanged |
Положение панорамы (поворот / наклон / угол обзора) изменилось |
projectionchanged |
Проекция панорамы изменилась |
fullscreenenter |
Произведен вход в полноэкранный режим |
fullscreenexit |
Произведен выход из полноэкранного режима |
playerstatechanged |
Одно из состояний проигрывателя изменилось, например, hasGyro(), hasVR() и др. |
repaint |
Каждый раз при перерисовке (обновлении) панорамы |
tilesrequested |
Начало загрузки тайлов мультрезолюшн |
tilesready |
Завершение загрузки тайлов мультрезолюшн |
videostarted |
Воспроизведение видеоэлемента началось |
videopaused |
Воспроизведение видеоэлемента было приостановлено |
videoended |
Воспроизведение видеоэлемента завершилось |
hotspotsremoved |
Произошло удаление активных зон из текущей панорамы |
clonerchanged |
Каждый раз при обновлении компонента Cloner |
varchanged_varname |
Каждый раз при изменении значения определенной переменной |
webglready |
Контекст WebGL создан |
renderframe |
К этому событию можно добавить код для рисования поверх панорамы. Используйте функцию getWebGlContext() чтобы получить контекст WebGL. |