Integração de componentes frontend

Introdução básica

Introdução aos componentes de frontend

Os componentes de frontend do DJI FlightHub 2 incluem: criação de rotas de voo, editor de rotas de voo, cockpit virtual e projeto/mapa. Esses componentes são compatíveis com temas e estilos personalizados. Este manual apresentará como integrar esses componentes ao seu próprio sistema do zero.

Preparação antes de começar

Pilha de tecnologia: React, Vue e HTML + CSS são todos compatíveis.
Requisitos de hardware: Consulte o manual de implantação da versão local do DJI FlightHub 2 para implantar a versão local do FlightHub 2.

Ativação rápida

A versão atual oferece principalmente os seguintes componentes e coleções de recursos correspondentes. Você pode baixar o Demo e consultar este manual para configuração e depuração.

Os componentes lançados são os seguintes:

Componente	Coleção de recursos	Captura de tela de recurso
Criação de rota de voo	Tipos de rota de voo: - Rota de trajetória - Rota de área - Rota de inclinação - Rota geométrica - Rota de captura 3D Inteligente Personalização de estilo
Editor de rota de voo	Tipos de rota de voo: - Rota de trajetória - Rota de área - Rota de inclinação - Rota geométrica - Rota de captura 3D Inteligente Funções de rota de voo: - Edição e salvamento de rota de voo - Anotações de mapa - Abertura do Cesium - Anotações de ponto, linha e área - Carregamento de modelo Personalização de Estilo
Cabine virtual	Funções de controle remoto: - Decolagem com um clique - Transmissão ao vivo - Voo Manual e exibição de trajetória pressionando as teclas WASD - Personalização de Estilo de RTH com um clique
Projeto/Mapa	Dados do mapa do projeto: - Anotações de ponto, linha e área - Planejamento de rota de voo e de trajetória - Área de tarefa personalizada, Zona Restrita personalizada - Lista de dispositivos do projeto - Aeronave do dock - Aeronave de voo manual

Tutorial

Adicionar Estilos e Dependências Necessários

Após concluir a implantação da versão local do FlightHub 2, você receberá um IP privado. Insira este IP privado ou o nome de domínio e a porta na seção HEAD do bloco de código.

<!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>

Informações de conformidade dos componentes de frontend

Os componentes de frontend dependem dos recursos fornecidos pela versão local do FlightHub 2, portanto é necessário obter o projectToken e o prjId da versão local do FlightHub 2. Os métodos para obter as informações são os seguintes:

projectToken: Acesse a versão local do FlightHub 2, vá para My Organization (nome de domínio implantado do FlightHub 2/user-center#/my-organization) > Organization Settings > FlightHub Sync para obter a chave da organização. Esse valor de chave da organização é o projectToken.
prjId: Acesse a versão local do FlightHub 2, clique na lista de projetos, selecione um projeto e encontre o ID do projeto na URL. Por exemplo: https://deployed FlightHub 2 domain name/organization/4bf0039f-6434-44a8-b891-8d7b6b7ff132/project/aa9c7a78-4e97-4ced-8953-2cea96c07c00, em que 4bf0039f-6434-44a8-b891-8d7b6b7ff132 é o orgId e aa9c7a78-4e97-4ced-8953-2cea96c07c00 é o prjId.

Exemplo:

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=='
})

Observação

Certifique-se de que a chamada de window.FH2 seja executada após o carregamento completo da página (load). Por exemplo, você pode usar addEventListener('load', cb) para definir uma função de retorno de chamada cb e invocar o método window.FH2 dentro desse retorno de chamada.

Adicionar um contêiner para o componente

Por exemplo, para adicionar um editor de rota, insira o seguinte código na seção do seu código em que você deseja que o editor de rota seja exibido:

<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>

Adicione o Estilo do Contêiner de Componente

Abaixo estão os estilos de contêiner recomendados, que podem ser usados diretamente na área de código de destino. Se houver outros requisitos personalizados, você pode modificar o código de Estilo por conta própria.

<!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>

Carregar componentes de frontend

