Benutzerdefinierter HTML-Code

Das benutzerdefinierte HTML-Steuerelement richtet sich an fortgeschrittene Benutzer und bietet die Flexibilität von HTML-, CSS- und JavaScript-Programmiersprachen, um benutzerdefinierte, interaktive Steuerelemente zu erstellen, die ihren geschäftlichen Anforderungen entsprechen. Das Steuerelement enthält dedizierte Editoren für HTML-, CSS- und JavaScript-Code, mit dem zusätzlichen Vorteil, dass extern gehostete CSS- und JavaScript-Dateien über URLs integriert werden können.

Allgemein

• Code-Editor öffnen – Öffnet einen Editor mit drei Bereichen zum Hinzufügen des HTML-, CSS- und JavaScript-Codes.

• Zugängliche Beschriftung – Die Beschreibung des Steuerelements. Diese Eigenschaft wird von Bildschirmleseprogrammen für eine verbesserte Zugänglichkeit verwendet.

• Ausgeblendet – Bei „true“ wird das Steuerelement während der Runtime ausgeblendet.

• Deaktiviert – Bei „true“ wird das Steuerelement zur Laufzeit inaktiv. Der HTML-, CSS- und JavaScript-Inhalt wird geladen, reagiert jedoch nicht auf Benutzeraktionen wie Klicken.

Events

Keine Ereignisse.

Stil

• Ausrichtung von Steuerelementen – Erbt standardmäßig die übergeordnete Ausrichtung. Eine andere Ausrichtung als die übergeordnete kann festgelegt werden. Um die Standardausrichtung wiederherzustellen, heben Sie die Markierung der überschriebenen Optionen auf.

  Hinweis: Die Ausrichtung hängt vom Layout ab, das für das übergeordnete Element ausgewählt wurde (vertikal vs. horizontal).
• Rahmen – Der Rahmen für das Steuerelement. Rahmenstärke und Radius können konfiguriert werden.

• Seitenrand – Der Seitenrand des Steuerelements. Standardmäßig ist ein Seitenrand von 4px festgelegt. Die Randeigenschaften Oben/Unten und Links/Rechts werden kombiniert. Diese Eigenschaften können mit der Schaltfläche Link rechts neben dem Abschnitt Seitenrand getrennt werden.

• Größe – Die Breite und Höhe des Steuerelements. Standardmäßig ist die Größe auf auto festgelegt. Um Mindest- oder Höchstwerte festzulegen, klicken Sie auf das Drei-Punkte-Symbol (…).

Code-Editor für benutzerdefiniertes HTML

Der Code-Editor des benutzerdefinierten HTML-Steuerelements bietet drei Bereiche zur Eingabe von Code in den Programmiersprachen HTML, CSS und JavaScript. Jeder Editor unterstützt IntelliSense oder die automatische Codevervollständigung und Syntaxhervorhebung.

Der Code aus den Panels wird zu einem Projekt kompiliert und in Apps Studio zur Vorschau gerendert. Um die Funktionalität des Steuerelements zu beobachten, zeigen Sie eine Vorschau der App an.

Wichtig:

• Jeder Editor hat eine maximale Inhaltsgröße von 5 MB. Wenn der Inhalt diese Größe überschreitet, können Sie Ihre Änderungen nicht mehr speichern.

• IntelliSense funktioniert nicht für CSS- und JavaScript-Codes, die im HTML-Editor geschrieben wurden.

Hinzufügen externer Ressourcen

Wenn Sie bereits Stile oder Skripte definiert haben, können Sie im Steuerelement auf sie verweisen, ohne den Code in die entsprechenden CSS- oder JavaScript-Bereiche schreiben zu müssen.

So verweisen Sie auf vorhandene .css- oder .js -Dateien:

1. Wechseln Sie im Code-Editor des benutzerdefinierten HTML-Steuerelements zur Registerkarte Externe Ressourcen .

2. Fügen Sie im Abschnitt CSS eine externe CSS-Datei hinzu. Die Datei muss unter einer für das Netzwerk zugänglichen URL gehostet werden, um die Kompatibilität und Verfügbarkeit an dem Ort sicherzustellen, an dem die App ausgeführt wird.

