Práticas recomendadas e diretrizes para componentes de código criados usando Power Apps estrutura de componentes

Use estas práticas recomendadas da estrutura de componentes do Power Apps para desenvolver, implantar e manter componentes de código com mais usabilidade, facilidade de suporte e melhor desempenho. As diretrizes abrangem as seguintes áreas:

• Estrutura de componentes do Power Apps
• Aplicativos do Microsoft Power
• TypeScript e JavaScript
• Desenvolvimento da interface do usuário do navegador HTML
• Azure DevOps/GitHub

Este artigo descreve as melhores práticas e diretrizes estabelecidas para profissionais que desenvolvem componentes de código. Este artigo tem como objetivo descrever os benefícios por trás de cada um para que os componentes de código possam aproveitar a usabilidade, a capacidade de suporte e os aprimoramentos de desempenho que essas ferramentas e dicas fornecem.

Estrutura de componentes do Power Apps

Esta seção contém as práticas recomendadas e as diretrizes relacionadas à própria estrutura de componentes Power Apps.

Evite implantar compilações de desenvolvimento no Dataverse

Criar componentes de código no modo de produção ou desenvolvimento. Evite implantar versões de desenvolvimento no Dataverse, pois elas prejudicam o desempenho e podem até ter a implantação bloqueada devido ao seu tamanho. Mesmo se você planeja implantar uma compilação de lançamento mais tarde, pode ser fácil esquecer de reimplantar se você não tiver um pipeline de lançamento automatizado. Para obter mais informações, consulte Depurando controles personalizados.

Evite usar métodos de estrutura sem suporte

Não use métodos internos não documentados que existem no ComponentFramework.Context. Esses métodos podem funcionar, mas, como não têm suporte, podem parar de funcionar em versões futuras. Não há suporte para o uso do script de controle que acessa o aplicativo host HTML Document Object Model (DOM). Todas as partes do DOM do aplicativo host que estão fora do limite do componente de código estão sujeitas a alterações sem aviso prévio.

Use o método init para solicitar os recursos de rede necessários

Quando o contexto de hospedagem carrega um componente de código, ele primeiro chama o método de inicialização . Use esse método para solicitar recursos de rede, como metadados, em vez de aguardar o updateView método. Se o updateView método for chamado antes do retorno das solicitações, o componente de código deverá lidar com esse estado e fornecer um indicador de carregamento visual.

Limpar recursos dentro do destroy método

O contexto de hospedagem chama o método destroy quando um componente de código é removido do DOM do navegador. Use o método destroy para encerrar qualquer WebSockets e remover os manipuladores de eventos que você adiciona fora do elemento contêiner. Se você estiver usando o React, use ReactDOM.unmountComponentAtNode dentro do destroy método. A limpeza de recursos dessa forma evita problemas de desempenho causados por componentes de código carregando e descarregando em uma determinada sessão do navegador.

Evite chamadas desnecessárias de atualização em uma propriedade de um conjunto de dados

Se o componente de código for do tipo conjunto de dados, as propriedades associadas ao conjunto de dados expõem um método refresh que faz com que o contexto de hospedagem recarregue os dados. Chamar esse método desnecessariamente afeta o desempenho do componente de código.

Minimizar chamadas para notifyOutputChanged

Em algumas circunstâncias, não é desejável que atualizações em um controle de interface do usuário (como pressionamentos de teclas ou eventos de movimento do mouse) façam uma chamada a notifyOutputChanged a cada ocorrência, pois mais chamadas a notifyOutputChanged resultam na propagação de muito mais eventos para o contexto pai do que o necessário. Em vez disso, considere usar um evento quando um controle perde o foco ou quando o evento de toque ou de mouse do usuário for concluído.

Verificar a disponibilidade da API

Ao desenvolver componentes de código para hosts diferentes (aplicativos controlados por modelos, aplicativos de tela, portais), sempre verifique a disponibilidade das APIs que você está usando para obter suporte nessas plataformas. Por exemplo, context.webAPI não está disponível em aplicativos de tela. Para verificar a disponibilidade de APIs individuais, consulte a referência da API da estrutura de componentes do Power Apps.

Gerenciar valores de propriedade temporariamente nulos passados para updateView

Valores nulos são passados para o updateView método quando os dados não estão prontos. Seus componentes devem considerar essa situação e esperar que os dados possam ser nulos e que um ciclo subsequente updateView possa incluir valores atualizados. updateView está disponível para componentes standard e React .

Aplicativos baseados em modelos

Esta seção contém as práticas recomendadas e as diretrizes relacionadas aos componentes de código em aplicativos controlados por modelos.

