HTML Personalizado

Crie controles de aplicativos personalizados e interativos no Studio Web usando HTML, CSS e JavaScript com editores de código dedicados para cada idioma.

O Controle de HTML personalizado é direcionado a usuários avançados e oferece a flexibilidade das linguagens de programação HTML, CSS e JavaScript para criar controles interativos personalizados conforme exigido pelas suas necessidades de negócios. O controle inclui editores dedicados para códigos HTML, CSS e JavaScript, com a vantagem adicional de incorporar arquivos CSS e JavaScript hospedados externamente por meio de URLs.

Geral

• Abrir editor de código - Abre um editor de três painéis para adicionar o código HTML, CSS e JavaScript.
• Rótulo acessível — a descrição do controle. Essa propriedade é usada por leitores de tela para acessibilidade aprimorada.
• Oculto— se verdadeiro, oculta o controle no tempo de execução.
• Desabilitado — se verdadeiro, torna o controle inativo no tempo de execução. O conteúdo HTML, CSS e JavaScript é carregado, mas não responde a ações do usuário, como clicar.

Events

Não há eventos.

Estilo

• Alinhamento de controle — Por padrão, herda o alinhamento parent. É possível definir outro alinhamento que não o pai. Para voltar ao alinhamento padrão pai, desmarque as opções substituídas.
  Observação:

  O alinhamento depende do layout selecionado para o pai (Vertical vs Horizontal).

• Borda — define a borda do controle. A espessura e o raio da borda podem ser configurados.
• Margem — a margem do controle. Por padrão, uma margem de 4px é definida. As propriedades Top/Bottom e Left/Right são combinadas. Essas propriedades podem ser desanexadas usando o botão Link no lado direito da seção Margem .
• Size - The width and height of the control. By default, the size is set to auto. To set minimum or maximum values, select the three dot icon (...).

Editor de código para HTML personalizado

O editor de código do controle HTML personalizado fornece três painéis para entrada de código nas linguagens de programação HTML, CSS e JavaScript. Cada editor é compatível com o IntelliSense, ou a conclusão automática de código e destaque de sintaxe.

O código dos painéis é compilado em um projeto e renderizado no Apps Studio para visualização. Para observar a funcionalidade do controle, visualize o aplicativo.

Importante:

• Cada editor tem um tamanho máximo de conteúdo de 5 MB. Quando o conteúdo exceder esse tamanho, você não poderá mais salvar suas alterações.
• O IntelliSense não funciona para códigos CSS e JavaScript escritos dentro do editor de HTML.

Adição de recursos externos

Se você já tiver definidos estilos ou scripts, poderá referenciá-los no controle, sem escrever o código nos painéis CSS ou JavaScript correspondentes.

Para fazer referência a arquivos .cssou .js existentes:

1. No editor de código do controle HTML personalizado, mude para a guia Recursos externos .
2. Na seção CSS, adicione um arquivo CSS externo. O arquivo deve ser hospedado em uma URL acessível pela rede para garantir a compatibilidade e a disponibilidade no local em que o aplicativo estiver em execução.
3. Na seção JavaScript, adicione um arquivo de script externo. O arquivo deve ser hospedado em uma URL acessível pela rede para garantir a compatibilidade e a disponibilidade no local em que o aplicativo estiver em execução.
4. When you finished adding all the external resources, select Save.

Atalhos de acessibilidade para a tecla Tab

Por padrão, a tecla Tab adiciona um espaço de tabulação dentro do editor atual. Para personalizar o comportamento da tecla Tab, use os seguintes atalhos:

SO	Atalho	Comportamento
Windows	CTRL+M	Instrui a tecla Tab a navegar entre os painéis e a alterar o foco nos botões visíveis do editor. Pressione CTRL+M novamente para retornar ao comportamento padrão da Guia.
MacOS	CTRL+Shift+M	Instrui a tecla Tab a navegar entre os painéis e a alterar o foco nos botões visíveis do editor. Pressione CTRL+Shift+M novamente para retornar ao comportamento padrão da Guia.

O editor de HTML