3. Fügen Sie im Abschnitt JavaScript eine externe Skriptdatei hinzu. Die Datei muss unter einer für das Netzwerk zugänglichen URL gehostet werden, um die Kompatibilität und Verfügbarkeit an dem Ort sicherzustellen, an dem die App ausgeführt wird.

4. Wenn Sie alle externen Ressourcen hinzugefügt haben, klicken Sie auf Speichern.

Tastenkombinationen für die Tabulatortaste

Standardmäßig fügt die Tabulatortaste einen Tabulatorbereich innerhalb des aktuellen Editors hinzu. Um das Verhalten der Tabulatortaste anzupassen, verwenden Sie die folgenden Tastenkombinationen:

OS	Verknüpfung	Verhalten
Windows	STRG+M	Weist die Tabulatortaste an, zwischen den Bereichen zu navigieren und den Fokus auf die sichtbaren Schaltflächen des Editors zu ändern. Drücken Sie STRG+M erneut, um das Standardverhalten der Registerkarte wiederherzustellen.
MacOS	STRG+Umschalt+M	Weist die Tabulatortaste an, zwischen den Bereichen zu navigieren und den Fokus auf die sichtbaren Schaltflächen des Editors zu ändern. Drücken Sie erneut STRG+Umschalt+M, um zum Standard-Registerkartenverhalten zurückzukehren.

Der HTML-Editor

In diesem Panel können Sie die Struktur Ihres Steuerelements eingeben, die normalerweise in den <body></body> -Tags eines Codeblocks enthalten ist.

Um beispielsweise das Containerelement für ein interaktives Kreisdiagramm in Ihrer App hinzuzufügen, würden Sie das folgende HTML-Snippet verwenden:

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

Wo:

• id="myChart" verweist auf das JavaScript-Element „myChart“, das das interaktive Kreisdiagramm innerhalb des HTML-Elements generiert. Weitere Informationen finden Sie unter Der JavaScript-Editor.
• class="chart-container" verweist auf die CSS-Klasse „chart-container“, die den Stil für das Kreisdiagramm innerhalb des HTML-Elements hinzufügt. Weitere Informationen finden Sie unter Der CSS-Editor.

Der CSS-Editor

In diesem Bereich können Sie den Stil Ihres Steuerelements und der darin enthaltenen Elemente eingeben.

Um dem Kreisdiagramm beispielsweise Farben und einen Rahmen hinzuzufügen, würden Sie das folgende CSS-Snippet verwenden:

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

Der JavaScript-Editor

In diesem Panel können Sie den interaktiven Teil Ihres Steuerelements erstellen, z. B. aktuelle Inhaltsaktualisierungen, Karten oder animierte 2D-/3D-Diagramme.

Um beispielsweise ein Kreisdiagramm für den weltweiten Vertrieb von Apple-Produkten zu erstellen und es so zu gestalten, dass Werte für das ausgewählte Segment angezeigt werden, gehen Sie wie folgt vor:

1. Fügen Sie die folgende externe JavaScript-Ressource hinzu:

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

2. Verwenden Sie den folgenden JavaScript-Snippet:

   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',
         },
       },
     },
   });

Verwenden von Variablen in benutzerdefiniertem HTML-Code

Um die Kommunikation zwischen dem benutzerdefinierten HTML-Steuerelement und anderen Steuerelementen oder Integrationen herzustellen, empfehlen wir die Verwendung der integrierten Funktionen setVariable(), getVariable() und onVariableChange() .

getVariable()

Verwenden Sie diese Funktion im JavaScript-Editor, um den Wert einer vorhandenen Variablen abzurufen.

Um beispielsweise den Wert einer Variablen an internalValue zu übergeben, würden Sie das folgende JavaScript-Snippet verwenden:

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

Hinweis:

• Die FunktiongetVariable() ist asynchron, deshalb müssen Sie await verwenden.
• Wenn Sie getVariable() innerhalb einer Funktion aufrufen, machen Sie diese Funktion zu async. Im angegebenen Beispiel haben wir die Funktion init() erstellt und sofort aufgerufen.
• Wenn Sie getVariable() auf hoher Ebene aufrufen, bebetten Sie es in eine async -Funktion.