Não interaja diretamente com formContext

Se você tem experiência trabalhando com a API do cliente, talvez esteja acostumado a interagir com formContext para acessar atributos, controles e chamar métodos da API, como save, refresh e setNotification. Espera-se que os componentes de código funcionem em vários produtos, como aplicativos baseados em modelo, aplicativos de tela e painéis, portanto, não podem ter dependência de formContext.

Uma solução alternativa é tornar o componente de código associado a uma coluna e adicionar um OnChange manipulador de eventos a essa coluna. O componente de código pode atualizar o valor da coluna e o OnChange manipulador de eventos pode acessar o formContext. O suporte para os eventos personalizados será adicionado no futuro, o que permitirá a comunicação de alterações fora de um controle sem adicionar uma configuração de coluna.

Limitar o tamanho e a frequência das chamadas para o WebApi

Ao usar os context.WebApi métodos, limite o número de chamadas e a quantidade de dados. Cada vez que você invocar WebApi, isso será contabilizado na cota de API do usuário e nos limites de proteção de serviço. Ao executar operações CRUD em registros, considere o tamanho da carga. Em geral, quanto maior a carga útil da solicitação, mais lento ficará seu componente de código.

Aplicativos de tela

Esta seção contém as práticas recomendadas e as diretrizes relacionadas aos componentes de código em aplicativos de tela.

Minimizar o número de componentes em uma tela

Cada vez que você adiciona um componente ao seu aplicativo de tela, leva um tempo finito para renderizar. O tempo de renderização aumenta com cada componente adicionado. Avalie cuidadosamente o desempenho de seus componentes de código à medida que você adiciona mais a uma tela usando as ferramentas de Desempenho do Desenvolvedor.

Atualmente, cada componente de código inclui seu próprio conjunto de bibliotecas compartilhadas, como o Fluent UI e o React. Carregar várias instâncias da mesma biblioteca não carrega essas bibliotecas várias vezes. No entanto, o carregamento de vários componentes de código diferentes resulta no carregamento de várias versões agrupadas do navegador dessas bibliotecas. No futuro, você pode carregar e compartilhar essas bibliotecas com componentes de código.

Permitir que os criadores estilizem seu componente de código

Quando os criadores de aplicativos consomem componentes de código de dentro de um aplicativo de tela, eles querem usar um estilo que corresponda ao restante do aplicativo. Use propriedades de entrada para fornecer opções de personalização para elementos de tema, como cor e tamanho. Ao usar o Microsoft Fluent UI, mapeie essas propriedades para os elementos do tema fornecidos pela biblioteca. No futuro, o suporte a temas será adicionado aos componentes de código para facilitar esse processo.

Siga as práticas recomendadas de desempenho dos aplicativos de tela

Os aplicativos de tela fornecem um amplo conjunto de práticas recomendadas de dentro do aplicativo e do verificador de solução. Verifique se seus aplicativos seguem essas recomendações antes de adicionar componentes de código. Para obter mais informações, consulte:

• Dicas para melhorar o desempenho de aplicativos de tela
• Considerações para desempenho otimizado no Power Apps

TypeScript e JavaScript

Esta seção contém as práticas recomendadas e as diretrizes relacionadas ao TypeScript e JavaScript nos componentes de código.

ES5 vs. ES6

Por padrão, os componentes de código são direcionados ao ES5 para dar suporte a navegadores mais antigos. Se você não quiser dar suporte a esses navegadores mais antigos, altere o destino para ES6 dentro da tsconfig.jsonpastapcfproj. Para obter mais informações, consulte ES5 vs ES6.

Importações de módulo

Sempre empacote os módulos de que seu componente de código precisa, em vez de usar scripts que precisam ser carregados pela tag SCRIPT. Por exemplo, se você quiser usar uma API de gráfico não Microsoft em que o exemplo mostra a adição <script type="text/javascript" src="somechartlibrary.js></script> à página, essa abordagem não tem suporte dentro de um componente de código. Agrupar todos os módulos necessários isola o componente de código de outras bibliotecas e também dá suporte à execução no modo offline.

Configurar o ESLint para componentes de código

Linting é onde uma ferramenta verifica o código em busca de possíveis problemas. O modelo usado pelo pac pcf init instala o eslint módulo em seu projeto e o configura adicionando um .eslintrc.json arquivo. Eslint requer a configuração para os estilos de codificação TypeScript e React. Ele também pode corrigir alguns desses problemas automaticamente sempre que possível. Para configurar, use o seguinte comando:

npx eslint --init

