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

Use estos procedimientos recomendados del marco de componentes de Power Apps para desarrollar, implementar y mantener componentes de código con una mejor facilidad de uso, compatibilidad y rendimiento. En las instrucciones se describen las siguientes áreas:

• Marco de componentes de Power Apps
• Microsoft Power Apps: una plataforma para desarrollar aplicaciones personalizadas.
• 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.

Marco de componentes de Power Apps

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

Cree componentes de código en modo de producción o desarrollo. Evite implementar versiones de desarrollo en Dataverse, ya que afectan negativamente al rendimiento y su implementación puede incluso bloquearse 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. Para obtener más información, consulte Depuración de controles personalizados.

Evitar usar métodos de framework no compatibles

No use métodos internos no documentados del 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 hospedaje carga un componente de código, primero 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. Use el método destroy para cerrar cualquier WebSockets y quitar los controladores de eventos que agregue fuera del elemento contenedor. Si está usando React, use ReactDOM.unmountComponentAtNode dentro del método destroy. La limpieza de los recursos de esta manera evita problemas de rendimiento causados por la carga y descarga de componentes de código dentro de una sesión de explorador determinada.

Evite llamadas innecesarias para actualizar una propiedad conjunto de datos

Si el componente de código es de tipo conjunto de datos, las propiedades enlazadas del conjunto de datos exponen el método refresh, que provoca que el contexto de hospedaje recargue 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 que las actualizaciones de un control de interfaz de usuario (como pulsaciones de teclas o eventos de movimiento del ratón) llamen cada una a notifyOutputChanged, ya que más llamadas a notifyOutputChanged hacen que se propaguen al contexto principal muchos más eventos de los necesarios. En su lugar, considere utilizar un evento cuando un control pierda el foco o cuando finalice el evento táctil o de ratón del usuario.

Comprobar disponibilidad de API

Al desarrollar componentes de código para diferentes entornos host (aplicaciones basadas en modelos, aplicaciones de lienzo y portales), compruebe siempre la disponibilidad de las API que está utilizando para verificar su compatibilidad con 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.

Gestionar valores de propiedad temporalmente nulos que se pasan 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 controladas por modelos, aplicaciones de lienzo y paneles, por lo que no pueden tener una dependencia 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

Cuando se usan los context.WebApi métodos, limite el número de llamadas y la cantidad de datos. Cada vez que se invoca WebApi, se contabiliza para la capacidad asignada 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. 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 procedimientos recomendados y directrices sobre los componentes de código de las aplicaciones de lienzo.

Minimizar la cantidad de componentes en una pantalla

Cada vez que agregas un componente a tu aplicación de lienzo, tarda un tiempo determinado en renderizarse. El tiempo de renderizado aumenta con cada componente que agrega. Mida cuidadosamente el rendimiento de los componentes de código a medida que agregue más a una pantalla mediante las herramientas de rendimiento del desarrollador.

Actualmente, cada componente de código agrupa su propia biblioteca de bibliotecas compartidas, como Fluent UI y React. Cargar varias instancias de la misma biblioteca no carga 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, puede cargar y compartir estas bibliotecas 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.

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

• Consejos para mejorar el rendimiento de las aplicaciones de lienzo
• Consideraciones para rendimiento optimizado en Power Apps

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 dar soporte a estos navegadores más antiguos, cambie el destino a ES6 dentro del tsconfig.json de la carpeta pcfproj. Para obtener más información, consulte ES5 frente a ES6.

Importaciones de módulos

Agrupa siempre los módulos que requiera tu componente de código en lugar de usar scripts que requieran cargarse a través de la etiqueta SCRIPT. Por ejemplo, si desea usar una API de gráficos que no sea de Microsoft, donde el ejemplo muestra cómo agregar <script type="text/javascript" src="somechartlibrary.js></script> a la página, este enfoque no se admite 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.

Configuración de ESLint para componentes de código

Linting es donde una herramienta examina el código para detectar 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 puede corregir algunos de estos problemas automáticamente siempre que sea posible. Para configurar, use el siguiente comando:

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 utilizas? 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 (Este es el estilo de finales de línea CRLF predeterminado de Visual Studio Code.)

• ¿Necesita punto y coma? Respuesta: Sí

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.

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

Desarrollo de la interfaz de usuario del navegador HTML

Esta sección contiene procedimientos recomendados e instrucciones para el desarrollo de la interfaz de usuario del explorador 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 la interfaz de usuario de Fluent, por lo que puede crear una interfaz de usuario coherente con el resto de las aplicaciones.

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

