Benutzerdefinierte JavaScript-Komponenten erstellen

Universal ist erweiterbar und Sie können benutzerdefinierte JavaScript-Komponenten und Frameworks erstellen. Dieses Dokument behandelt, wie Sie benutzerdefinierte Komponenten erstellen, die sich in die Universal App-Plattform integrieren.

Dies ist ein fortgeschrittenes Thema und nicht erforderlich, wenn Sie einfach nur Universal Apps verwenden möchten.

Ein vollständiges funktionierendes Beispiel finden Sie im Projekt ud-mermaid auf GitHub. Dies ist eine produktionsreife benutzerdefinierte Komponente, die die Mermaid-Diagrammbibliothek in PowerShell Universal integriert.

Überblick

Das Erstellen einer benutzerdefinierten React-Komponente für PowerShell Universal umfasst mehrere zentrale Bestandteile:

1. Projektstruktur: Ein Node.js-Projekt mit Webpack zum Bündeln von React-Komponenten
2. React-Komponente (JSX): Die React-Komponente, die Ihre Benutzeroberfläche rendert
3. PowerShell-Modul (PSM1): PowerShell-Funktionen, die Komponentendefinitionen erstellen
4. Modulmanifest (PSD1): Standardmäßige PowerShell-Modulmetadaten
5. Build-Prozess: Webpack-Konfiguration zum Bündeln von JavaScript-Assets
6. Komponentenregistrierung: Registrierung Ihrer Komponente bei Universal Dashboard

Funktionsweise

Die Integration zwischen PowerShell und React funktioniert wie folgt:

1. PowerShell-Seite: Ihre PowerShell-Funktion gibt eine Hashtabelle mit Komponenteneigenschaften zurück
2. Asset-Registrierung: Das gebündelte JavaScript wird beim AssetService von PowerShell Universal registriert
3. Komponententyp: Die Eigenschaft type verknüpft die PowerShell-Hashtabelle mit der React-Komponente
4. Übergabe von Props: Eigenschaften der Hashtabelle werden automatisch zu React-Props
5. Rendering: Universal Dashboard lädt das JavaScript-Bundle und rendert die React-Komponente

PowerShell Function → Hashtable → Asset Service → React Component → DOM

Das Beispiel ud-mermaid

In diesem Leitfaden verweisen wir durchgehend auf das Projekt ud-mermaid als praxisnahes Beispiel. Diese Komponente umschließt die Diagrammbibliothek Mermaid.js zur Verwendung in PowerShell Universal und demonstriert:

• Integration einer JavaScript-Bibliothek von Drittanbietern
• Verwendung von React-Hooks (useEffect, useRef)
• Übergabe von Konfigurationsobjekten
• Professionelle Projektstruktur
• Build-Automatisierung

Schritt für Schritt

Der folgende Abschnitt führt Sie Schritt für Schritt durch die verschiedenen Aspekte der Erstellung einer Universal App-Komponente.

1. Abhängigkeiten installieren

Sie müssen die folgenden Abhängigkeiten installieren, bevor Sie Ihre Komponente erstellen.

• NodeJS – Erforderlich für npm und die Ausführung von Build-Tools

2. Ein neues Projekt erstellen

Erstellen Sie ein neues Verzeichnis für Ihr Komponentenprojekt:

New-Item -Path .\MyComponent -ItemType Directory
Set-Location .\MyComponent

Initialisieren Sie ein neues npm-Projekt:

npm init -y

Dadurch wird eine grundlegende Projektstruktur erstellt, einschließlich:

• package.json – Node.js-Abhängigkeiten und Build-Skripte

3. JavaScript-Abhängigkeiten installieren

Installieren Sie die erforderlichen Build-Tools und React-Abhängigkeiten:

npm install --save-dev @babel/core @babel/preset-env @babel/preset-react babel-loader webpack webpack-cli css-loader style-loader @babel/plugin-proposal-class-properties @babel/plugin-syntax-dynamic-import --legacy-peer-deps

Installieren Sie das Universal Dashboard-Paket:

npm install universal-dashboard --legacy-peer-deps

Das Projekt ud-mermaid enthält zum Beispiel das Paket mermaid als zusätzliche Abhängigkeit:

"dependencies": {
    "mermaid": "^9.4.3",
    "universal-dashboard": "^1.0.1"
}

Installieren Sie alle weiteren Bibliotheken, die Ihre Komponente benötigt:

npm install mermaid --legacy-peer-deps

4. Projektstruktur erstellen

Erstellen Sie die erforderlichen Verzeichnisse für Ihre Komponente:

New-Item -Path .\Components -ItemType Directory

5. Ihre React-Komponente erstellen

Erstellen Sie eine React-Komponente im Verzeichnis Components/. Ihre Komponente sollte:

1. Aus universal-dashboard importieren
2. Das withComponentFeatures-HOC (Higher-Order Component) verwenden
3. Props akzeptieren, die den Parametern Ihrer PowerShell-Funktion entsprechen

Beispiel aus ud-mermaid (Components/mermaid.jsx):

import React, { useEffect, useRef } from 'react';
import { withComponentFeatures } from 'universal-dashboard';
import mermaid from 'mermaid';

const UDMermaid = (props) => {
  const mermaidRef = useRef(null);
  const { id, diagram, config } = props;

  useEffect(() => {
    mermaid.initialize(config || {});
    
    if (mermaidRef.current) {
      mermaidRef.current.removeAttribute('data-processed');
      mermaid.contentLoaded();
    }
  }, [diagram, config]);

  return (
    <div className="mermaid" id={id} ref={mermaidRef}>
      {diagram}
    </div>
  );
};

export default withComponentFeatures(UDMermaid);

6. Ihre Komponente registrieren

Erstellen Sie eine index.js-Datei im Verzeichnis Components/, die Ihre Komponente bei Universal Dashboard registriert:

import UDMermaid from './mermaid';
UniversalDashboard.register("ud-mermaid", UDMermaid);

Die Zeichenfolge, die Sie an register() übergeben, wird zur Eigenschaft type, die Sie in Ihrer PowerShell-Funktion verwenden.

7. PowerShell-Funktionen erstellen

Nun müssen Sie den Code des PowerShell-Moduls schreiben. Sie müssen die PSM1-Datei aktualisieren, um Assets zu laden und Funktionen zu definieren, die Komponentendefinitionen erstellen.

Die PSM1-Datei sollte:

1. Die gebündelte JavaScript-Datei beim AssetService registrieren
2. Funktionen definieren, die Hashtabellen mit Komponenteneigenschaften zurückgeben

Beispiel aus ud-mermaid (UniversalDashboard.Mermaid.psm1):

# Register JavaScript assets with PowerShell Universal
Get-ChildItem "$PSScriptRoot\*.js" | ForEach-Object {
    $Item = [UniversalDashboard.Services.AssetService]::Instance.RegisterAsset($_.FullName)
    if ($_.Name.StartsWith("index.") -and $_.Name.EndsWith(".bundle.js")) {
        $AssetId = $Item
    }
}

function New-UDMermaid {
    param(
        [Parameter()]
        [string]$Id = (New-Guid).ToString(),
        [Parameter(Mandatory)]
        [string]$Diagram,
        [Parameter()]
        [hashtable]$Config
    )

    @{
        assetId = $AssetId 
        isPlugin = $true 
        type = "ud-mermaid"  # This matches the name used in UniversalDashboard.register()
        id = $Id
        diagram = $Diagram
        config = $Config
    }
}

Wichtige Eigenschaften der Hashtabelle:

• assetId – Die von RegisterAsset zurückgegebene ID
• isPlugin – Für benutzerdefinierte Komponenten immer auf $true gesetzt
• type – Muss mit dem Namen übereinstimmen, den Sie in UniversalDashboard.register() verwendet haben
• id – Ein eindeutiger Bezeichner für die Komponenteninstanz
• Weitere Eigenschaften werden als Props an Ihre React-Komponente übergeben

8. Webpack konfigurieren

Ihre webpack.config.js sollte Ihre Komponenten bündeln und die Abhängigkeiten React und Universal Dashboard als externals auslagern. Hier ist die wesentliche Konfiguration aus ud-mermaid:

module.exports = (env) => {
  return {
    entry: {
      'index': __dirname + '/components/index.js'
    },
    output: {
      path: BUILD_DIR,
      filename: '[name].[hash].bundle.js',
      library: 'udcomponent',
      libraryTarget: 'var'
    },
    module: {
      rules: [
        { test: /\.(js|jsx)$/, exclude: [/public/], loader: 'babel-loader' },
        { test: /\.css$/, loader: "style-loader!css-loader" }
      ]
    },
    externals: {
      'react': 'react',
      'react-dom': 'reactdom',
      UniversalDashboard: 'UniversalDashboard'
    },
    resolve: {
      extensions: ['.js', '.jsx']
    }
  };
}

Wichtige externals:

• react und react-dom – Werden von PowerShell Universal bereitgestellt
• UniversalDashboard – Das globale Universal Dashboard-Objekt

