Compartir por

Prácticas recomendadas y orientación para componentes de código creados con Power Apps component framework

  • Artigo

Desarrollar, implementar y mantener componentes de código necesita una combinación de conocimientos que incluye las siguientes áreas:

  • Power Apps component framework
  • Microsoft Power Apps
  • TypeScript y JavaScript
  • Desarrollo de la interfaz de usuario del navegador HTML
  • Azure DevOps/GitHub

Este artículo describe las mejores prácticas establecidas y la guía para los profesionales que desarrollan componentes de código. El objetivo de este artículo es describir los beneficios de cada uno para que los componentes de su código puedan aprovechar las mejoras de usabilidad, compatibilidad y rendimiento que ofrecen estas herramientas y sugerencias.

Power Apps component framework

Esta sección contiene las mejores prácticas y orientación relacionadas con Power Apps component framework en sí.

Evite implementar compilaciones de desarrollo para Dataverse

Los componentes de código se pueden incorporar en modo de producción o desarrollo. Evite implementar compilaciones de desarrollo para Dataverse ya que afectan negativamente el rendimiento e incluso pueden bloquearse su implementación debido a su tamaño. Incluso si planea implementar una compilación de versión más adelante, puede ser fácil olvidarse de volver a implementarlo si no tiene una canalización de lanzamiento automatizada. Más información: Depurar controles personalizados.

Evitar usar métodos de marco incompatibles

Estos incluyen el uso de métodos internos indocumentados que existen en el ComponentFramework.Context. Es posible que estos métodos funcionen pero, debido a que no son compatibles, es posible que dejen de funcionar en versiones futuras. No se admite el uso de script de control que obtiene acceso al Document Object Model (DOM) HTML de la aplicación host. Cualquier parte del DOM de la aplicación host que esté fuera del límite del componente de código está sujeta a cambios sin previo aviso.

Usar el método init para solicitar los recursos necesarios de la red

Cuando el contexto de alojamiento carga un componente de código, primero se llama al método init. Utilice este método para solicitar cualquier recurso de red, como metadatos, en lugar de esperar al método updateView. Si el método updateView se llama antes de que regresen las solicitudes, su componente de código debe manejar este estado y proporcionar un indicador de carga visual.

Limpiar los recursos dentro del método destroy

El contexto de alojamiento llama al método destroy cuando se elimina un componente de código del DOM del navegador. Utilice el método destroy para cerrar cualquier WebSockets y eliminar los controladores de eventos que se agregan fuera del elemento contenedor. Si está usando React, use ReactDOM.unmountComponentAtNode dentro del método destroy. La limpieza de recursos de esta manera evita cualquier problema de rendimiento causado por la carga y descarga de componentes de código dentro de una sesión de navegador determinada.

Evite llamadas innecesarias para actualizar una propiedad conjunto de datos

Si su componente de código es del tipo conjunto de datos, las propiedades enlazadas conjunto de datos exponen un método refresh que hace que el contexto de alojamiento vuelva a cargar los datos. Llamar a este método sin necesidad afecta al rendimiento de los componentes del código.

Minimizar las llamadas a notifyOutputChanged

En algunas circunstancias, no es deseable para las actualizaciones de un control de la interfaz de usuario (como pulsaciones de teclas o eventos de movimiento del mouse) para cada llamada notifyOutputChanged, ya que más llamadas a notifyOutputChanged darían lugar a que se propaguen al contexto principal muchos más eventos de los necesarios. En su lugar, considere usar un evento cuando un control pierde el foco o cuando se completa el evento de toque o ratón del usuario.

Comprobar disponibilidad de API

Al desarrollar componentes de código para diferentes hosts (aplicaciones controladas por modelos, de lienzo, portales), compruebe siempre la disponibilidad de las API que está utilizando para brindar soporte en esas plataformas. Por ejemplo, context.webAPI no está disponible en las aplicaciones de lienzo. Para conocer la disponibilidad de API individuales, consulte Referencia de API de Power Apps component framework.

Administrar valores de propiedad temporalmente nulos pasados a updateView

Los valores nulos se pasan al método updateView cuando los datos no están listos. Sus componentes deben tener en cuenta esta situación y esperar que los datos puedan ser nulos, y que un ciclo posterior de updateView pueda incluir valores actualizados. updateView está disponible para los componentes estándar y React.

Aplicaciones basadas en modelo

Esta sección contiene las mejores prácticas y orientación relacionada con los componentes de código dentro de las aplicaciones basadas en modelos.

No interactuar directamente con formContext

Si tiene experiencia trabajando con API de cliente, es posible que esté acostumbrado a interactuar con formContext para acceder a atributos, controles y llamar a métodos de API como save, refresh y setNotification. Se espera que los componentes de código funcionen en varios productos, como aplicaciones basadas en modelos, aplicaciones de lienzo, paneles y, por lo tanto, no pueden depender de formContext.

