Benutzerdefiniertes Widget

Client-Steuerelemente und OMI-Apps werden nur auf dem Desktop unterstützt und funktionieren nicht im Web Client. Benutzerdefinierte Widgets sind eine plattformübergreifende Lösung, mit der Sie Elemente einmal entwickeln und in allen InTouch- und OMI-Projekten in Web- und Desktop-Umgebungen verwenden können.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Folgendes installiert ist:

• Node.js (24.15.0 oder höher) und npm (11.12.1 oder höher): Erforderlich, um Abhängigkeiten zu installieren und das Widget-Paket zu erstellen. Laden Sie sie von nodejs.org herunter.

• Texteditor: Wird zum Bearbeiten von Widget-Dateien verwendet. Visual Studio Code wird empfohlen.

In diesem Abschnitt wird erläutert, wie Sie ein benutzerdefiniertes Widget in InTouch- und OMI-Projekten erstellen und verwenden. Führen Sie die folgenden Schritte aus:

• Schritt 1: Erstellen und Ändern eines benutzerdefinierten Widgets

• Schritt 2: Aktualisieren der Projektdateien

• Schritt 3: Definieren von Widget-Eigenschaften und -Methoden in der .wjson-Datei

• Schritt 4: Erstellen des Widget-Pakets

• Schritt 5: Importieren und Verwenden des Widgets

Schritt 1: Erstellen und Ändern eines benutzerdefinierten Widgets

Ein Beispiel-Widget für den Einstieg ist unter C:\ProgramData\AVEVA\Widgets\SampleWidget verfügbar.

Der Ordner Vorlagen enthält die Basisdateien, die zum Erstellen neuer Widgets verwendet werden. Ändern Sie diese Vorlagendateien nicht während der regulären Widget-Entwicklung.

1. Öffnen Sie das Terminal im WidgetCreator-Verzeichnis: C:\ProgramData\AVEVA\Widgets\WidgetCreator.

2. Führen Sie den folgenden Befehl aus, um ein neues Widget zu erstellen:

   npm run create-widget MyWidgetName. Dabei ist MyWidgetName der Name des neuen Widgets.

3. Navigieren Sie zum neu erstellten Widget-Ordner: cd MyWidgetName.

4. Öffnen Sie den neuen Widgetordner in Visual Studio Code, um Änderungen vorzunehmen.

Schritt 2: Aktualisieren der Projektdateien

Sie können die folgenden Projektdateien anpassen, um Ihr Widget zu erstellen:

• index.html: Verwenden Sie diese Option, um die HTML-Struktur nach Bedarf zu modifizieren. Diese obligatorische Datei ist der Haupteinstiegspunkt und wird zuerst geladen, wenn das Widget geöffnet wird. Benennen Sie diese Datei nicht um.