Neste painel, você pode inserir a estrutura do seu controle, que geralmente está contida dentro das tags <body></body> de um bloco de código HTML.

Por exemplo, para adicionar o elemento contêiner para um gráfico de pizza interativo em seu aplicativo, você usaria o seguinte fragmento de HTML:

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

Onde:

• id="myChart" refere-se ao elemento JavaScript "myChart" que gera o gráfico de pizza interativo dentro do elemento HTML. Para obter detalhes, consulte O editor de JavaScript.
• class="chart-container" se refere à classe CSS "chart-container", que adiciona o estilo do gráfico de pizza dentro do elemento HTML. Para detalhes, consulte O editor CSS.

O editor CSS

Neste painel, você pode inserir o estilo do seu controle e os elementos dentro dele.

Por exemplo, para adicionar cores e uma borda ao gráfico de pizza, você usaria o seguinte fragmento CSS:

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

O editor de JavaScript

Neste painel, você pode criar a parte interativa do seu controle, como atualizações oportunas de conteúdo, mapas ou gráficos animados 2D/3D.

Por exemplo, para criar um gráfico de pizza para as vendas de produtos da Apple em todo o mundo e projetá-lo para exibir valores para a fatia selecionada, você terá:

1. Adicione o seguinte recurso JavaScript externo:

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

2. Use o seguinte fragmento 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',
         },
       },
     },
   });
   

Usando variáveis em HTML personalizado

Para estabelecer a comunicação entre o controle HTML personalizado e outros controles ou integrações, recomendamos o uso das funções integradas setVariable(), getVariable() e onVariableChange() .

getVariable()

No editor de JavaScript, use essa função para obter o valor de uma variável existente.

Por exemplo, para passar o valor de uma variável para um internalValue, você usaria o seguinte fragmento de JavaScript:

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

Observação:

• A funçãogetVariable() é assíncrona, o que requer que você use await.
• Se você chamar getVariable() dentro de uma função, faça essa função async. No exemplo fornecido, criamos a função init() e a invocamos imediatamente.
• Se você chamar getVariable() em um nível superior, incorpore-o dentro de uma função async .

Para lidar com erros, como nomes de variáveis inválidos, use a instrução try-catch. Por exemplo:

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

setVariable()

No editor de JavaScript, use essa função para definir um valor para uma variável existente. O primeiro argumento é o nome da variável, e o segundo argumento é o valor que você deseja definir.

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

Observação:

Para aguardar a conclusão da operação de definição antes de executar outro código, use await.

Para lidar com erros, como nomes de variáveis inválidos ou incompatibilidade de tipo entre a variável e o valor definido, use a instrução try-catch. Por exemplo:

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

onVariableChange()

No editor de JavaScript, use essa função para ouvir as alterações de um valor de variável existente e acessar o valor da variável mais recente.

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

No exemplo a seguir, atribuímos a função retornada pelo onVariableChange() à variável deregister . Então, se você quiser parar de ouvir mudanças de variáveis, você pode invocar a função 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();

Observação:

• O ouvinte é iniciado depois que o controle HTML personalizado é renderizado completamente. Se o valor de uma variável for alterado antes do controle HTML personalizado ser inicializado, o valor atualizado não será capturado. Para obter o valor da variável mais recente, chame getVariable() antes de chamar onVariableChange().
• O controle HTML e as funções dentro dele são inicializados após o controle ser exibido no tempo de execução.

Tipos de variáveis