Usando o editor de rota de voo como exemplo, você pode carregar o componente passando o id e o wayline_id correspondente para o método. Consulte o Tutorial de Interface do manual para mais detalhes.

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

Personalizar elementos do mapa (Opcional)

Usando texto de mapa personalizado como exemplo, você pode clicar em Personalizar mapa na parte superior de wayline.html e diminuir o zoom do mapa para ver o efeito.

<!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>

Personalizar tema (Opcional)

O arquivo de demonstração mostra a capacidade de personalizar estilos. Você pode modificar os estilos de tema correspondentes em custom-style.css e ver imediatamente os efeitos nos quatro arquivos HTML, incluindo wayline.html. O arquivo custom-style.css é escrito em CSS, então, se o seu projeto também utilizar CSS, você pode ajustar diretamente as variáveis de estilo custom-style dentro do seu projeto.

<!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>

Adicionar listener de evento (Opcional)

Usando o editor de rota de voo como exemplo, você pode se inscrever no botão de salvar e receber avisos correspondentes ao salvar ou cancelar a rota de voo.

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

Tutorial da interface

Instância: window.FH2

Método: validateToken

Parâmetro	Tipo	Necessário	Descrição
token	string	true	Retorna o resultado da validação do token: true/false

Método: initConfig

Parâmetro	Tipo	Necessário	Descrição
serverUrl	string	true	Endereço do serviço HTTP de backend
wssUrl	string	true	Endereço do serviço Duplex de backend
hostUrl	string	true	Endereço de entrada da web do front-end
prjId	string	true	ID do projeto
Token de projeto	string	true	token de autenticação OpenAPI

Método: loadWaylineCreation

Parâmetro	Tipo	Necessário	Descrição
domId	string	true	O frontend de terceiros fornece o ID do nó MDO
propriedades	Objeto<WaylineCreationConfig>	false	Para uma descrição detalhada dos parâmetros, consulte a tabela abaixo: WaylineCreationConfig

Descrição dos parâmetros de WaylineCreationConfig:

Parâmetro	Tipo	Necessário	Descrição
folder_id	string	false	A pasta onde a rota de voo criada é armazenada. O valor é o ID da pasta. Se não for informado, será a pasta padrão.

Método: destroyWaylineCreation

Parâmetro	Tipo	Necessário	Descrição
-	-	-	Destruir a instância do componente de criação de rota de voo

Método: loadWayline

Parâmetro	Tipo	Necessário	Descrição
domId	string	true	O frontend de terceiros fornece o ID do nó MDO
propriedades	Objeto<WaylineConfig>	true	Para obter descrições detalhadas dos parâmetros, consulte a tabela abaixo: WaylineConfig.

descrição do parâmetro WaylineConfig:

Parâmetro	Tipo	Necessário	Descrição
wayline_id	string	true	ID da Wayline

Método: destroyWayline

Parâmetro	Tipo	Necessário	Descrição
isEffect	boolean	false	Destrua a instância do editor de rotas de voo. Se houver vários componentes na página atual, passar o valor "true" para destruir a instância não afetará os outros componentes carregados. Se nenhum parâmetro for passado, o padrão será false.

Método: loadCockpit

Parâmetro	Tipo	Necessário	Descrição
domId	string	true	O frontend de terceiros fornece o ID do nó MDO
propriedades	Objeto<CockpitConfig>	true	Para uma descrição detalhada dos parâmetros, consulte a tabela abaixo: CockpitConfig

Descrição dos parâmetros de CockpitConfig:

Parâmetro	Tipo	Necessário	Descrição
gatewaySn	string	true	Número de série do gateway
Número de série do drone	string	true	Nº de série da aeronave
map	boolean	false	Se o mapa deve ser carregado. O valor padrão é true. Definir o parâmetro do método como false impede o carregamento do mapa.

Método: destroyCockpit

Parâmetro	Tipo	Necessário	Descrição
isEffect	boolean	false	Destruir a instância de cockpit virtual. Se houver vários componentes na página atual, passar o valor "true" para destruir a instância não afetará os outros componentes carregados. Se nenhum parâmetro for passado, o padrão será false.

Método: loadProject