• src/*.css: Verwenden Sie diese Option, um die visuellen Stile anzupassen.

• src/*.js: Verwenden Sie diese Option, um die Widget-Logik zu implementieren.

  Hinweis: Die standardmäßigen CSS- und JavaScript-Dateinamen sind nach dem Beispiel-Widget benannt. Sie können diese Dateien bei Bedarf umbenennen.

Schritt 3: Definieren von Widget-Eigenschaften und -Methoden in der .wjson-Datei

Die .wjson-Datei fungiert als Vertrag zwischen dem Widget und den InTouch- sowie OMI-Projekten. Sie definiert die Eigenschaften, die von Ihrem Widget für die Plattform verfügbar gemacht werden.

Grundlegendes zur .wjson-Struktur

Die .wjson-Datei enthält die folgenden Schlüsselfelder:

• version: Gibt die Version des Widgets an.

• width and height: Definiert die Standardgröße des Widgets, wenn es zum ersten Mal hinzugefügt wird.

• events: Derzeit nicht implementiert, aber für zukünftige Versionen geplant.

• properties: Definiert die Widget-Eigenschaften, die der Plattform zur Verfügung gestellt werden. Jede Eigenschaft muss fortlaufend nummeriert werden, beginnend mit „0“, „1“, „2“ usw.

  Hinweis: Diese Felder sind Pflichtfelder und dürfen nicht entfernt werden, da sie für die ordnungsgemäße Funktion des Widgets erforderlich sind.

Konfigurierbare Eigenschaftsfelder

Sie können die folgenden Felder für jede Widget-Eigenschaft konfigurieren:

• Name: Gibt den Namen der Widget-Eigenschaft an, die in InTouch und OMI angezeigt wird. Der Name darf maximal 32 Zeichen lang sein.

• Type: Definiert den .NET-Datentyp der Eigenschaft. Zu den unterstützten Eigenschaftstypen gehören Boolean, Double, Elapsed Time, Float, Integer, String, Time und History Summary.

• Value: Legt den Standardwert fest, der der Widget-Eigenschaft zugewiesen wird.

• Desc: Enthält eine Beschreibung der Widget-Eigenschaft. Dieses Feld unterstützt mehrere Sprachen, um die Lokalisierung und Benutzerfreundlichkeit zu verbessern.

Das folgende Beispiel zeigt zwei Eigenschaften. Um eine neue Eigenschaft hinzuzufügen, kopieren Sie den vollständigen JSON-Eintrag und aktualisieren Sie die Sequenznummer zusammen mit den Feldern für Name, Typ und anderen relevanten Feldern.

{

"version": 0,

"width": 500,

"height": 500,

"events": {},

"properties": {

"0": {

"name": "Counter",

"type": "integer",

"value": 0,

"desc": {

"1033": "Counter value",

"1036": "Valeur du compteur",

"1031": "Zählerwert",

"1041": "カウンター値",

"2052": "计数器值"

}

},

"1": {

"name": "Label",

"type": "string",

"value": "Count:",

"desc": {

"1033": "Display label",

"1036": "Étiquette d'affichage",

"1031": "Anzeigebeschriftung",

"1041": "表示ラベル",

"2052": "显示标签"

}

}

}

}

Verwenden von Widget-Eigenschaften in JavaScript

Sobald Sie Ihre Eigenschaften in der .wjson-Datei definiert haben, können Sie mit cwidget in JavaScript darauf zugreifen.

Auf Eigenschaftsänderungen achten

Um Änderungen an einer Widget-Eigenschaft zu erkennen, verwenden Sie das folgende Muster (ersetzen Sie „Counter“ durch Ihren tatsächlichen Eigenschaftsnamen):

cwidget.on('Counter', callbackFn);

callbackFn: Eine Funktion, die immer dann ausgeführt wird, wenn sich der Eigenschaftswert ändert. Sie kann verwendet werden, um die Benutzeroberfläche zu aktualisieren oder eine zusätzliche Logik auszulösen.

Beispiel aus dem Beispiel-Widget:

Wenn sich in SampleWidget.js die Eigenschaft „Counter“ ändert, wird die Funktion _onCounterCshanged() ausgelöst, um die Anzeige zu aktualisieren:

cwidget.on('Counter', _onCounterChanged);

function _onCounterChanged() {

document.getElementById('counter').innerText = cwidget.Counter;

}

Festlegen von Eigenschaftswerten

Um einer Widget-Eigenschaft einen neuen Wert zuzuweisen, verwenden Sie die folgende Syntax:

cwidget.Counter = nextValue;

nextValue: Speichert den Wert, der der Eigenschaft zugewiesen werden soll. Er sollte dem Datentyp der Eigenschaft entsprechen (z. B. eine Zahl für eine Integer-Eigenschaft oder eine Zeichenfolge für eine Zeichenfolgeneigenschaft).

Beispiel aus dem Beispiel-Widget:

In SampleWidget.js wird mit der Schaltfläche zum Inkrementieren die Eigenschaft „Counter“ aktualisiert. Dadurch wird automatisch der Rückruf ausgelöst und alle gebundenen Steuerelemente aktualisiert:

function _increment() {

const current = Number.parseInt(cwidget.Counter, 10) || 0;

cwidget.Counter = current + 1;

}

Aufrufbare Methoden in JavaScript binden (optional)

Damit InTouch- und OMI-Projekte Methoden in Ihrem Widget aufrufen können, können Sie die Methoden der Widget-Klasse verfügbar machen, indem Sie sie an Funktionen im Fensterobjekt binden.

Im Folgenden finden Sie ein Beispiel (ersetzen Sie SampleWidget, Decrement, _decrement und Counter durch Ihre eigenen Klassen- und Methodennamen):

class SampleWidget {

constructor() {

window.Decrement = this._decrement.bind(this);

}

_decrement(args) {

var number = JSON.parse(args[0]);

const current = Number.parseInt(cwidget.Counter, 10) || 0;

const delta = Number.parseInt(number, 10) || 0;

cwidget.Counter = current - delta;

_onCounterChanged();

}

}

Dadurch entsteht eine aufrufbare Funktion mit dem Namen „Decrement“, die nach dem Import des Widgets in Industriegrafik-Aktionsskripten verwendet werden kann.

Schritt 4: Erstellen des Widget-Pakets 

Führen Sie nach Abschluss der Entwicklung die Schritte zum Erstellen des Widgets und zum Generieren des bereitstellbaren Pakets aus:

5. Öffnen Sie ein Terminal im Widget-Ordner (C:\ProgramData\AVEVA\Widgets\WidgetCreator\MyWidgetName).

6. Führen Sie den Build-Befehl npm run build aus.

   Dadurch wird ein .cwp-Paket im dist-Ordner generiert.

Schritt 5: Importieren und Verwenden des Widgets

Sobald Ihr Widget erstellt ist, können Sie es importieren und in Ihrem Projekt verwenden. Führen Sie die Schritte aus, um das Widget in das InTouch-Projekt zu importieren und seine Eigenschaften zu binden:

Importieren und Einbetten des Widgets für InTouch WindowViewer

7. Öffnen Sie Ihr Projekt in WindowMaker.

8. Gehen Sie zu Datei > Import > Visualisierung > HTML5-Widget.

   

9. Wählen Sie die in Schritt 4 erzeugte .cwp-Datei aus.

10. Öffnen Sie den Grafikeditor und betten Sie das Widget über Industriegrafiken > Widgets ein.

Importieren und Einbetten des Widgets für die System Platform-IDE

11. Öffnen Sie Ihre Galaxy.

12. Wechseln Sie zur Registerkarte Home und wählen Sie Importieren.

    

13. Wählen Sie Web-Widgets aus.

14. Wählen Sie die in Schritt 4 erzeugte .cwp-Datei aus.

    Nach dem Import erscheint Ihr Widget im Grafikeditor-Objektsatz, wo Sie es per Drag & Drop auf Ihre Grafik ziehen können.

Benutzerdefinierte Eigenschaften binden

Die Bindung von Widget-Eigenschaften an benutzerdefinierte Eigenschaften ermöglicht eine bidirektionale Synchronisierung zwischen Ihrem Widget und anderen Steuerelementen in Ihrem Projekt.

Einrichten der Bindung

15. Erstellen Sie eine benutzerdefinierte Eigenschaft in Ihrem Projekt. In diesem Beispiel verwenden wir cp_value.

    

16. Binden Sie die Widget-Eigenschaft an die benutzerdefinierte Eigenschaft. Verknüpfen Sie im Widget-Eigenschaften-Raster die Eigenschaft Counter-Widget mit cp_value.

Zwei-Wege-Bindung

Sobald die Bindung eingerichtet ist, ändert sich der Fluss automatisch in beide Richtungen:

• Vom Widget zum Projekt: Wenn das Widget seine Eigenschaft aktualisiert (z. B. cwidget.Counter = newValue), wird die benutzerdefinierte Eigenschaft „cp_value“ aktualisiert und alle angebundenen Steuerelemente (z. B. Textfelder) spiegeln den neuen Wert wider.

• Vom Projekt zum Widget: Wenn Sie einen Wert in das Textfeld eingeben, ändert sich „cp_value“. Diese Änderung löst die mit cwidget.on() registrierte Callback-Funktion aus, sodass das Widget reagieren kann und die Benutzeroberfläche synchronisiert bleibt.

Aufrufen von Widget-Methoden aus Skripten

Wenn Sie aufrufbare Methoden in Ihrem Widget definiert haben (siehe „Schritt 3: Aufrufbare Methoden in JavaScript binden“), können Sie eine Widget-Methode aus dem Grafikskript-Editor aufrufen.

Erstellen Sie in diesem Beispiel eine Schaltfläche mit einer Aktionsskript-Animation, sodass beim Klicken die Decrement-Methode ausgelöst wird, die zuvor in JavaScript gebunden war.

dim args [1] as object;

args[1]=5;

SampleWidget1.ExecuteFunctionAsync("Decrement",args);

Gehen Sie beispielsweise wie folgt vor, um die Decrement-Funktion aufzurufen:

Dieses Skript ruft die Decrement-Methode in Ihrer Widget-Instanz auf und übergibt den Wert 5. Wenn die Schaltfläche angeklickt wird, verringert sich der Zähler des Widgets um 5.

wobei:

• SampleWidget1 ist der Name der Widget-Instanz auf der Grafik.

• ExecuteFunctionAsync ist die Methode, die verwendet wird, um Widget-Funktionen asynchron aufzurufen.

• Decrement ist der Methodenname, der dem JavaScript-Bindungsfenster zugeordnet ist. Decrement this._decrement.bind (this).

• „args“ ist ein Objektarray, das die an die Widget-Methode übergebenen Argumente speichert. Der Array-Index sollte bei [1] (nicht bei [0]) beginnen.

Ersetzen Sie SampleWidget1 durch Ihren tatsächlichen Widget-Namen und passen Sie den Methodennamen und die Argumente nach Bedarf an.

Ihr benutzerdefiniertes Widget ist jetzt vollständig integriert und einsatzbereit.