Tipo de variável do aplicativo	Exemplo de resposta de funções de variável
Text (String)	"Hello world"
UInt64 (Int)	100
Decimal number	50.25
True/False (Boolean)	True
DateOnly	2024-01-02 (Formato: AAAA-MM-DD)
DateTimeOffset	2024-01-06T09:54:41.9170000Z (Formato JS equivalente: string ISO do objeto de data)
AppsFile — valor de um controle de seletor de arquivos	Objeto do arquivo JS
ArquivoDoApps - valor criado a partir do URL Por exemplo: new AppsFile("https://image.jpg")	Objeto do arquivo: {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',...},...]

Práticas recomendadas para HTML personalizado

• Não inclua dados confidenciais no controle HTML personalizado, devido ao seu acesso do lado do cliente.
• Não utilize as tags <html> e <head> dentro do editor de HTML, pois o código é acrescentado automaticamente dentro das tags <body> .
• Adicione URLs de CDN de recursos externos, como Inicialização, jQuery ou outros SDKs de JavaScript na guia Recursos externos .
• Se você quiser parar de ouvir a mudança da variável, use a função deregister() .
• Evite loops de dados grandes para evitar a lentidão do aplicativo e para manter o controle responsivo.
• Minimize o uso de elementos DOM tanto quanto possível: crie elementos DOM apenas quando necessário e remova-os quando se tornarem obsoletos.
• Use a rolagem infinita ou virtual para grandes conjuntos de dados em vez da rolagem padrão.
• Criar e manter um código limpo, otimizado e sem redundância.

Limitações funcionais

• Para conectar o controle ao Apps, você deve usar as funções de variáveis: getVariable(), setVariable(), onVariableChange().
• As dimensões do controle HTML não se ajustam dinamicamente para exibir pop-ups ou menus suspensos. É preciso definir manualmente o tamanho do controle HTML para que se ajuste a esses menus.
• Não é possível interagir com o controle de HTML durante o tempo de design.
• As funções setVariable(), getVariable() e onVariableChange() operam apenas no runtime.
• As alterações ou exclusões de variáveis não refletem automaticamente nos editores de código. Você precisa atualizar manualmente o código com as variáveis atuais.
• As transferências de dados de imagem do controle HTML para um bucket de armazenamento ou para uma entidade usando um URL de dados não devem exceder 1 MB de tamanho de arquivo. Arquivos que excedem esse tamanho podem causar problemas de desempenho.
• O controle pode se comunicar com outros componentes da UiPath, como Processos, Filas ou Buckets de Armazenamento, apenas por meio do uso de variáveis.
• O código CSS pré-processado, usando LESS ou SCSS, é incompatível com o controle HTML.
• As seguintes APIs falham de forma silenciosa quando usadas, devido a preocupações de segurança:
  • Baixando usando o atributo download .
  • Abertura de Modais usando Window.alert(), Window.confirm(), Window.print(), Window.prompt().
  • Bloqueio de ponteiro e orientação.
  • Navegação no contexto do navegador de nível superior.
  • Entrada da tela cheia usando requestFullscreen().
  • Captura de tela usando MediaDevices.getDisplayMedia().
  • Acessando a câmera ou o microfone usando MediaDevices.getUserMedia().
  • Solicitando pagamentos.
  • Acessando o local usando navigator.geolocation().
  • Compartilhamento de dados usando navigator.share().

Depurando o código de um controle HTML personalizado

Adição e filtragem de logs do console de um controle HTML personalizado

1. Adicione um console.log() no editor de JavaScript.
2. Abra o console do navegador pressionando F12 e, em seguida, selecione a guia Console .
3. Nas configurações do console, marque a caixa Apenas contexto selecionado .
4. No menu suspenso do contexto do JavaScript na parte superior da página do console, selecione a opção html-control-base.html para o controle HTML desejado.

Os logs do controle selecionado são exibidos no console.

Assista o vídeo para obter mais detalhes:

Adição de pontos de interrupção

1. Adicione um console.log() no editor de JavaScript.
2. Abra o console do navegador pressionando F12 e, em seguida, selecione a guia Console .
3. At the right-hand side of the log, select the VM message.

The debugger opens. Select your breakpoint by selecting the desired line number.

Assista o vídeo para obter mais detalhes:

Propriedades VB

Propriedade do VB	Tipo de dados	Description
AccessibleLabel	String	A descrição do controle, usado por tecnologias de acessibilidade, como os leitores de tela.
Hidden	Booleano	Determina a visibilidade do controle HTML personalizado . Se verdadeiro, oculta o controle no tempo de execução.
Disabled	Booleano	Determina se o controle HTML personalizado está desabilitado. Se verdadeiro, desabilita a interação com o controle no tempo de execução. O conteúdo HTML, CSS e JavaScript é carregado, mas não responde às ações do usuário.