Widget API

Материал из SmartPlayer

Модуль для создания виджетов на основе шаблона

Внимание! В описании указаны могут быть указаны версии того или иного пакета, рекомендуется использовать их, т.к. на них было протестирована работоспособность, в противном случае, работоспособность не может быть гарантирована.

Создание шаблона виджета: Для того, что бы создать шаблон виджета, необходима установленная версия NodeJS версии 12.XX.XXX, npm версии 6.XX.XX В командной строке необходимо ввести: 'npx sp_create_widget_template widgetName' где 'widgetName' - название виджета, оно так же будет являться типом виджета. В текущую папку, из которой началась установка, будет создана папка с названием виджета, в которой будет находиться шаблон, так же, автоматически будут установлены необходимые зависимости. Установить или обновить пакеты можно вручную через команду 'npm i' или 'npm i имя_пакета'. Для того, что бы запустить dev-сервер необходимо ввести команду 'npm start', сборка виджета осуществляется командой 'npm run build', после чего в корне появится папка build со сборкой, а так же внутри папки будет zip архив с копией того, что находится в папке build, этот архив понадобится, если нужно будет открыть виджет в личном кабинете, предварительно скопировав архив туда. В папке src/components можно увидеть компонент TestComponent, который в свою очередь импортирован в AppMain. Он присутствует для примера и его можно заменить своим, так же стоит обратить внимание на стиль этого компонента, он прописан для позиционирования в рамках окна настроек виджета (о которых чуть ниже). Начинать разработку рекомендуется именно с компонента appMain. В шаблоне виджета можно встретить методы, которые присутствуют исключительно для ознакомления, что бы можно было увидеть живой пример взаимодействия, регистрации методов для общения с клиентскими приложениями и т.д. Ненужное можно удалить.

Модули в зависимостях

У шаблона есть в зависимостях установленные пакеты, список отображен в файле package.json, большинство из них - сторонние opensource библиотеки и подробное описание о них можно почитать на официальных страницах этих библиотек, но есть 2 пакета, которые разработаны компанией SmartPlayer специально для работы с шаблоном и которые требуют отдельного описания:

sp_widget_core - ядро виджета

Ядро виджета устанавливается с npm сервера командой “npm i sp_widget_core“ либо общей установкой пакетов через команду “npm i“ т.к. уже прописан в package.json.

Ядро содержит следующие методы:

ClientCommunicator Метод используется для “общения” с клиентскими приложениями, принимает 2 параметра, первый - список методов, которые необходимо зарегистрировать, второй(необязательный) - название платформы в виде строки для принудительного подключения провайдера для указанной платформы, поддерживаются значения: windows, linux, android, frontend. Вызов метода возвращает ряд новых методов: setListeners, executeListeners, deleteListeners, clearListeners, connect + указанные для регистрации методы, которые необходимо “прослушивать“, после чего их можно вызывать и на стороне виджета. connect делает подключение к провайдеру и возвращает Promise, setListeners устанавливает методы для прослушивания, executeListeners выполняет метод для прослушивания, deleteListeners удаляет слушатели, clearListeners очищает список для прослушивания. Пример установки и очистки слушателей в компоненте (при перерисовке компонента):

Пример описания методов для регистрации в отдельном файле:

Далее его можно импортировать и передать первым аргументом в ClientCommunicator

Logger Используется для логирования, вызов возвращает 3 метода: log, warn, err, которые могут быть использованы для различного типа логов, пример использования const logger = Logger() logger.log('Hello world!')

Messenger Используется для регистрации и удаления событий для postMessage

setDictionary Метод для привязки json файла к переводчику, принимает 1 аргумент - json файл

getLocale Метод возвращает текущую локаль

setLocale Метод устанавливает локаль, принимает 1 аргумент - строку с кодом локали (например “ru”)

translate Метод получения перевода по ключу из привязанного ранее словаря, согласно текущей установленной локали, пример с ru локалью: translate('helloWorld') => 'Привет, мир!

isExist Метод проверяет что переданное ему значение !== undefined && !== null, возвращает true или false

isArray Метод проверяет, является ли переданное значение массивом, возвращает true или false

isNotEmptyArray Метод проверяет, что переданный массив не пустой, возвращает true или false

isNotEmptyString Метод проверяет, что переданная строка не пуская, возвращает true или false

convertValueForEditorFormat Метод конвертирует значение под формат настроек виджета, используется для редактирования настроек виджета и возвращает объект типа: { 

   target: {
       value
   }

}

printError Метод выводит лог, который содержит префикс ERROR + переданное значение

getEnviromentOS Возвращает название системы, в которой запущен виджет