Una solución alternativa es hacer que el componente de código esté vinculado a una columna y agregar un controlador de eventos OnChange a esa columna. El componente de código puede actualizar el valor de la columna y el controlador de eventos OnChange puede acceder al formContext. En el futuro se agregará soporte para los eventos personalizados, lo que permitirá comunicar cambios fuera de un control sin agregar una configuración de columna.

Limitar el tamaño y la frecuencia de las llamadas a WebApi

Al usar los métodos context.WebApi, limite tanto el número de llamadas como la cantidad de datos. Cada vez que llame a WebApi, contará para los derechos de API del usuario y los límites de protección del servicio. Al realizar operaciones CRUD en registros, tenga en cuenta el tamaño de la carga útil. En general, cuanto mayor sea la carga útil de la solicitud, más lento es el componente de su código.

Aplicaciones de lienzo

Esta sección contiene las mejores prácticas y orientación relacionada con los componentes de código dentro de las aplicaciones de lienzo.

Minimizar la cantidad de componentes en una pantalla

Cada vez que agrega un componente a su aplicación de lienzo, se necesita una cantidad finita de tiempo para representar. El tiempo de renderizado aumenta con cada componente que agrega. Mida cuidadosamente el rendimiento de los componentes de su código a medida que agrega más a una pantalla con las herramientas de rendimiento de desarrollo.

Actualmente, cada componente de código incluye su propia biblioteca de bibliotecas compartidas, como Fluent UI y React. La carga de varias instancias de la misma biblioteca no cargará estas bibliotecas varias veces. Sin embargo, cargar varios componentes de código diferentes hará que el navegador cargue varias versiones empaquetadas de estas bibliotecas. En el futuro, estas bibliotecas podrán cargarse y compartirse con componentes de código.

Permita que los creadores diseñen su componente de código

Cuando los creadores de aplicaciones consumen componentes de código desde dentro de una aplicación de lienzo, quieren usar un estilo que coincida con el resto de su aplicación. Utilice las propiedades de entrada para proporcionar opciones de personalización para los elementos del tema, como el color y el tamaño. Cuando utilice Microsoft Fluent UI, asigne estas propiedades a los elementos del tema proporcionados por la biblioteca. En el futuro, se agregará compatibilidad con temas a los componentes del código para facilitar este proceso.

Siga las mejores prácticas de rendimiento de las aplicaciones de lienzo

Las aplicaciones de lienzo proporcionan un amplio conjunto de mejores prácticas desde dentro de la aplicación y el verificador de soluciones. Asegúrese de que sus aplicaciones sigan estas recomendaciones antes de agregar componentes de código. Para obtener más información, consulte:

TypeScript y JavaScript

Esta sección contiene las prácticas recomendadas y orientación relacionada con TypeScript y JavaScript dentro de componentes de código.

ES5 frente a ES6

De forma predeterminada, los componentes del código apuntan a ES5 para admitir navegadores más antiguos. Si no desea admitir estos navegadores más antiguos, puede cambiar el destino a ES6 dentro del pcfproj de su carpeta tsconfig.json. Más información: ES5 frente a ES6.

Importaciones de módulos

Empaquete siempre los módulos que se requieren como parte de su componente de código en lugar de usar scripts que deben cargarse usando la etiqueta SCRIPT. Por ejemplo, si desea utilizar una API de gráficos que no es de Microsoft donde el ejemplo muestra cómo agregar <script type="text/javascript" src="somechartlibrary.js></script> a la página, esto no es compatible dentro de un componente de código. La agrupación de todos los módulos necesarios aísla el componente de código de otras bibliotecas y también admite la ejecución en modo fuera de línea.

Nota

Las bibliotecas compartidas a través de componentes utilizando nodos de biblioteca en el manifiesto del componente aún no se admiten.

Linting

Linting es donde una herramienta puede escanear el código en busca de posibles problemas. La plantilla utilizada por pac pcf init instala el módulo eslint a su proyecto y lo configura agregando un archivo .eslintrc.json. Eslint requiere la configuración para los estilos de codificación TypeScript y React. También se puede utilizar para solucionar algunos de estos problemas automáticamente siempre que sea posible. Para configurarlo,en la línea de comandos use:

npx eslint --init