8.1. Babel konfigurieren

Erstellen Sie eine .babelrc-Datei, um JSX und die Transformation von modernem JavaScript zu konfigurieren:

{
  "presets": [
    ["@babel/preset-env", {
      "targets": {
        "browsers": [">0.5%", "not dead"]
      }
    }],
    "@babel/preset-react"
  ],
  "plugins": [
    "@babel/plugin-proposal-class-properties",
    "@babel/plugin-syntax-dynamic-import",
    "@babel/plugin-proposal-optional-chaining",
    "@babel/plugin-proposal-nullish-coalescing-operator"
  ]
}

Diese Konfiguration:

• Wandelt JSX in JavaScript um
• Transpiliert modernes JavaScript für die Browserkompatibilität
• Aktiviert nützliche Sprachfunktionen von JavaScript

9. Modulmanifest erstellen

Erstellen Sie ein standardmäßiges PowerShell-Modulmanifest (.psd1) mit den Metadaten Ihrer Komponente:

@{
    RootModule = 'UniversalDashboard.Mermaid.psm1'
    ModuleVersion = '1.0.0'
    Author = 'Your Name'
    Description = 'Custom component description'
    FunctionsToExport = @('New-UDMermaid')
}

10. Das Projekt erstellen

Sie können nun Ihr Projekt erstellen. Es wird ein Modul ausgegeben, das Sie in PowerShell Universal laden können.

Fügen Sie zunächst Build-Skripte zu Ihrer package.json hinzu:

"scripts": {
    "build": "webpack -p --env production",
    "dev": "webpack-dev-server --config webpack.config.js -p --env development"
}

Führen Sie dann den Build aus:

npm run build

Optional: Erstellen Sie ein Build-Skript (wie component.build.ps1 von ud-mermaid):

# component.build.ps1
$OutputPath = "$PSScriptRoot\output"

Remove-Item -Path $OutputPath -Force -ErrorAction SilentlyContinue -Recurse
Remove-Item -Path "$PSScriptRoot\public" -Force -ErrorAction SilentlyContinue -Recurse

npm install --legacy-peer-deps
npm run build

New-Item -Path $OutputPath -ItemType Directory

Copy-Item $PSScriptRoot\public\*.* $OutputPath
Copy-Item $PSScriptRoot\UniversalDashboard.MyComponent.psd1 $OutputPath
Copy-Item $PSScriptRoot\UniversalDashboard.MyComponent.psm1 $OutputPath

Führen Sie es dann aus:

.\component.build.ps1

Der Build-Prozess:

1. Bündelt den gesamten JavaScript-/React-Code mit Webpack
2. Gibt gebündelte Dateien mit Hash-Namen aus (z. B. index.78a6d857.bundle.js)
3. Kopiert die Moduldateien (.psm1, .psd1) in das Ausgabeverzeichnis

11. Verwendung in PowerShell Universal

Laden Sie in Ihrer App Ihr Modul und führen Sie die Funktion aus.

Import-Module .\output\UniversalDashboard.Mermaid.psd1

New-UDApp -Content {
   New-UDMermaid -Diagram @"
graph TD
    A[Start] --> B[Process]
    B --> C[End]
"@
}

Beispiel einer Projektstruktur

Hier ist die typische Struktur eines benutzerdefinierten Komponentenprojekts (aus ud-mermaid):

project/
├── Components/
│   ├── index.js              # Component registration
│   └── mermaid.jsx           # React component
├── output/                   # Build output (git ignored)
│   ├── index.[hash].bundle.js
│   ├── UniversalDashboard.Mermaid.psm1
│   └── UniversalDashboard.Mermaid.psd1
├── package.json              # Node.js dependencies
├── webpack.config.js         # Webpack configuration
├── component.build.ps1       # Optional build script
├── UniversalDashboard.Mermaid.psm1   # PowerShell module
└── UniversalDashboard.Mermaid.psd1   # Module manifest

Props

Props sind Werte, die entweder aus der vom Benutzer bereitgestellten PowerShell-Hashtabelle oder von der Universal App-High-Order-Funktion withComponentsFeature übergeben werden.

Standard

Die Eigenschaften, die Sie in Ihrer Hashtabelle in PowerShell festlegen, werden automatisch als Props an die React-Komponente übergeben.

Wenn Sie beispielsweise die Eigenschaften diagram und config in der Hashtabelle festlegen:

function New-UDMermaid {
    param(
        [Parameter()]
        [string]$Id = (New-Guid).ToString(),
        [Parameter(Mandatory)]
        [string]$Diagram,
        [Parameter()]
        [hashtable]$Config
    )

    @{
        type = "ud-mermaid"
        isPlugin = $true
        assetId = $AssetId 
        id = $Id
        diagram = $Diagram
        config = $Config
    }
}

Dann haben Sie in React Zugriff auf diese Props:

import React, { useEffect, useRef } from 'react';
import { withComponentFeatures } from 'universal-dashboard';
import mermaid from 'mermaid';

const UDMermaid = (props) => {
  const { id, diagram, config } = props;

  useEffect(() => {
    mermaid.initialize(config || {});
  }, [diagram, config]);

  return <div className="mermaid" id={id}>{diagram}</div>;
};

export default withComponentFeatures(UDMermaid);

Best Practices für Props:

• Verwenden Sie aussagekräftige Prop-Namen, die den PowerShell-Parameternamen entsprechen
• Behandeln Sie optionale Props mit Standardwerten oder bedingter Logik
• Hashtabellen in PowerShell werden automatisch zu JavaScript-Objekten

React-Hooks und Komponentenlebenszyklus

Beim Erstellen benutzerdefinierter Komponenten können Sie alle standardmäßigen React-Hooks verwenden. Die ud-mermaid-Komponente demonstriert die Verwendung von useEffect und useRef zur Verwaltung des Komponentenlebenszyklus und von DOM-Referenzen:

import React, { useEffect, useRef } from 'react';

const UDMermaid = (props) => {
  const mermaidRef = useRef(null);
  const { diagram, config } = props;

  // Run when diagram or config changes
  useEffect(() => {
    mermaid.initialize(config || {});
    
    if (mermaidRef.current) {
      mermaidRef.current.removeAttribute('data-processed');
      mermaid.contentLoaded();
    }
  }, [diagram, config]); // Dependency array

  return <div ref={mermaidRef}>{diagram}</div>;
};

Häufige Muster:

• useEffect – Für Initialisierung, Aufräumarbeiten und die Reaktion auf Prop-Änderungen
• useRef – Für den direkten Zugriff auf DOM-Elemente
• useState – Für die Verwaltung des internen Komponentenzustands
• useMemo / useCallback – Für die Leistungsoptimierung

Endpunkte

Endpunkte sind besonders in der Art, wie sie registriert werden und wie sie als Props an Ihre Komponente übergeben werden. Sie müssen Register für den Endpunkt in PowerShell aufrufen und die Variablen Id und PSCmdlet übergeben.

function New-UD95Button {
    param(
        [Parameter()]
        [string]$Id = [Guid]::NewGuid(),
        [Parameter()]
        [string]$Text,
        [Parameter()]
        [Endpoint]$OnClick
    )

    if ($OnClick)
    {
        $OnClick.Register($Id, $PSCmdlet)
    }

    @{
        type = "ud95-button"
        isPlugin = $true 
        assetId = $AssetId

        id = $Id 
        text = $Text 
        onClick = $OnClick
    }
}

Endpunkte werden aus ScriptBlocks erstellt und ausgeführt, wenn das entsprechende Ereignis eintritt.

New-UD95Button -Text 'Hello' -OnClick {
    Show-UDToast -Message 'Test' 
}

Universal verknüpft den Endpunkt automatisch mit einer Funktion innerhalb von JavaScript. Das bedeutet, dass Sie die Props verwenden können, um diesen Endpunkt aufzurufen.

Beachten Sie den Funktionsaufruf props.onClick. Dieser ruft automatisch den PowerShell-Skriptblock auf dem Server auf.

import React from 'react';
import { withComponentFeatures } from 'universal-dashboard';
import { Button } from 'react95';

const UD95Button = props => {

    const p = {
        onClick: () => props.onClick()
    }

    return <Button {...p}>{props.text}</Button>
}

export default withComponentFeatures(UD95Button);

setState

Die Prop setState wird verwendet, um den Zustand der Komponente festzulegen. Dadurch wird sichergestellt, dass der Zustand verfolgt wird und Ihre Komponente mit Get-UDElement funktioniert.

Bei einem Textfeld sollten Sie beispielsweise props.setState aufrufen und den neuen Textwert für den Zustand übergeben.

const UDTextField = (props) => {
    const onChange = (e) => {
        props.setState({value: e.target.value})
    }

    return <TextField  {...props} onChange={onChange} />
}

export default withComponentFeatures(UDTextField);

children

Die Prop children ist eine standardmäßige React-Prop. Wenn Ihre Komponente untergeordnete Elemente unterstützt, etwa eine Liste oder ein Auswahlfeld, sollten Sie die standardmäßige Prop props.children verwenden, um sicherzustellen, dass die Cmdlets Add-UDElement, Remove-UDElement und Clear-UDElement korrekt funktionieren.

