Интеграция компонентов фронтенда

Общее введение

Введение во фронтенд-компоненты

Фронтенд-компоненты DJI FlightHub 2 включают: создание маршрута полета, редактор маршрута полета, виртуальную кабину и проект/карту. Эти компоненты поддерживают пользовательские темы и стили. В данном руководстве описано, как интегрировать эти компоненты в вашу собственную систему с нуля.

Подготовка к началу работы

Технологический стек: Поддерживаются React, Vue и HTML + CSS.
Требования к оборудованию: Для развертывания FlightHub 2 (локальная версия) см. руководство по развертыванию DJI FlightHub 2 (локальная версия).

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

Текущая версия в основном предоставляет следующие компоненты и соответствующие наборы функций. Вы можете загрузить Демо-версию и использовать данное руководство для настройки и отладки.

Доступные компоненты перечислены ниже:

Компонент	Набор функций	Скриншот функции
Создание маршрута полета	Типы маршрутов полета: - маршрут по точкам - маршрут по области - маршрут по склону - геометрический маршрут - маршрут интеллектуального создания маршрута в 3D Настройка стиля
Редактор маршрута полета	Типы маршрутов полета: - Маршрут по точкам - маршрут по области - маршрут по склону - геометрический маршрут - маршрут интеллектуального создания маршрута в 3D Функции маршрута полета: - редактирование и сохранение маршрута полета - аннотации карты - открытие Cesium - аннотации точек, линий и областей - загрузка модели Настройка стиля
Виртуальная кабина	Функции дистанционного управления: - взлет в одно нажатие - трансляция - ручной полет и отображение траектории при нажатии клавиш WASD - возврат домой в один клик Настройка стиля
Проект/Карта	Данные карты проекта: - аннотации точек, линий и областей - планирование маршрутов и траекторий полета - пользовательская область задачи, пользовательская зона с ограничениями - список устройств проекта - дрон док-станции - дрон для ручного полета

Видеоуроки

Добавить необходимые стили и зависимости

После развертывания FlightHub 2 (локальная версия) вы получите приватный IP-адрес. Введите этот приватный IP-адрес или доменное имя и порт в раздел HEAD блока кода.

<!DOCTYPE html>
<html>
  <head>
    <script type="text/javascript" src="http://Private IP or domain name/paas.js" fh2></script>
    <title>Demo</title>
  </head>
  <body>
  </body>
</html>

Информация о требованиях к фронтенд-компонентам

Фронтенд-компоненты зависят от возможностей, предоставляемых FlightHub 2 (локальная версия), поэтому необходимо получить значения projectToken и prjId локальной версии FlightHub 2. Способы получения этих данных приведены ниже:

projectToken: Откройте FlightHub 2 (локальная версия), перейдите в раздел «Моя организация» (домен развернутого FlightHub 2/user-center#/my-organization) > «Настройки организации» > «Синхронизация FlightHub», чтобы получить ключ организации. Значение этого ключа организации является projectToken.
prjId: Откройте FlightHub 2 (локальная версия), перейдите в список проектов, выберите проект и найдите идентификатор проекта в URL-адресе. Например: https://домен развернутого FlightHub 2/organization/4bf0039f-6434-44a8-b891-8d7b6b7ff132/project/aa9c7a78-4e97-4ced-8953-2cea96c07c00, где 4bf0039f-6434-44a8-b891-8d7b6b7ff132 — это orgId, а aa9c7a78-4e97-4ced-8953-2cea96c07c00 — это prjId.

Пример:

window.FH2.initConfig({
    serverUrl: 'http://Enter the domain name and backend service port here. Default port number is 30812',
    wssUrl: 'ws://Enter the domain name and backend service port here. Default port number is 30812/duplex/web',
    hostUrl: 'http://Enter the IP or domain name of the web page and the port number here',
 
    // Copy prjId value and paste here
    prjId: 'cdca2736-8096-4729-9bc7-497ad5b60d5e',
    // Copy projectToken value and paste here
    projectToken: 'MTczMDg4NDI1NHx1NUR3RWxNajc5VnF4QWJuY1BvZmxUenlwYzdnRnBUazFSQnRhMXZOODlPSlVrdFhQekdFTjJKb0I1UkNNUlhtaFR0M3k2WllBdWNJTFVGNDZ4eHp3aWJnSnZ0TjVhNDdNMDUtcUlNQmZRUEtKYjNHeWIyLVZNTm80Qzd6TnMyTUNNSmFsWjZVQ0tkVWtEOU1tWVB5cDNSeWhLQW1NUXJrSzhnQkJhVl9saW5Bazhwbl9KQzg2b2FmWUVULWJoMWowbWh2aEV5X1BtZW9pZm1sRGJmajNoa1QxN280emluNDk1eUFaTUw4ZEJMRmljczIxY0twVmZBNVhiMU81b3Y2UmlNY3dZazFHLTY4Q3ljdFJVdWZuUmVxUUo1VGxEcnJrYkFZNGlpTGVjdC1jNnprYU5nSkFpLWdRbXJ5M2JraEVGUlJJY3YwUUk1TUlDMzZDd2tRc2dlOHNIblFVaHNwb1ozVFJ2MmtoenhZa1pMN0RCbVk4QkVNOVNvaVN1NmszVGRBTE1MMWVLRE5wMFY5VmFrN0FJSzgtcjZaaUstaThwNU9yd0E0V05iNE15eWswc1lXRnFVUzJGZm1wdG0xR0k5WXB0TzRZZUpMeHhCNGVBNEZKZkdaTC1NUV9iRGtXR3EwNXBpOUlBSUd2WFBnYl8tbEJ0NV9qRTRtZG45SDJBZkdpUFZJSktrOFhhSkdqNHEtOUxaUXdvT2NSV0FhUklnQXdINFdFRHR3TGhrPXwr7HTdhghvb4TN9rYRlDyCE9Mzc4Q89m4H3_B24WRKVg=='
})

Примечание

Убедитесь, что вызов window.FH2 выполняется после полной загрузки страницы (load). Например, можно использовать addEventListener('load', cb) для определения функции обратного вызова cb и вызвать метод window.FH2 внутри этой функции.

Добавить контейнер для компонента

Например, чтобы добавить редактор маршрута, вставьте следующий код в ту часть вашего кода, где должен отображаться редактор маршрута:

<div class="fh2-container">
    <div id="wayline-header"></div>
    <div class="project-details">
        <div id="project-app-container"></div>
        <div id="project-middle-container"></div>
        <div id="project-right-micro-app" class="right-micro-app">
            <div class="maps-micro-app">
                <div id="project-map-app-placeholder" class="map-app-placeholder">
                    <div id="map-app-global" class="map-app-container"></div>
                </div>
            </div>
            <div id="wayline-app-container"></div>
        </div>
    </div>
</div>

Добавить стиль контейнера компонента

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

<!DOCTYPE html>
<html>
  <head>
    <!-- start -->
    <style>
        .fh2-container {
            display: flex;
            flex-direction: column;
            /* Set the width and height of the container where you want to load the component */
            height: 100vh;
            width: 100vw;
        }
 
        #project-app-container>div, .map-app-container>div {
            width: 100%;
            height: 100%;
        }
 
        .project-details {
            position: relative;
            width: 100%;
            display: flex;
            flex: 1;
            overflow: auto;
        }
 
        .project-details .right-micro-app {
            position: relative;
            display: flex;
            flex: 1;
        }
 
        .project-details .right-micro-app .maps-micro-app {
            display: flex;
            flex: 1;
        }
 
        .project-details .right-micro-app .map-app-placeholder {
            flex: 1;
            position: relative;
            display: flex;
            flex-direction: column;
        }
 
        .project-details .right-micro-app .map-app-container {
            height: 100%;
        }
 
        .project-details .right-micro-app #wayline-app-container {
            position: absolute;
            top: 0;
            left: 0;
            width: 100%;
            height: 100%;
            pointer-events: none;
        }
    </style>
    <title>Demo</title>
  </head>
  <body>
  </body>