Parâmetro	Tipo	Necessário	Descrição
domId	boolean	true	Carregar mapa do projeto

Método: destroyProject

Parâmetro	Tipo	Necessário	Descrição
-	-	-	Destruir mapa do projeto

Método: loadFlightPath

Parâmetro	Tipo	Necessário	Descrição
domId	string	true	ID do nó DOM fornecido pelo frontend de terceiros
params	IFlightPathParams	true	Veja os detalhes dos parâmetros na tabela abaixo: IFlightPathParams

Descrição dos parâmetros IFlightPathParams:

Parâmetro	Tipo	Necessário	Descrição
flight_path_id	string	true	ID da trajetória de voo

Método: destroyFlightPath

Parâmetro	Tipo	Necessário	Descrição
-	-	-	Descarregar registro de voo

Método: subscribe

Parâmetro	Tipo	Necessário	Descrição
eventName	string	true	Assinar eventos: - wayline-save: Acionado ao salvar uma rota de voo, e o parâmetro de callback é o ID da rota de voo salva com sucesso - wayline-cancel: Acionado ao cancelar o salvamento de uma rota de voo, e o parâmetro de callback é o ID da rota de voo - wayline-back: Acionado ao clicar no botão voltar no componente do editor de rotas de voo, e o parâmetro de callback é o ID da rota de voo - wayline-creation-saved: Acionado ao cancelar o salvamento de um componente de criação de rota de voo e o parâmetro de callback é o ID da rota de voo salva com sucesso - wayline-creation-cancel: Acionado ao cancelar o salvamento de um componente de criação de rota de voo - cesium-viewer-change: Acionado quando são detectadas alterações no carregamento de cada mapa Cesium - flight-path-back: Acionado ao retornar do registro de voo
callback	string	false	Passe o ID da rota de voo atual

Método: cesiumViewer

Tipo	Explicação
{ [key: string]: CesiumViewer }	Este método fornece acesso a todas as instâncias do Cesium Viewer na página atual. Os valores de chave atualmente incluem: - global: Mapa principal - wayline_editor_support: Mapa auxiliar no componente do editor de rotas de voo.

Instância: window.Cesium

Objetos nativos do Cesium podem ser acessados diretamente por meio do objeto window, portanto os usuários não precisam importar o arquivo cesium.js manualmente.

Perguntas frequentes

Por que invocar FH2 resulta em um erro de "propriedade indefinida"?

Certifique-se de invocar o método window.FH2 após o carregamento (load) da página. Você também pode usar para definir uma função de retorno de chamada e invocar window.FH2 dentro dessa função.

Por que a cor de fundo do corpo da página da web fica branca após carregar o componente FlightHub 2?

Atualmente, o carregamento do componente FlightHub 2 aplica um estilo global à cor de fundo do corpo, o que pode substituir o estilo original do site. Nesse caso, você precisa definir um estilo de prioridade mais alta para a cor de fundo do site, como usar o estilo !important.

Por que o uso do componente FlightHub 2 faz com que alguns elementos da interface fiquem com posicionamento impreciso?

Por exemplo, ao adicionar pontos de passagem, anotações e mensagens de aviso no editor de rotas de voo, o posicionamento de alguns elementos fica impreciso. Solução: Certifique-se de que o contêiner do componente e seus contêineres pai não possuam as seguintes propriedades de estilo: 1. transform ou perspective não é none; 2. filter não é none; 3. will-change é transform ou perspective; 4. contain é paint

Como realizar inferência em TypeScript?

Consulte o seguinte código:

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;
}

Integração de componentes frontend

# Introdução básica

# Introdução aos componentes de frontend

# Preparação antes de começar

# Ativação rápida

# Tutorial

# Adicionar Estilos e Dependências Necessários

# Informações de conformidade dos componentes de frontend

#

# Adicionar um contêiner para o componente

# Adicione o Estilo do Contêiner de Componente

# Carregar componentes de frontend

# Personalizar elementos do mapa (Opcional)

# Personalizar tema (Opcional)

# Adicionar listener de evento (Opcional)

# Tutorial da interface

# Instância: window.FH2

# Instância: window.Cesium

# Perguntas frequentes