Em seguida, responda às seguintes perguntas quando solicitado:

• Como você gostaria de usar ESLint? Resposta: Para verificar a sintaxe, encontre problemas e imponha o estilo de código

• Que tipo de módulos seu projeto usa? Resposta: módulos JavaScript (importação/exportação)

• Qual estrutura seu projeto usa? Resposta: React

• Seu projeto usa TypeScript? Resposta: Sim

• Onde o código é executado? Resposta: Navegador

• Como você gostaria de definir um estilo para seu projeto? Resposta: Responder perguntas sobre seu estilo

• Em que formato você deseja que o arquivo de configuração esteja? Resposta: JSON (esta resposta atualiza o existente .eslintrc.json)

• Que estilo de recuo você usa? Resposta: Espaços (esse estilo de recuo é o padrão do Visual Studio Code)

• Quais aspas você usa para cadeias de caracteres? Resposta: Único

• Quais terminações de linha você usa? Resposta: Windows (este final de linha é o estilo padrão de términos de linha CRLF Visual Studio Code).)

• Você precisa de ponto-e-vírgula? Resposta: Sim

Antes de usar eslint, você precisa adicionar alguns scripts ao package.json:

 "scripts": {
    ...
    "lint": "eslint MY_CONTROL_NAME --ext .ts,.tsx",
    "lint:fix": "npm run lint -- --fix"
  }

O eslint script aceita a pasta que contém seu código. Substitua MY_CONTROL_NAME pelo mesmo nome do componente de código usado ao chamar pac pcf init.

Agora, na linha de comando, você pode usar:

npm run lint:fix

Esse comando altera o código no projeto para corresponder ao estilo escolhido e também relata alguns problemas resolvidos posteriormente.

"ignorePatterns": ["**/generated/*.ts"]

Desenvolvimento da interface do usuário do navegador HTML

Esta seção contém as práticas recomendadas e as diretrizes para o desenvolvimento da interface do usuário do navegador HTML.

Usar Microsoft Fluent UI React

Fluent UI React é o framework oficial de front-end em React de código aberto projetado para criar experiências que se integram perfeitamente a uma ampla variedade de produtos da Microsoft. Power Apps em si usa a interface do usuário fluente, para que você possa criar uma interface do usuário consistente com o restante dos seus aplicativos.

Usar importações baseadas em caminho a partir do Fluent para reduzir o tamanho do bundle

Atualmente, os modelos de componentes de código usados com pac pcf init não usam tree-shaking. Tree-shaking é o processo no qual webpack detecta os módulos que você importa, mas não usa, e os remove. Se você importar do Fluent UI usando o comando a seguir, importará e incluirá toda a biblioteca no pacote:

import { Button } from '@fluentui/react'

Para evitar importar e agrupar toda a biblioteca, use importações baseadas em caminho em que você importa o componente de biblioteca específico usando o caminho explícito:

import { Button } from '@fluentui/react/lib/Button';

O uso do caminho específico reduz o tamanho do pacote em builds de desenvolvimento e de versão.

Você pode aproveitar o tree-shaking (que afeta apenas builds de release e produção) atualizando seu tsconfig.json para usar a seguinte configuração de módulo dentro da seção compilerOptions:

"module": "es2015",
"moduleResolution": "node"

Mais informações: interface do usuário fluente – uso avançado.

Otimizar a renderização do React

Ao usar o React, siga as práticas recomendadas específicas do React para minimizar a renderização de componentes. Essa abordagem resulta em uma interface do usuário mais responsiva. A lista a seguir inclui algumas das práticas recomendadas:

• Chame ReactDOM.render somente dentro do método updateView quando uma alteração em uma propriedade vinculada ou em um aspecto do framework exigir que a interface do usuário reflita essa alteração. Use updatedProperties para determinar o que mudou.
• Use PureComponent (com componentes de classe) ou React.memo (com componentes funcionais) sempre que possível para evitar re-renderizações desnecessárias dos componentes quando suas props de entrada não mudarem.
• Para componentes do React grandes, desconstrua sua interface do usuário em componentes menores para melhorar o desempenho.
• Evite usar funções de seta e associação de função dentro da função de renderização. Essas práticas criam uma nova closure de callback a cada renderização e fazem com que o componente filho seja sempre renderizado novamente quando o componente pai é renderizado. Em vez disso, use a vinculação de função no construtor ou funções de seta em campos de classe. Consulte manipulação de eventos – React.

Verificar a acessibilidade

Verifique se os componentes de código estão acessíveis para que os usuários somente teclado e leitor de tela possam usá-los:

• Forneça alternativas de navegação do teclado para eventos de mouse e toque. Por exemplo, se o componente fornecer uma lista suspensa, verifique se um usuário pode usar Tab para definir o foco e, em seguida, navegar pelas opções usando as teclas de direção.
• alt Verifique se os atributos ARIA (Aplicativos avançados de Internet acessíveis) estão definidos para que os leitores de tela anunciem uma representação precisa da interface do componente de código. A biblioteca de interface do usuário do Microsoft Fluent facilita o uso desses atributos, pois muitos dos componentes já são acessíveis e compatíveis com leitores de tela.
• As ferramentas de desenvolvedor do navegador moderno oferecem maneiras úteis de inspecionar a acessibilidade. Use essas ferramentas para procurar problemas comuns de acessibilidade com seu componente de código.

Para obter mais informações, consulte Criar aplicativos de tela acessíveis no Power Apps.

Sempre use chamadas de rede assíncronas

Ao fazer chamadas de rede, nunca use uma solicitação de bloqueio síncrona, pois essa solicitação faz com que o aplicativo pare de responder e resulte em desempenho lento. Para obter mais informações, consulte Interagir com recursos HTTP e HTTPS de forma assíncrona.

Escrever código para vários navegadores

Aplicativos baseados em modelos, aplicativos de tela e portais dão suporte a vários navegadores. Certifique-se de usar apenas técnicas com suporte em todos os navegadores modernos e testar com um conjunto representativo de navegadores para o público-alvo pretendido.

• Limites e configurações
• Navegadores da Web com suporte
• Navegadores usados pelo Office

Os componentes de código devem planejar o suporte a vários clientes e formatos de tela

Os componentes de código podem ser renderizados em vários clientes (aplicativos controlados por modelos, aplicativos de tela, portais) e formatos de tela (móvel, tablet, Web). Quando usados em aplicativos controlados por modelos, os componentes de código do conjunto de dados podem ser colocados em grades de formulário principais, grades de registro relacionadas, subgrids ou dashboards. Quando usados em aplicativos de tela, os componentes de código podem ser colocados dentro de contêineres responsivos que redimensionam dinamicamente usando a configuração fornecida pelo criador de aplicativos.

• Ao usar trackContainerResize, os componentes de código podem responder a alterações na largura e altura disponíveis. Em alguns casos, definir essa propriedade renderiza uma interface do usuário diferente que se ajusta ao espaço disponível. Você pode combinar allocatedHeight e allocatedWidth com getFormFactor para determinar se o componente de código está sendo executado em um cliente móvel, tablet ou web. Para obter mais informações, consulte este tutorial do seletor de Opções.
• Com a implementação setFullScreen, os usuários podem expandir para usar toda a tela disponível, onde o espaço é limitado. Para obter mais informações, consulte o componente de grade do aplicativo Canvas.
• Se o componente de código não puder fornecer uma experiência significativa no tamanho do contêiner fornecido, ele deverá desabilitar a funcionalidade adequadamente e fornecer comentários ao usuário.

Sempre use regras CSS com escopo

Ao implementar o estilo para seus componentes de código usando CSS, verifique se você define o escopo do CSS para o componente. Use as classes CSS geradas automaticamente aplicadas ao elemento de contêiner DIV do componente. Se você definir o escopo do CSS globalmente, poderá interromper o estilo existente do formulário ou da tela em que o componente de código é renderizado. Se você usar uma estrutura CSS de terceiros, use uma versão com espaçamento de nomes dessa estrutura ou encapsule a estrutura em um namespace manualmente ou usando um pré-processador CSS.

Por exemplo, se o namespace for SampleNamespace e o nome do componente de código for LinearInputComponent, adicione uma regra CSS personalizada usando:

.SampleNamespace\.LinearInputComponent rule-name

Evitar o uso de objetos de armazenamento da Web

Os componentes de código não devem usar os objetos de armazenamento da Web HTML, como window.localStorage e window.sessionStorage, para armazenar dados. Os dados armazenados localmente no navegador do usuário ou no cliente móvel não são seguros e não têm garantia de estar disponíveis de forma confiável.

ALM, Azure DevOps e GitHub

Para obter práticas recomendadas sobre componentes de código com ALM, Azure DevOps e GitHub, consulte o artigo sobre o ALM (gerenciamento do ciclo de vida do aplicativo de componente de código).

Artigos relacionados

• O que são componentes de código
• Componentes de código para apps de canvas
• Criar e construir um componente de código
• Conheça a estrutura de componentes do Power Apps
• Usar componentes de código no Power Pages