</html>

Загрузка фронтенд-компонентов

На примере редактора маршрута полета компонент можно загрузить, передав в метод значения id и соответствующий wayline_id. Для получения дополнительной информации обратитесь к Руководство по интерфейсу.

window.FH2.loadWayline("wayline-app-container", {
      wayline_id: 'bded3cf1-c924-4cd0-95d0-4bd642ddda09',
})

Настройка элементов карты (необязательно)

В качестве примера пользовательского текста карты можно нажать Настроить карту в верхней части wayline.html и уменьшить масштаб карты, чтобы увидеть эффект.

<!DOCTYPE html>
<html>
  <head>
    <link href="./custom-style.css" rel="stylesheet">
  </head>
  <body>
    <div class="btn-bar">
        <button id="CesiumMapBtn" onclick="addCustomCesiumData()">Customize Map</button>
    </div>
    <script>
        const CesiumMapBtn = document.getElementById('CesiumMapBtn')
        CesiumMapBtn.style.display = 'none'
        window.addEventListener('load', function () {
            // Wait until the map instance is ready, and then display the map customization button
            window.FH2.subscribe('cesium-viewer-change', (key) => {
                if (window.FH2.cesiumViewer.global) {
                    CesiumMapBtn.style.display = 'inline-block'
                }
            })
        })
        
        // Example: Customize the map, adding custom text to the map
        function addCustomCesiumData () {
            for (const key in window.FH2.cesiumViewer) {
                if (Object.prototype.hasOwnProperty.call(window.FH2.cesiumViewer, key)) {
                    const ins = window.FH2.cesiumViewer[key].entities.add({
                        position: window.Cesium.Cartesian3.fromDegrees(113.93,  22.57, 50),
                        label: {
                            text: "User custom text",
                        },
                    })
                }
            }
        }
    </script>
  </body>
</html>

Настройка темы (необязательно)

Демонстрационный файл показывает возможность настройки стилей. Вы можете изменить соответствующие стили темы в custom-style.css и сразу увидеть результат во всех четырех HTML-файлах, включая wayline.html. Файл custom-style.css написан на CSS, поэтому, если в вашем проекте также используется CSS, вы можете напрямую изменить переменные стиля custom-style в своем проекте.

<!DOCTYPE html>
<html>
  <head>
    <link href="./custom-style.css" rel="stylesheet">
  </head>
  <body>
    <div class="btn-bar">
        <button onclick="changeTheme()">Customize Style</button>
    </div>
    <script>
        function changeTheme () {
            document.body.className = document.body.className ? '' : 'set-change-color'
        }
    </script>
  </body>
</html>

Добавление обработчика событий (необязательно)

На примере редактора маршрута полета можно подписаться на кнопку сохранения и получать соответствующие уведомления при сохранении или отмене маршрута полета.

window.FH2.subscribe('wayline-cancel', () => {
    console.log('Canceled saving flight route')
})
window.FH2.subscribe('wayline-save', () => {
    console.log('Flight route saved')
})

Руководство по интерфейсу

Экземпляр: window.FH2

Метод: validateToken

Параметр	Тип	Требуется	Описание
токен	string	TRUE	Возвращает результат проверки токена: true/false

Метод: initConfig

Параметр	Тип	Требуется	Описание
serverUrl	string	TRUE	Адрес HTTP-службы бекенда
wssUrl	string	TRUE	Адрес двунаправленной службы серверной части
hostUrl	string	TRUE	Адрес веб-входа фронтенда
prjId	string	TRUE	Идентификатор проекта
projectToken	string	TRUE	Токен аутентификации OpenAPI