isAuthorizationUserExist Проверяет, авторизован ли пользователь, возвращает true или false


sp_widget_editor - модуль для редактирования настроек виджета

Сохранение настроек работает только, когда виджет запущен в контексте личного кабинета, т.е. сохранение настроек, которые представляют из себя json файл, расположенный в папке public, происходит посредством сервера SmartPlayer.

Модуль устанавливается командой ‘npm i sp_widget_editor’, так же он уже прописан в зависимостях в файле package.json и может быть установлен общей командой ‘npm i’.

Из пакета может быть импортировано:

WidgetEditor Компонент настроек виджета, принимает props и возвращает JSX разметку, пример использования можно посмотреть в только что создавшемся шаблоне, в компоненте app.

WidgetOptionsEditor Класс описывающий опции виджета, возвращает экземпляр опций на основе принятого объекта из settings.json, располагающегося в папке public виджета, пример оспользования есть в компоненте app.

getQueryStringValue Метод для проверки, в какой среде запущен виджет на данный момент (в ЛК либо отдельно на dev сервере по localhost или на клиентском приложении), используется для определения, нужно ли отображать шестеренку с настройками или нет, но так же можно использовать и для отображения или скрытия другого функционала, если необходимо принудительно открыть иконку шестеренки настроек в режиме работы dev-сервера либо для отладки на удаленном дисплее, нужно в метод при вызове передать 1 аргумент = true, после завершения разработки этот параметр необходимо убрать.

UI окна настроек виджета Окно делится на две области, слева располагается список настроек, справа превью виджета, которое в реальном времени отражает результат выбранных пользователем настроек. Так же, справа внизу расположен ряд кнопок для "применения", "сброса", "выгрузки настроек в файл", "загрузки настроек из файла". Настройки будут применены только после нажатия на кнопку "применить", кнопка "сбросить" в свою очередь откатывает изменения до момента открытия модального окна с настройками. В списке слева можно использовать следующие типы настроек: 1. размер шрифта

2. выбор цвета для стилизации элементов UI (в шаблоне есть пример стилизующий цвет фона согласно выбранному цвету в настройках)

3. выбор валюты, если в виджете планируется использовать api для получения курса валют, есть возможность добавление новой пары (валюта из которой конвертировать + валюта в которую конвертировать), настройка только хранит значение, она не предоставляет api для работы с валютами и не может быть использована как самостоятельная.

4. выбор изображения (выбор происходит в личном кабинете SmartPlayer)

5. выбор папки с изображениями (выбор происходит в личном кабинете SmartPlayer)

6. выбор видео (выбор происходит в личном кабинете SmartPlayer)

7. выбор папки с видео (выбор происходит в личном кабинете SmartPlayer)

8. выбор аудио (выбор происходит в личном кабинете SmartPlayer)

9. выбор папки с аудио (выбор происходит в личном кабинете SmartPlayer)

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

11. выбор папки со смешанным контентом (выбор происходит в личном кабинете SmartPlayer)

12. текстовое поле

13. числовое поле (принимает только числовые значения)

14. выбор опции с возможностью поиска по опциям.

15. мультивыбор опций

16. выбор языка, переключает текущую локаль на другую выбранную из четырех, доступные языки ('ru', 'en', 'es', 'pt')

17. выбор даты.

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

Настройки могут быть объединены в отдельные логические группы, пример можно посмотреть в файле app.tsx (в группу с заголовком объединены размер шрифта и фон для виджета), дублирование настройки одного типа не запрещено, главное в settings.json использовать разные ключи параметров, что бы избежать перезаписи одной настройки другой.

ВАЖНО!

Если виджет при разработке использует библиотеку React, желательно, что бы она совпадала с версией, которая прописана в зависимости у пакета sp_widget_editor, в противном случае, возможен конфликт. Узнать версию можно следующим образом: зайти в папку node_modules в корневой папке виджета, найти в ней папку sp_widget_editor, зайти в нее и открыть файл package.json, там в dependencies найти параметр “react" и посмотреть версию, далее сравнить с версией, которая прописана в package.json расположенном в корневой папке виджета.

Под какую версию браузера стоит писать виджет?

Каждое устройство на котором вы запускаете виджет, внутри себя содержит браузер. Версия веб движка зависит от прошивки, некоторе open source библиотеки могут не поддерживать старые версии движка, чтобы узнать версию движка:

  • запустите на устройстве через трансляцию ссылку https://html5test.com/ сайт покажет версию веб движка
  • зайти в информацию об устройстве и получить информацию нажатие иконки браузер на устройстве. Устройство вернет полную информацию о своем движке.
Источник — https://wiki.smartplayer.org/index.php?title=Widget_API&oldid=12143