HTML personalizado

El control HTML personalizado está dirigido a usuarios avanzados y ofrece la flexibilidad de los lenguajes de programación HTML, CSS y JavaScript para crear controles personalizados e interactivos según lo requieran sus necesidades empresariales. El control incluye editores dedicados para código HTML, CSS y JavaScript, con la ventaja añadida de incorporar archivos CSS y JavaScript alojados externamente a través de URL.

General

• Abrir editor de código : abre un editor de tres paneles para añadir el código HTML, CSS y JavaScript.

• Etiqueta accesible : la descripción del control. Los lectores de pantalla utilizan esta propiedad para mejorar la accesibilidad.

• Oculto: si es verdadero, oculta el control en tiempo de ejecución.

• Deshabilitado : si es verdadero, hace que el control esté inactivo en tiempo de ejecución. El contenido HTML, CSS y JavaScript se carga, pero no responde a las acciones del usuario, como hacer clic.

Events

No hay eventos.

Estilo

• Alineación de control: por defecto, hereda la alineación principal. Se puede establecer una alineación diferente a la principal. Para volver a la alineación principal, anula la selección de las opciones anuladas.

  Nota: la alineación depende del diseño seleccionado para el elemento principal (Vertical vs Horizontal).
• Borde : el borde del control. Se puede configurar el grosor del borde y el radio .

• Margen: el margen del control. De forma predeterminada, se establece un margen de 4px. Se combinan las propiedades de los márgenes superiores/inferiores e izquierdos/derechos. Estas propiedades se pueden separar utilizando el botón Enlace situado a la derecha de la sección Margen.

• Tamaño: el ancho y la altura del control. El tamaño está establecido como auto de forma predeterminada. Para establecer valores mínimos o máximos, haz clic en el icono de tres puntos (...).

Editor de código para HTML personalizado

El editor de código del control HTML personalizado proporciona tres paneles para introducir código en los lenguajes de programación HTML, CSS y JavaScript. Cada editor es compatible con IntelliSense, o la finalización automática de código, y el resaltado de sintaxis.

El código de los paneles se compila en un proyecto y se renderiza en Apps Studio para su vista previa. Para observar la funcionalidad del control, previsualiza la aplicación.

Importante:

• Cada editor tiene un tamaño máximo de contenido de 5 MB. Cuando el contenido supera este tamaño, ya no se pueden guardar los cambios.

• IntelliSense no funciona para los códigos CSS y JavaScript escritos en el editor HTML.

Añadir recursos externos

Si ya tienes estilos o scripts definidos, puedes hacer referencia a ellos en el control, sin necesidad de escribir el código en los paneles CSS o JavaScript correspondientes.

Para hacer referencia a archivos .csso .js existentes:

1. En el Editor de código del control HTML personalizado, cambia a la pestaña Recursos externos .

2. En la sección CSS, añade un archivo CSS externo. El archivo debe estar alojado en una URL accesible por red para garantizar la compatibilidad y la disponibilidad donde se ejecuta la aplicación.

3. En la sección JavaScript, añade un archivo de script externo. El archivo debe estar alojado en una URL accesible por red para garantizar la compatibilidad y la disponibilidad donde se ejecuta la aplicación.

4. Cuando hayas terminado de añadir todos los recursos externos, haz clic en Guardar.

Atajos de accesibilidad para la tecla Tabulador

De forma predeterminada, la tecla Tab añade un espacio de tabulación dentro del editor actual. Para personalizar el comportamiento de la tecla Tab, utiliza los siguientes atajos:

SO	Atajo	Comportamiento
Ventanas	CTRL+M	Indica a la tecla Tabulador que navegue entre los paneles y cambie el enfoque en los botones visibles del editor. Presiona CTRL+M de nuevo para volver al comportamiento predeterminado de la pestaña.
MacOS	CTRL+Mayús+M	Indica a la tecla Tabulador que navegue entre los paneles y cambie el enfoque en los botones visibles del editor. Presiona CTRL+Shift+M de nuevo para volver al comportamiento de pestaña predeterminado.

El editor HTML

En este panel puedes introducir la estructura de tu control, que suele estar contenida dentro de las etiquetas <body></body> de un bloque de código HTML.

Por ejemplo, para añadir el elemento contenedor para un gráfico circular interactivo en tu aplicación, utilizarías el siguiente fragmento de código HTML:

<canvas id="myChart" class="chart-container" style="width:100%;max-width:600px"></canvas>

Donde:

• id="myChart" hace referencia al elemento JavaScript "myChart" que genera el gráfico circular interactivo dentro del elemento HTML. Para obtener más información, consulta El editor de JavaScript.
• class="chart-container" se refiere a la clase CSS "chart-container" que añade el estilo para el gráfico circular dentro del elemento HTML. Para obtener más información, consulta El editor de CSS.

El editor de CSS

En este panel puedes introducir el estilo de tu control y los elementos que contiene.

Por ejemplo, para añadir colores y un borde al gráfico circular, utilizarías el siguiente fragmento de CSS:

.chart-container {
    background-color: #f3f7e9;
    border: 1px solid #cccccc;
}