Метод: loadWaylineCreation

Параметр	Тип	Требуется	Описание
domId	string	TRUE	Сторонний фронтенд предоставляет ID DOM-узла
props	Object<WaylineCreationConfig>	false	Подробное описание параметров приведено в таблице ниже: WaylineCreationConfig

Описание параметров WaylineCreationConfig:

Параметр	Тип	Требуется	Описание
folder_id	string	false	Папка, в которой сохраняется созданный маршрут полета. Значение — это ID папки. Если параметр не указан, используется папка по умолчанию.

Метод: destroyWaylineCreation

Параметр	Тип	Требуется	Описание
-	-	-	Уничтожить экземпляр компонента создания маршрута полета

Метод: loadWayline

Параметр	Тип	Требуется	Описание
domId	string	TRUE	Сторонний фронтенд предоставляет ID DOM-узла
props	Object<WaylineConfig>	TRUE	Подробное описание параметров приведено в таблице ниже: WaylineConfig.

Описание параметров WaylineConfig:

Параметр	Тип	Требуется	Описание
wayline_id	string	TRUE	Идентификатор маршрута

Метод: destroyWayline

Параметр	Тип	Требуется	Описание
isEffect	boolean	false	Уничтожить экземпляр редактора маршрута полета. Если на текущей странице загружено несколько компонентов, передача значения true при уничтожении экземпляра не повлияет на другие загруженные компоненты. Если параметр не передан, по умолчанию используется значение false.

Метод: loadCockpit

Параметр	Тип	Требуется	Описание
domId	string	TRUE	Сторонний фронтенд предоставляет ID DOM-узла
props	Object<CockpitConfig>	TRUE	Подробное описание параметров приведено в таблице ниже: CockpitConfig

Описание параметров CockpitConfig:

Параметр	Тип	Требуется	Описание
gatewaySn	string	TRUE	Серийный номер шлюза
droneSn	string	TRUE	Серийный номер дрона
карта	boolean	false	Загружать ли карту. Значение по умолчанию — true. Установка параметра метода в значение false предотвращает загрузку карты.

Метод: destroyCockpit

Параметр	Тип	Требуется	Описание
isEffect	boolean	false	Уничтожить экземпляр виртуальной кабины. Если на текущей странице загружено несколько компонентов, передача значения true при уничтожении экземпляра не повлияет на другие загруженные компоненты. Если параметр не передан, по умолчанию используется значение false.

Метод: loadProject

Параметр	Тип	Требуется	Описание
domId	boolean	TRUE	Загрузить карту проекта

Метод: destroyProject

Параметр	Тип	Требуется	Описание
-	-	-	Уничтожить карту проекта

Метод: loadFlightPath

Параметр	Тип	Требуется	Описание
domId	string	true	ID DOM-узла, предоставленный сторонним фронтендом
params	IFlightPathParams	true	Подробное описание параметров см. в таблице ниже: IFlightPathParams

Описание параметров IFlightPathParams:

Параметр	Тип	Требуется	Описание
flight_path_id	string	true	ID траектории полета

Метод: destroyFlightPath

Параметр	Тип	Требуется	Описание
-	-	-	Выгрузить запись полета

Метод: subscribe

Параметр	Тип	Требуется	Описание
eventName	string	TRUE	Подписка на события: - wayline-save: ВСрабатывает при сохранении маршрута полета, параметром callback является ID успешно сохраненного маршрута полета - wayline-cancel: Срабатывает при отмене сохранения маршрута полета, параметром callback является ID маршрута полета - wayline-back: Срабатывает при нажатии кнопки «Назад» в компоненте редактора маршрута полета, параметром callback является ID маршрута полета - wayline-creation-saved: Срабатывает при сохранении компонента создания маршрута полета, параметром callback является ID успешно сохраненного маршрута полета - wayline-creation-cancel: Срабатывает при отмене сохранения компонента создания маршрута полета - cesium-viewer-change: Срабатывает при обнаружении изменений в загрузке каждой карты Cesium - flight-path-back: Срабатывает при возврате из записи полета
callback	string	false	Передает ID текущего маршрута полета