Fehlerbehebung und Debugging

Häufige Probleme

Komponente wird nicht gerendert:

1. Überprüfen Sie, ob der type in Ihrer PowerShell-Funktion mit dem UniversalDashboard.register()-Namen übereinstimmt
2. Prüfen Sie, ob das Asset korrekt beim AssetService registriert ist
3. Stellen Sie sicher, dass isPlugin auf $true gesetzt ist
4. Bestätigen Sie, dass die gebündelte JavaScript-Datei im Modulverzeichnis vorhanden ist

Props werden nicht korrekt übergeben:

1. Überprüfen Sie, ob die Eigenschaftsnamen zwischen der PowerShell-Hashtable und der React-Komponente übereinstimmen
2. Prüfen Sie die Browser-Konsole auf JavaScript-Fehler
3. Verwenden Sie React DevTools, um die Props der Komponente zu untersuchen

Build-Fehler:

1. Führen Sie npm install --legacy-peer-deps aus, um sicherzustellen, dass die Abhängigkeiten installiert sind
2. Prüfen Sie die JSX-Dateien auf Syntaxfehler
3. Überprüfen Sie, ob die externals in webpack.config.js korrekt konfiguriert sind
4. Stellen Sie sicher, dass babel für die JSX-Transformation korrekt konfiguriert ist

Debugging-Tipps

Browser-Konsole: Öffnen Sie die Entwicklertools des Browsers (F12), um JavaScript-Fehler und -Warnungen zu sehen.

React DevTools: Installieren Sie die React DevTools-Browsererweiterung, um die Komponentenhierarchie und Props zu untersuchen.

PowerShell-Debugging: Verwenden Sie Write-Host oder Write-Debug in Ihren PowerShell-Funktionen, um die Ausführung nachzuvollziehen.

Webpack Dev Server: Verwenden Sie während der Entwicklung webpack-dev-server für Hot Reloading:

npm run dev

Konfigurieren Sie dann PowerShell Universal so, dass es von der Dev-Server-URL lädt.

Beispiel: Vollständiger Komponenten-Workflow

Hier ist ein vollständiges Beispiel basierend auf dem Projekt ud-mermaid:

1. React-Komponente erstellen (Components/mermaid.jsx):

import React, { useEffect, useRef } from 'react';
import { withComponentFeatures } from 'universal-dashboard';
import mermaid from 'mermaid';

const UDMermaid = (props) => {
  const mermaidRef = useRef(null);
  const { id, diagram, config } = props;

  useEffect(() => {
    mermaid.initialize(config || {});
    if (mermaidRef.current) {
      mermaidRef.current.removeAttribute('data-processed');
      mermaid.contentLoaded();
    }
  }, [diagram, config]);

  return <div className="mermaid" id={id} ref={mermaidRef}>{diagram}</div>;
};

export default withComponentFeatures(UDMermaid);

2. Komponente registrieren (Components/index.js):

import UDMermaid from './mermaid';
UniversalDashboard.register("ud-mermaid", UDMermaid);

3. PowerShell-Funktion erstellen (UniversalDashboard.Mermaid.psm1):

Get-ChildItem "$PSScriptRoot\*.js" | ForEach-Object {
    $Item = [UniversalDashboard.Services.AssetService]::Instance.RegisterAsset($_.FullName)
    if ($_.Name.StartsWith("index.") -and $_.Name.EndsWith(".bundle.js")) {
        $AssetId = $Item
    }
}

function New-UDMermaid {
    param(
        [Parameter()]
        [string]$Id = (New-Guid).ToString(),
        [Parameter(Mandatory)]
        [string]$Diagram,
        [Parameter()]
        [hashtable]$Config
    )

    @{
        assetId = $AssetId 
        isPlugin = $true 
        type = "ud-mermaid"
        id = $Id
        diagram = $Diagram
        config = $Config
    }
}

4. Erstellen und testen:

# Build
npm run build

# Test in PowerShell Universal
Import-Module .\output\UniversalDashboard.Mermaid.psd1

New-UDApp -Content {
    New-UDMermaid -Diagram @"
graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[Car]
"@
}

Zusätzliche Ressourcen

• ud-mermaid GitHub-Repository: https://github.com/ironmansoftware/ud-mermaid - Vollständiges funktionierendes Beispiel
• React-Dokumentation: https://react.dev
• Webpack-Dokumentation: https://webpack.js.org