El editor JavaScript

En este panel puedes crear la parte interactiva de tu control, como actualizaciones de contenido oportunas, mapas o gráficos animados en 2D/3D.

Por ejemplo, para crear un gráfico circular para las ventas de productos Apple en todo el mundo, y diseñarlo para que muestre los valores del sector seleccionado, harías lo siguiente:

1. Añade el siguiente recurso externo de JavaScript:

   https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.4/Chart.js

2. Utiliza el siguiente fragmento de JavaScript:

   const ctx = document.getElementById('myChart').getContext('2d');
   const myChart = new Chart(ctx, {
     type: 'pie',
     data: {
       labels: ['iPhone', 'iPad', 'MacBook', 'Apple Watch', 'AirPods'],
       datasets: [{
         label: 'Sales',
         data: [120000, 80000, 50000, 40000, 30000],
         backgroundColor: [
           '#5CB85C', // Green
           '#F0AD4E', // Orange
           '#D9534F', // Red
           '#5BC0DE', // Light blue
           '#999',    // Gray
         ],
         borderColor: '#fff',
         borderWidth: 2,
       }],
     },
     options: {
       plugins: {
         legend: {
           position: 'top',
         },
         title: {
           display: true,
           text: 'Apple Products Sales',
         },
       },
     },
   });

Uso de variables en HTML personalizado

Para establecer la comunicación entre el control HTML personalizado y otros controles o integraciones, recomendamos y utilizar las funciones integradas setVariable(), getVariable() y onVariableChange() .

getVariable()

En el editor de JavaScript, utiliza esta función para obtener el valor de una variable existente.

Por ejemplo, para pasar el valor de una variable a un internalValue, usarías el siguiente fragmento de JavaScript:

async function init() {
  let internalValue = await App.getVariable('<app_variable_name>');
}
init();

Nota:

• La funcióngetVariable() es asíncrona, lo que requiere que utilices await.
• Si llamas a getVariable() dentro de una función, haz que esa función sea async. En el ejemplo proporcionado, creamos la función init() y la invocamos inmediatamente.
• Si llamas a getVariable() en un nivel superior, insértalo dentro de una función async .

Para gestionar errores como nombres de variables no válidos, utiliza la instrucción try-catch. Por ejemplo:

async function init() {
  try {
    const value = await App.getVariable("test");
  } catch (e) {
    console.log("Error in evaluating app variable:", e);
  }
}
init();

setVariable()

En el editor de JavaScript, utiliza esta función para establecer un valor en una variable existente. El primer argumento es el nombre de la variable, y el segundo argumento es el valor que quieres establecer.

async function setValue() {
  await App.setVariable('<app_variable_name>', <app_variable_value>);
}
setValue();

Nota:

Para esperar a que se complete la operación de configuración antes de ejecutar otro código, utiliza await.

Para manejar errores como nombres de variables no válidos o falta de coincidencia de tipos entre la variable y el valor establecido, utiliza la declaración try-catch. Por ejemplo:

try {
  App.setVariable('<app_variable_name>', <app_variable_value>);
} catch (e) {
  console.log("Error in setting app variable:", e);
}

onVariableChange()

En el editor de JavaScript, utiliza esta función para escuchar los cambios de un valor de variable existente y acceder al último valor de variable.

App.onVariableChange('<app_variable_name>', value => {
  console.log("Latest value: ", value);
});

En el siguiente ejemplo, asignamos la función devuelta por onVariableChange() a la variable deregister . A continuación, si quieres dejar de escuchar los cambios de variables, puedes invocar la función deregister() :

const deregister = App.onVariableChange('<app_variable_name>', value => {
  console.log("Latest value: ", value);
});

// To stop listening for value changes, the deregister function can be invoked like below
deregister();

Nota:

• El listener se inicia después de que el control HTML personalizado se represente por completo. Si el valor de una variable cambia antes de que se inicialice el control HTML personalizado, el valor actualizado no se captura.

  Para obtener el último valor de la variable, llama a getVariable() antes de llamar a onVariableChange().

• El control HTML y las funciones que contiene se inicializan después de que el control se muestre en tiempo de ejecución.

Tipos de variables

Tipo de variable de aplicación	Ejemplo de respuesta de funciones variables
Text (String)	"Hello world"
UInt64 (Int)	100
Decimal number	50.25
True/False (Boolean)	Verdadero
DateOnly	2024-01-02 (Formato: AAAA-MM-DD)
DateTimeOffset	2024-01-06T09:54:41.9170000Z (Formato JS equivalente: cadena ISO de objeto de fecha)
AppsFile: valor de un control de selector de archivos	Objeto de archivo JS
AppsFile: valor creado a partir de la URL Por ejemplo: new AppsFile("https://image.jpg")	Objeto de archivo: {FileSize: 0, Name: "", URL: "https://image.jpg", __infoType: "$metadata"}
GUID	"5637F7DB-391D-4C8B-805D-0A918531CA3E"
List(Of string)	["Banana", "Kiwi", "Apple", "Lemon"]
ListSource(Of <Entity>)	{ data: [{Name: "John", Age: "28", ...},{Name: "Kane", Age: "48", ...}], totalRecords: 2 }
<Entity> (Single entity row)	{ Name: "John", Age: "28", ... }
ListSource(Of <Choiceset>)	{ data: [{DisplayName: "Male", Id: "00F3372D-3920-EC11-AE72-0003FFBA1E91", Name: "Male", ...}, {DisplayName: "Female", Id: "01F3372D-3920-EC11-AE72-0003FFBA1E91", Name: "Female", ...}], totalRecords: 2 }
Datatable	[{From: 'Ahmedabad', To: 'Azua', ...},{From: 'banglore', To: 'Dominican Republic',...},...]