Метод: cesiumViewer

Тип	Описание
{ [key: string]: CesiumViewer }	Данный метод предоставляет доступ ко всем экземплярам Cesium Viewer на текущей странице. В настоящее время ключевые значения включают: - global: Основная карта - wayline_editor_support: Вспомогательная карта в компоненте редактора маршрута полета.

Тип

Описание

{ [key: string]: CesiumViewer }

Данный метод предоставляет доступ ко всем экземплярам Cesium Viewer на текущей странице. В настоящее время ключевые значения включают:
- global: Основная карта
- wayline_editor_support: Вспомогательная карта в компоненте редактора маршрута полета.

Экземпляр: window.Cesium

К нативным объектам Cesium можно получить доступ напрямую через объект window, поэтому пользователям не требуется самостоятельно импортировать cesium.js.

Ответы на вопросы

Почему при вызове FH2 возникает ошибка «свойство не назначено»?

Убедитесь, что вы вызываете метод window.FH2 после загрузки страницы (load). Вы также можете использовать addEventListener('load', cb) для определения функции обратного вызова и вызвать window.FH2 внутри этой функции.

Почему цвет фона тела веб-страницы становится белым после загрузки компонента FlightHub 2?

В настоящее время при загрузке компонента FlightHub 2 к цвету фона тела применяется глобальный стиль, который может переопределить исходный стиль сайта. В этом случае необходимо задать стиль с более высоким приоритетом для фона сайта, например с использованием !important.

Почему при использовании компонента FlightHub 2 у некоторых элементов интерфейса наблюдается некорректное позиционирование?

Например, при добавлении точек маршрута, аннотаций и уведомлений в редакторе маршрута полета позиционирование некоторых элементов может быть некорректным. Решение: Убедитесь, что контейнер компонента и его родительские контейнеры не имеют следующих свойств стиля: 1. transform или perspective не равны none; 2. filter не равен none; 3. will-change имеет значение transform или perspective; 4. contain имеет значение paint

Как выполнить вывод типов в TypeScript?

Обратитесь к следующему коду:

export type eventName = 'wayline-save' | 'wayline-cancel' | 'cesium-viewer-change'
export interface IWaylineParams {
  wayline_id: string;
}
 
export interface ICockpitParams {
  gateway_sn: string;
  drone_sn: string;
}
 
export interface IFH2Config {
  userId: string;
  orgId: string;
  prjId: string;
  serverUrl: string;
  wssUrl: string;
  hostUrl: string;
  token?: string;
}
export interface FH2 extends Record<string, any> {
  validateToken: (token: string) => boolean;
  initConfig: (config: IFH2Config) => void;
  subscribe: (eventName: eventName, callback: (...args: any[]) => void) => void;
  unsubscribe: (eventName: eventName) => void;
  destroyWayline: () => void;
  loadWayline: (domId: string, routerName: string, params?: IWaylineParams) => void;
  updateWayline: (routerName: string, params?: IWaylineParams) => void;
}

Интеграция компонентов фронтенда

# Общее введение

# Введение во фронтенд-компоненты

# Подготовка к началу работы

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

# Видеоуроки

# Добавить необходимые стили и зависимости

# Информация о требованиях к фронтенд-компонентам

#

# Добавить контейнер для компонента

# Добавить стиль контейнера компонента

# Загрузка фронтенд-компонентов

# Настройка элементов карты (необязательно)

# Настройка темы (необязательно)

# Добавление обработчика событий (необязательно)

# Руководство по интерфейсу

# Экземпляр: window.FH2

# Экземпляр: window.Cesium

# Ответы на вопросы