Luego, responda las siguientes preguntas cuando se le solicite:

  • ¿Cómo le gustaría usar ESLint? Respuesta: Para verificar la sintaxis, encontrar problemas y aplicar el estilo del código

  • ¿Qué tipo de módulos utiliza su proyecto? Respuesta: Módulos JavaScript (importación / exportación)

  • ¿Qué marco utiliza su proyecto? Respuesta: React

  • ¿Su proyecto usa TypeScript? Respuesta: Sí

  • ¿Dónde se ejecuta su código? Respuesta: Navegador

  • ¿Cómo le gustaría definir un estilo para su proyecto? Respuesta: Responder preguntas sobre su estilo

  • ¿En qué formato quieres que esté su archivo de configuración? Respuesta: JSON (Esta respuesta actualiza el .eslintrc.json ya existente)

  • ¿Qué estilo de sangría usa? Respuesta: Espacios (Este estilo de sangría es el predeterminado de Visual Studio Code)

  • ¿Qué comillas usas para las cadenas? Respuesta: Única

  • ¿Qué finales de línea usa? Respuesta: Windows (Esta finalización de línea es el valor predeterminado de Visual Studio Code Estilo de terminaciones de línea de CRLF.)

  • ¿Necesita punto y coma? Respuesta: Sí

Nota

Puede personalizar esta configuración para que se adapte a sus necesidades particulares (por ejemplo, si no está usando React). Más información: Primeros pasos con ESLint.

Antes de poder usar eslint necesita agregar algunos scripts a package.json:

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

El script eslint acepta la carpeta que contiene su código. Reemplace MY_CONTROL_NAME para que sea el mismo nombre que el componente de código utilizado al llamar a pac pcf init.

Ya en la línea de comandos, puede usar:

npm run lint:fix

Este comando cambia el código del proyecto para que coincida con el estilo elegido, y también informa de algunos problemas que se resuelven más tarde.

Nota

ESLint señalará problemas con el código de la plantilla inicialmente (por ejemplo, constructor vacío). Puede agregar comentarios en línea para indicarle a ESLint que excluya las reglas como: // eslint-disable-next-line @typescript-eslint/no-empty-function

Además, puede agregar archivos para ignorar (por ejemplo, las interfaces generadas automáticamente), agregando lo siguiente a .eslintrc.json:

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

Más información: ignorePatterns en archivos de configuración.

Sugerencia

Puedes instalar la extensión Visual Studio Code que usa el archivo .eslintrc.json del proyecto para proporcionar resaltado de código para cualquier problema detectado, con la opción de solucionarlo directamente dentro del IDE. Más información: Administrar extensiones en Visual Studio Code.

Desarrollo de la interfaz de usuario del navegador HTML

Esta sección contiene las mejores prácticas y orientación relacionadas con el desarrollo de la interfaz de usuario del navegador HTML.

Uso de Microsoft Fluent UI React

Fluent UI React es el marco oficial de código abierto del front-end de React diseñado para crear experiencias que se adapten a la perfección a una amplia gama de productos de Microsoft. Power Apps usa Fluent UI, lo que significa que puede crear una interfaz de usuario que es consistente con el resto de sus aplicaciones.

Use importaciones basadas en rutas desde Fluent para reducir el tamaño del paquete

Actualmente, las plantillas de componentes de código utilizadas con pac pcf init no utilizarán el tree-shaking, que es el proceso por el que webpack detecta los módulos importados que no se utilizan y los elimina. Si importa desde Fluent UI utilizando el siguiente comando, importará y empaquetará toda la biblioteca:

import { Button } from '@fluentui/react'

Para evitar importar y empaquetar toda la biblioteca, puede usar importaciones basadas en rutas, donde el componente de biblioteca específico se importa usando la ruta explícita:

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

Al usar la ruta especificada, se reduce el tamaño de su paquete tanto en desarrollo como en versiones de lanzamiento.

Puede aprovechar la agitación de árboles (que solo afecta a las versiones de lanzamiento / producción) actualizando su tsconfig.json para utilizar la siguiente configuración de módulo dentro de la sección compilerOptions:

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

Más información: Fluent UI: uso avanzado.

Optimizar el renderizado de React

Al usar React, es importante seguir las prácticas recomendadas específicas de React con respecto a minimizar la representación de componentes, lo que resulta en una interfaz de usuario más interactiva. Algunas de las prácticas recomendadas se enumeran a continuación:

  • Solo haga una llamada a ReactDOM.render dentro del método updateView cuando el cambio de una propiedad vinculada o un aspecto del marco requiere que la interfaz de usuario refleje el cambio. Puede usar updatedProperties para determinar qué ha cambiado.
  • Use PureComponent (con componentes de clase) o React.memo (con componentes de función) donde sea posible para evitar repeticiones innecesarias de componentes cuando sus accesorios de entrada no han mutado.
  • Para componentes React grandes, deconstruye su IU en componentes más pequeños para mejorar el rendimiento.
  • Evite el uso de funciones de flecha y el enlace de funciones dentro de la función de renderizado, ya que estas prácticas crearán un nuevo cierre de devolución de llamada con cada render y hará que el componente secundario siempre se vuelva a renderizar cuando se renderice el componente principal. En su lugar, utilice el enlace de funciones en el constructor o utilice funciones de flecha de campo de clase. Vea Gestión de eventos - React.