Actualmente, las plantillas de componentes de código que se usan con pac pcf init no usan tree-shaking. El tree-shaking es el proceso por el que webpack detecta los módulos que importas pero no utilizas y los elimina. Si importa desde la interfaz de usuario de Fluent mediante el siguiente comando, importará y agrupará toda la biblioteca:

import { Button } from '@fluentui/react'

Para evitar importar y agrupar toda la biblioteca, use las importaciones basadas en rutas de acceso donde importe el componente de biblioteca específico mediante la ruta de acceso explícita:

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

Usar la ruta específica reduce el tamaño del paquete tanto en las compilaciones de desarrollo como en las de producción.

Puede aprovechar el tree shaking (que solo afecta a las compilaciones de lanzamiento y producción) si actualiza su tsconfig.json para usar 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, siga los procedimientos recomendados específicos de React para minimizar la representación de componentes. Este enfoque da como resultado una interfaz de usuario más dinámica. En la lista siguiente se incluyen algunos de los procedimientos recomendados:

• Llame solo a ReactDOM.render dentro del método updateView cuando un cambio en una propiedad enlazada o en algún aspecto del framework requiera que la interfaz de usuario refleje ese cambio. Use updatedProperties para determinar qué ha cambiado.
• Use PureComponent (con componentes de clase) o React.memo (con componentes de función) siempre que sea posible para evitar volver a representar componentes innecesarios cuando sus propiedades de entrada no cambian.
• 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 enlace de funciones dentro de la función render. Estas prácticas crean un nuevo cierre para la devolución de llamada con cada renderizado y hacen que el componente secundario vuelva a renderizarse siempre que se renderiza el componente primario. 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 de código sean accesibles para que los usuarios de solo teclado y lector de pantalla puedan usarlos:

• Proporcionar alternativas de navegación mediante teclado a eventos táctiles y del mouse. Por ejemplo, si el componente proporciona una lista desplegable, asegúrese de que un usuario puede usar Tab para establecer el foco y, a continuación, navegar por las opciones mediante las teclas de dirección.
• Asegúrese de que alt y los atributos de ARIA (Aplicaciones de Internet enriquecidas accesibles) estén establecidos para que los lectores de pantalla anuncien una representación precisa de la interfaz del componente de 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.

Para obtener más información, consulte Creación de 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ónica, ya que esta solicitud hace que la aplicación deje de responder y produzca un rendimiento lento. Para obtener más información, consulte Interacción con recursos HTTP y HTTPS de 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.

• Límites y configuraciones
• Exploradores web admitidos
• Navegadores utilizados por la oficina

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 de conjunto de datos se pueden colocar en cuadrículas de formularios principales, cuadrículas de registros relacionados, subcuadrículas o paneles. Cuando se utilizan en aplicaciones de lienzo, los componentes de código se pueden colocar dentro de contenedores adaptables que se redimensionan dinámicamente mediante la configuración proporcionada por el creador de la aplicación.

• Al usar trackContainerResize, los componentes de código pueden responder a cambios en el ancho y la altura disponibles. En algunos casos, establecer esta propiedad representa una interfaz de usuario diferente que se ajusta al espacio disponible. Puede combinar allocatedHeight y allocatedWidth con getFormFactor para determinar si el componente de código se ejecuta en un cliente móvil, tableta o web. Para obtener más información, consulte este tutorial del selector de opciones.
• Al implementar setFullScreen, los usuarios pueden expandirse para usar toda la pantalla disponible en la que el espacio está limitado. Para obtener más información, consulte componente de cuadrícula de la aplicación de 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 de CSS con ámbito limitado

Al implementar estilos para los componentes de código mediante CSS, asegúrese de limitar el ámbito de CSS al componente. Use las clases CSS generadas automáticamente aplicadas al elemento contenedor DIV del componente. Si limita el ámbito de CSS globalmente, es posible que interrumpa el estilo existente del formulario o la pantalla donde se representa el componente de código. Si usa un marco CSS de terceros, use una versión con espacio de nombres de ese marco o encapsula el marco en un espacio de nombres manualmente o mediante un preprocesador CSS.

Por ejemplo, si el espacio de nombres es SampleNamespace y el nombre del componente de código es LinearInputComponent, agregue una regla CSS personalizada mediante:

.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 explorador del usuario o en el cliente móvil no son seguros y no se garantiza que estén disponibles de forma confiable.

ALM, Azure DevOps y GitHub

Para conocer los procedimientos recomendados sobre los componentes de código con ALM, Azure DevOps y GitHub, consulte el artículo sobre administración del ciclo de vida de las aplicaciones de componentes de código (ALM).

Artículos relacionados

• Qué son los componentes de código
• Componentes de código para aplicaciones de lienzo
• Crear y generar un componente de código
• Más información sobre Power Apps component framework
• Usar componentes de código en Power Pages