Um Fehler wie ungültige Variablennamen zu behandeln, verwenden Sie die Anweisung Try-Catch. Zum Beispiel:

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

setVariable()

Verwenden Sie diese Funktion im JavaScript-Editor, um einen Wert für eine vorhandene Variable festzulegen. Das erste Argument ist der Variablenname und das zweite Argument ist der Wert, den Sie festlegen möchten.

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

Hinweis:

Um auf den Abschluss des festgelegten Vorgangs zu warten, bevor anderer Code ausgeführt wird, verwenden await.

Um Fehler wie ungültige Variablennamen oder Typfehler zwischen der Variablen und dem festgelegten Wert zu behandeln, verwenden Sie die Anweisung Try-Catch. Zum Beispiel:

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

onVariableChange()

Verwenden Sie diese Funktion im JavaScript-Editor, um Änderungen eines vorhandenen Variablenwerts abzuhören und auf den neuesten Variablenwert zuzugreifen.

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

Im folgenden Beispiel weisen wir die von onVariableChange() zurückgegebene Funktion der Variablen deregister zu. Wenn Sie dann die Überwachung von Variablenänderungen beenden möchten, können Sie die Funktion deregister() aufrufen:

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();

Hinweis:

• Der Listener wird gestartet, nachdem das benutzerdefinierte HTML-Steuerelement vollständig gerendert wurde. Wenn sich ein Variablenwert ändert, bevor das benutzerdefinierte HTML-Steuerelement initialisiert wird, wird der aktualisierte Wert nicht erfasst.

  Um den neuesten Variablenwert abzurufen, rufen Sie getVariable() auf, bevor Sie onVariableChange() aufrufen.

• Das HTML-Steuerelement und die darin enthaltenen Funktionen werden initialisiert, nachdem das Steuerelement zur Laufzeit angezeigt wurde.

Variablentypen