Comprobar accesibilidad

Asegúrese de que los componentes del código sean accesibles para que puedan utilizarlos los usuarios que solo utilicen el teclado y los lectores de pantalla:

  • Proporcione alternativas de navegación con teclado a los eventos táctiles / del ratón. Por ejemplo, si su componente proporciona una lista desplegable, asegúrese de que un usuario pueda usar la pestaña para establecer el enfoque y luego navegar por las opciones usando las teclas de flecha.
  • Asegúrese de que los atributos alt y ARIA (Aplicaciones enriquecidas de Internet accesibles) se establecen para que los lectores de pantalla anuncien una representación precisa de la interfaz de los componentes del código. La biblioteca de interfaz de usuario de Microsoft Fluent hace que el uso de estos atributos sea fácil, ya que muchos de los componentes ya son accesibles y compatibles con lectores de pantalla.
  • Las herramientas para desarrolladores de los navegadores modernos ofrecen formas útiles de inspeccionar la accesibilidad. Utilice estas herramientas para buscar problemas de accesibilidad comunes con su componente de código.

Más información: Crear aplicaciones de lienzo accesibles en Power Apps.

Utilice siempre llamadas de red asincrónicas

Al realizar llamadas de red, nunca use una solicitud de bloqueo sincrónico, ya que esto hace que la aplicación deje de responder y cause un rendimiento lento. Más información: Interactúe con recursos HTTP y HTTPS forma asincrónica.

Escribir código para diversos exploradores

Las aplicaciones basadas en modelos, las aplicaciones de lienzo y los portales son compatibles con varios navegadores. Asegúrese de utilizar solo técnicas que sean compatibles con todos los navegadores modernos y pruebe con un conjunto representativo de navegadores para su público previsto.

Los componentes del código deben planificar la compatibilidad con varios clientes y formatos de pantalla

Los componentes de código se pueden renderizar en múltiples clientes (aplicaciones basadas en modelos, aplicaciones de lienzo, portales) y formatos de pantalla (móvil, tableta, web). Cuando se utilizan en aplicaciones basadas en modelos, los componentes de código conjunto de datos se pueden colocar en cuadrículas de formularios principales, cuadrículas de registros relacionados, subcuadrículas o tableros. Cuando se usa en aplicaciones de lienzo, los componentes de código se pueden colocar dentro de contenedores interactivos que cambian de tamaño dinámicamente usando la configuración proporcionada por el fabricante de la aplicación.

  • Usar trackContainerResize permite que los componentes del código respondan a los cambios en el ancho y alto disponibles. En algunos casos, al configurarlo se obtiene una interfaz de usuario diferente que se adapta al espacio disponible. El uso de allocatedHeight y allocatedWidth se puede combinar con getFormFactor para determinar si el componente de código se está ejecutando en un cliente móvil, tableta o web. Más información: consulte Tutorial de selector de opciones.
  • Implementar setFullScreen permite a los usuarios expandirse para usar toda la pantalla disponible donde el espacio es limitado. Más información: Componente de cuadrícula de la aplicación lienzo.
  • Si el componente de código no puede proporcionar una experiencia significativa en el tamaño de contenedor dado, debe deshabilitar la funcionalidad de manera adecuada y proporcionar comentarios al usuario.

Utilice siempre reglas con alcance CSS

Cuando implementa estilo en sus componentes de código usando CSS, asegúrese de que el CSS tiene el alcance de su componente mediante la generación automática de clases CSS aplicadas al elemento contenedor DIV para su componente. Si el código CSS tiene un ámbito global, podría romper el estilo existente del formulario o la pantalla donde se representa el componente de código. Si usa un marco de trabajo CSS de terceros, debe usar una versión de espacio de nombres del marco que ya tenga espacio de nombres o, de lo contrario, encapsular ese marco en un espacio de nombres, ya sea manualmente o mediante un preprocesador de CSS.

Por ejemplo, si su espacio de nombres es SampleNamespace y el nombre de su componente de código es LinearInputComponent, agregaría una regla CSS personalizada usando:

.SampleNamespace\.LinearInputComponent rule-name

Evite el uso de objetos de almacenamiento web

Los componentes de código no deben utilizar los objetos de almacenamiento web HTML, como window.localStorage y window.sessionStorage, para almacenar datos. Los datos almacenados localmente en el navegador del usuario o en el cliente móvil no son seguros y no se garantiza que estén disponibles de manera confiable.

ALM/Azure DevOps/GitHub

Vea el artículo sobre Gestión del ciclo de vida de las aplicaciones de componentes de código (ALM) para conocer las prácticas recomendadas sobre componentes de código con ALM/Azure DevOps/GitHub.