Mejores prácticas para HTML personalizado

• No incluyas datos confidenciales en el control HTML personalizado debido a su acceso del lado del cliente.

• No utilices las etiquetas <html> y <head> dentro del editor HTML, ya que el código se añade automáticamente dentro de las etiquetas <body> .

• Añade las URL de CDN de recursos externos como Bootstrap, jQuery u otros SDK de JavaScript en la pestaña Recursos externos .

• Si quieres dejar de escuchar el cambio de variable, utiliza la función deregister() .

• Evita grandes bucles de datos para evitar ralentizar la aplicación y mantener el control receptivo.

• Minimiza el uso de elementos DOM tanto como sea posible: crea elementos DOM solo cuando sea necesario y elimínalos cuando se vuelvan obsoletos.

• Utiliza el desplazamiento infinito o virtual para grandes conjuntos de datos en lugar del desplazamiento estándar.

• Cree y mantenga un código limpio, optimizado y sin redundancia.

Limitaciones funcionales

• Para conectar el control a Apps, debes utilizar las funciones variables: getVariable(), setVariable(), onVariableChange().

• Las dimensiones del control HTML no se ajustan dinámicamente para mostrar ventanas emergentes o menús desplegables. Debes establecer manualmente el tamaño del control HTML para que se ajuste a estos menús.

• No se puede interactuar con el control HTML durante el tiempo de diseño.

• Las funciones setVariable(), getVariable() y onVariableChange() solo funcionan en tiempo de ejecución.

• Los cambios en los nombres de las variables o las eliminaciones de variables no se reflejan automáticamente en los editores de código. Debes actualizar manualmente el código con las variables actuales.

• Las transferencias de datos de imagen desde el control HTML a un depósito de almacenamiento, o a una entidad que utiliza una URL de datos, no deben superar 1 MB de tamaño de archivo. Los archivos que superan este tamaño pueden causar problemas de rendimiento.

• El control puede comunicarse con otros componentes de UiPath^® , como Procesos, Colas o Depósitos de almacenamiento, solo mediante el uso de variables.

• El código CSS preprocesado, que utiliza LESS o SCSS, es incompatible con el control HTML.

• Las siguientes API fallan silenciosamente cuando se utilizan, debido a problemas de seguridad:

  • Descargando utilizando el atributo download .
  • Abrir modales usando Window.alert(), Window.confirm(), Window.print(), Window.prompt().

  • Puntero y bloqueo de orientación.

  • Navegar por el contexto del navegador de nivel superior.

  • Entrar en pantalla completa usando requestFullscreen().
  • Captura de pantalla usando MediaDevices.getDisplayMedia().
  • Acceder a la cámara o al micrófono mediante MediaDevices.getUserMedia().

  • Solicitar pagos.

  • Acceder a la ubicación mediante navigator.geolocation().
  • Compartir datos mediante navigator.share().

Depurar el código de un control HTML personalizado

Añadir y filtrar registros de consola de un control HTML personalizado

1. Añade un console.log() en el editor de JavaScript.
2. Abre la consola del navegador pulsando F12 y, a continuación, selecciona la pestaña Consola .
3. En la configuración de la consola, marca la casilla Solo contexto seleccionado .
4. En el menú desplegable de contexto de JavaScript en la parte superior de la página de la consola, selecciona la opción html-control-base.html para el control HTML deseado.

Los registros del control seleccionado se muestran en la consola.

Consulta el vídeo para obtener más información:

Añadir puntos de interrupción

1. Añade un console.log() en el editor de JavaScript.
2. Abre la consola del navegador pulsando F12 y, a continuación, selecciona la pestaña Consola .
3. En la parte derecha del registro, haz clic en el mensaje de la VM.

Se abre el depurador. Selecciona tu punto de interrupción haciendo clic en el número de línea deseado.

Consulta el vídeo para obtener más información:

Propiedades VB

Propiedad VB	Tipo de datos	Descripción
AccessibleLabel	Cadena	La descripción del control, utilizada por las tecnologías de accesibilidad como los lectores de pantalla.
Hidden	Booleano	Determina la visibilidad del control HTML personalizado . Si es verdadero, oculta el control en tiempo de ejecución.
Disabled	Booleano	Determina si el control HTML personalizado está deshabilitado. Si es verdadero, deshabilita la interacción con el control en tiempo de ejecución. El contenido HTML, CSS y JavaScript se carga, pero no responde a las acciones del usuario.