App-Variablentyp	Beispielantwort von Variablenfunktionen
Text (String)	"Hello world"
UInt64 (Int)	100
Decimal number	50.25
True/False (Boolean)	True
DateOnly	2024-01-02 (Format: JJJJ-MM-TT)
DateTimeOffset	2024-01-06T09:54:41.9170000Z (Äquivalentes JS-Format: ISO-String des Datumsobjekts)
AppsFile – Wert eines Dateiauswahlsteuerelements	JS-Dateiobjekt
AppsFile – Wert, der aus der URL erstellt wurde Zum Beispiel: new AppsFile("https://image.jpg")	Dateiobjekt: {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',...},...]

Best Practices für benutzerdefiniertes HTML

• Nehmen Sie aufgrund des clientseitigen Zugriffs keine vertraulichen Daten in das benutzerdefinierte HTML-Steuerelement auf.

• Verwenden Sie die Tags <html> und <head> nicht im HTML-Editor, da der Code automatisch innerhalb der <body> -Tags angehängt wird.

• Fügen Sie CDN-URLs externer Ressourcen wie Bootstrap, jQuery oder anderer JavaScript SDKs auf der Registerkarte Externe Ressourcen hinzu.

• Wenn Sie die Überwachung der Variablenänderung beenden möchten, verwenden Sie die Funktion deregister() .

• Vermeiden Sie große Datenschleifen, um eine Verlangsamung der Anwendung zu verhindern und die Reaktion des Steuerelements aufrechtzuerhalten.

• Minimieren Sie die Verwendung von DOM-Elementen so weit wie möglich: Erstellen Sie DOM-Elemente nur bei Bedarf und entfernen Sie sie, wenn sie veraltet sind.

• Verwenden Sie für große Datasets unendliches oder virtuelles Scrollen anstelle von Standard-Scroll.

• Erstellen und pflegen Sie einen bereinigten, optimierten und Redundanz-freien Code.

Funktionseinschränkungen

• Um das Steuerelement mit Apps zu verbinden, müssen Sie die Variablenfunktionen verwenden: getVariable(), setVariable(), onVariableChange().

• Die Abmessungen des HTML-Steuerelements werden nicht dynamisch angepasst, um Pop-ups oder Dropdown-Menüs anzuzeigen. Sie müssen die Größe des HTML-Steuerelements manuell festlegen, damit es in diese Menüs passt.

• Sie können während der Entwurfszeit nicht mit dem HTML-Steuerelement interagieren.

• Die Funktionen setVariable(), getVariable() und onVariableChange() werden nur zur Laufzeit ausgeführt.

• Änderungen an Variablennamen oder Variablenlöschungen werden nicht automatisch in den Code-Editoren widergespiegelt. Sie müssen den Code manuell mit den aktuellen Variablen aktualisieren.

• Übertragungen von Bilddaten vom HTML-Steuerelement in einen Speicher-Bucket oder an eine Entität, die eine Daten-URL verwendet, dürfen die Dateigröße von 1 MB nicht überschreiten. Dateien, die diese Größe überschreiten, können Leistungsprobleme verursachen.

• Das Steuerelement kann nur über die Verwendung von Variablen mit anderen UiPath^® -Komponenten kommunizieren, z. B. Prozesse, Warteschlangen oder Speicher-Buckets.

• Vorverarbeiteter CSS-Code, der LESS oder SCSS verwendet, ist mit dem HTML-Steuerelement nicht kompatibel.

• Die folgenden APIs schlagen bei der Verwendung aufgrund von Sicherheitsbedenken im Hintergrund fehl:

  • Herunterladen mit dem Attribut download .
  • Öffnen von Modalitäten mit Window.alert(), Window.confirm(), Window.print(), Window.prompt().

  • Sperren von Zeiger und Ausrichtung.

  • Navigieren im Browserkontext auf oberster Ebene.

  • Öffnen des Vollbildmodus mit requestFullscreen().
  • Bildschirmaufnahme mit MediaDevices.getDisplayMedia().
  • Zugriff auf die Kamera oder das Mikrofon mit MediaDevices.getUserMedia().

  • Anfordern von Zahlungen.

  • Zugriff auf den Speicherort mit navigator.geolocation().
  • Freigeben von Daten mit navigator.share().

Debuggen des Codes eines benutzerdefinierten HTML-Steuerelements

Hinzufügen und Filtern von Konsolenprotokollen eines benutzerdefinierten HTML-Steuerelements

1. Fügen Sie im JavaScript-Editor einen console.log() hinzu.
2. Öffnen Sie die Browserkonsole, indem Sie F12 drücken und dann die Registerkarte Konsole auswählen.
3. Aktivieren Sie in den Konsoleneinstellungen das Kontrollkästchen Nur ausgewählter Kontext .
4. Wählen Sie in der Dropdownliste JavaScript-Kontext oben auf der Konsolenseite die Option html-control-base.html für das gewünschte HTML-Steuerelement aus.

Die Protokolle aus dem ausgewählten Steuerelement werden in der Konsole angezeigt.

Weitere Informationen finden Sie im Video:

Haltepunkte hinzufügen

1. Fügen Sie im JavaScript-Editor einen console.log() hinzu.
2. Öffnen Sie die Browserkonsole, indem Sie F12 drücken und dann die Registerkarte Konsole auswählen.
3. Klicken Sie auf der rechten Seite des Protokolls auf die VM-Meldung.

Der Debugger wird geöffnet. Wählen Sie Ihren Haltepunkt aus, indem Sie auf die gewünschte Zeilennummer klicken.

Weitere Informationen finden Sie im Video:

VB-Eigenschaften

VB-Eigenschaft	Datentyp	Beschreibung
AccessibleLabel	String	Die Beschreibung des Steuerelements, die von Barrierefreiheitstechnologien wie Bildschirmleseprogrammen verwendet wird.
Hidden	Boolescher	Bestimmt die Sichtbarkeit des benutzerdefinierten HTML -Steuerelements. Bei „true“ wird das Steuerelement zur Runtime ausgeblendet.
Disabled	Boolescher	Bestimmt, ob das benutzerdefinierte HTML -Steuerelement deaktiviert ist. Bei „true“ wird die Interaktion mit dem Steuerelement zur Runtime deaktiviert. HTML-, CSS- und JavaScript-Inhalte werden geladen, reagieren jedoch nicht auf Benutzeraktionen.