Creazione di componenti JavaScript personalizzati

Universal è estensibile e permette di creare componenti e framework JavaScript personalizzati. Questo documento illustra come creare componenti personalizzati che si integrano con la piattaforma di app Universal.

Questo è un argomento avanzato e non è necessario se desidera semplicemente utilizzare le Universal Apps.

Per un esempio completo e funzionante, consulti il progetto ud-mermaid su GitHub. Si tratta di un componente personalizzato pronto per la produzione che integra la libreria di diagrammi Mermaid con PowerShell Universal.

Panoramica

La creazione di un componente React personalizzato per PowerShell Universal coinvolge diversi elementi chiave:

1. Struttura del progetto: un progetto Node.js con Webpack per il bundling dei componenti React
2. Componente React (JSX): il componente React che esegue il rendering della sua interfaccia utente
3. Modulo PowerShell (PSM1): funzioni PowerShell che creano le definizioni dei componenti
4. Manifesto del modulo (PSD1): metadati standard del modulo PowerShell
5. Processo di build: configurazione Webpack per il bundling degli asset JavaScript
6. Registrazione del componente: registrazione del componente con Universal Dashboard

Come funziona

L'integrazione tra PowerShell e React funziona in questo modo:

1. Lato PowerShell: la sua funzione PowerShell restituisce una hashtable con le proprietà del componente
2. Registrazione degli asset: il JavaScript in bundle viene registrato con l'AssetService di PowerShell Universal
3. Tipo di componente: la proprietà type collega la hashtable di PowerShell al componente React
4. Passaggio delle props: le proprietà della hashtable diventano automaticamente props di React
5. Rendering: Universal Dashboard carica il bundle JavaScript ed esegue il rendering del componente React

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

L'esempio ud-mermaid

In questa guida faremo riferimento al progetto ud-mermaid come esempio reale. Questo componente incapsula la libreria di diagrammi Mermaid.js per l'utilizzo in PowerShell Universal, dimostrando:

• Integrazione di librerie JavaScript di terze parti
• Utilizzo degli hook React (useEffect, useRef)
• Passaggio di oggetti di configurazione
• Struttura professionale del progetto
• Automazione della build

Passo dopo passo

La sezione seguente la guiderà passo dopo passo attraverso i diversi aspetti della creazione di un componente per Universal App.

1. Installazione delle dipendenze

Prima di creare il componente dovrà installare le seguenti dipendenze.

• NodeJS - Necessario per npm e per l'esecuzione degli strumenti di build

2. Creare un nuovo progetto

Crei una nuova directory per il progetto del componente:

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

Inizializzi un nuovo progetto npm:

npm init -y

Questo crea una struttura di progetto di base che include:

• package.json - Dipendenze Node.js e script di build

3. Installare le dipendenze JavaScript

Installi gli strumenti di build e le dipendenze React necessari:

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

Installi il pacchetto Universal Dashboard:

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

Ad esempio, il progetto ud-mermaid include il pacchetto mermaid come dipendenza aggiuntiva:

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

Installi eventuali librerie aggiuntive necessarie al suo componente:

npm install mermaid --legacy-peer-deps

4. Creare la struttura del progetto

Crei le directory necessarie per il suo componente:

New-Item -Path .\Components -ItemType Directory

5. Creare il componente React

Crei un componente React nella directory Components/. Il componente dovrebbe:

1. Importare da universal-dashboard
2. Utilizzare l'HOC withComponentFeatures (Higher-Order Component)
3. Accettare props che corrispondono ai parametri della sua funzione PowerShell

Esempio da 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. Registrare il componente

Crei un file index.js nella directory Components/ che registri il suo componente con Universal Dashboard:

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

La stringa che passa a register() diventa la proprietà type che utilizzerà nella sua funzione PowerShell.

7. Creare le funzioni PowerShell

Ora dovrà scrivere il codice del modulo PowerShell. Dovrà aggiornare il file PSM1 per caricare gli asset e definire le funzioni che creano le definizioni dei componenti.

Il file PSM1 dovrebbe:

1. Registrare il file JavaScript in bundle con l'AssetService
2. Definire funzioni che restituiscono hashtable con le proprietà del componente

Esempio da 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
    }
}

Proprietà chiave della hashtable:

• assetId - L'ID restituito da RegisterAsset
• isPlugin - Sempre impostato su $true per i componenti personalizzati
• type - Deve corrispondere al nome utilizzato in UniversalDashboard.register()
• id - Un identificatore univoco per l'istanza del componente
• Le proprietà aggiuntive vengono passate come props al suo componente React

8. Configurare Webpack

Il suo webpack.config.js dovrebbe eseguire il bundling dei componenti ed esternalizzare le dipendenze React e Universal Dashboard. Ecco la configurazione essenziale di 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']
    }
  };
}

Externals importanti:

• react e react-dom - Forniti da PowerShell Universal
• UniversalDashboard - L'oggetto globale Universal Dashboard

8.1. Configurare Babel

Crei un file .babelrc per configurare la trasformazione di JSX e del JavaScript moderno:

{
  "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"
  ]
}

Questa configurazione:

• Trasforma JSX in JavaScript
• Transpila il JavaScript moderno per la compatibilità con i browser
• Abilita utili funzionalità del linguaggio JavaScript

9. Creare il manifesto del modulo

Crei un manifesto standard del modulo PowerShell (.psd1) con i metadati del suo componente:

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

10. Compilare il progetto

Ora può compilare il progetto. Verrà generato un modulo che potrà caricare in PowerShell Universal.

Per prima cosa, aggiunga gli script di build al suo package.json:

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

Quindi esegua la build:

npm run build

Facoltativo: creare uno script di build (come il component.build.ps1 di 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

Poi lo esegua:

.\component.build.ps1

Il processo di build:

1. Esegue il bundling di tutto il codice JavaScript/React utilizzando Webpack
2. Genera file in bundle con nomi con hash (ad esempio, index.78a6d857.bundle.js)
3. Copia i file del modulo (.psm1, .psd1) nella directory di output

11. Utilizzo in PowerShell Universal

All'interno della sua app, carichi il modulo ed esegua la funzione.

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

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

Esempio di struttura del progetto

Ecco la struttura tipica di un progetto di componente personalizzato (da 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

Le props sono valori passati dalla hashtable PowerShell fornita dall'utente oppure dalla funzione high-order withComponentsFeature di Universal App.

Standard

Le proprietà impostate nella hashtable in PowerShell verranno inviate automaticamente come props al componente React.

Ad esempio, se imposta le proprietà diagram e config nella hashtable:

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
    }
}

Avrà quindi accesso a quelle props in React:

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 practice per le props:

• Utilizzi nomi di props descrittivi che corrispondano ai nomi dei parametri PowerShell
• Gestisca le props facoltative con valori predefiniti o logica condizionale
• Le hashtable in PowerShell diventano automaticamente oggetti JavaScript

Hook React e ciclo di vita dei componenti

Quando crea componenti personalizzati, può utilizzare tutti gli hook React standard. Il componente ud-mermaid dimostra l'utilizzo di useEffect e useRef per gestire il ciclo di vita del componente e i riferimenti al DOM:

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>;
};

Pattern comuni:

• useEffect - Per l'inizializzazione, la pulizia e la risposta alle modifiche delle props
• useRef - Per accedere direttamente agli elementi del DOM
• useState - Per gestire lo stato interno del componente
• useMemo / useCallback - Per l'ottimizzazione delle prestazioni

Endpoint

Gli endpoint sono speciali per il modo in cui vengono registrati e per il modo in cui vengono passati come props al suo componente. Dovrà chiamare Register sull'endpoint in PowerShell e passare le variabili Id e PSCmdlet.

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
    }
}

Gli endpoint vengono creati da ScriptBlock e vengono eseguiti al verificarsi dell'evento corrispondente.

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

Universal collegherà automaticamente l'endpoint a una funzione in JavaScript. Ciò significa che può utilizzare le props per chiamare quell'endpoint.

Noti la chiamata alla funzione props.onClick. Questa chiamerà automaticamente lo script block PowerShell sul server.

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

La prop setState viene utilizzata per impostare lo stato del componente. Ciò garantisce che lo stato venga monitorato e che il suo componente funzioni con Get-UDElement.

Ad esempio, con un campo di testo, dovrà chiamare props.setState e passare il nuovo valore di testo per lo stato.

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

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

export default withComponentFeatures(UDTextField);

children

La prop children è una prop React standard. Se il suo componente supporta elementi figlio, come un elenco o una casella di selezione, dovrebbe utilizzare la prop standard props.children per garantire il corretto funzionamento dei cmdlet Add-UDElement, Remove-UDElement e Clear-UDElement.

Risoluzione dei problemi e debug

Problemi comuni

Il componente non viene renderizzato:

1. Verifichi che il type nella sua funzione PowerShell corrisponda al nome di UniversalDashboard.register()
2. Controlli che l'asset sia registrato correttamente con AssetService
3. Si assicuri che isPlugin sia impostato su $true
4. Confermi che il file JavaScript in bundle esista nella directory del modulo

Le props non vengono passate correttamente:

1. Verifichi che i nomi delle proprietà corrispondano tra la hashtable PowerShell e il componente React
2. Controlli la console del browser per eventuali errori JavaScript
3. Usi React DevTools per ispezionare le props del componente

Errori di build:

1. Esegua npm install --legacy-peer-deps per assicurarsi che le dipendenze siano installate
2. Controlli la presenza di errori di sintassi nei file JSX
3. Verifichi che gli externals di webpack.config.js siano configurati correttamente
4. Si assicuri che babel sia configurato correttamente per la trasformazione JSX

Suggerimenti per il debug

Console del browser: Apra gli strumenti di sviluppo del browser (F12) per vedere errori e avvisi JavaScript.

React DevTools: Installi l'estensione del browser React DevTools per ispezionare la gerarchia dei componenti e le props.

Debug di PowerShell: Usi Write-Host o Write-Debug nelle sue funzioni PowerShell per tracciare l'esecuzione.

Webpack Dev Server: Durante lo sviluppo, usi webpack-dev-server per il hot reloading:

npm run dev

Quindi configuri PowerShell Universal per caricare dall'URL del dev server.

Esempio: flusso di lavoro completo di un componente

Ecco un esempio completo basato sul progetto ud-mermaid:

1. Creare il componente React (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. Registrare il componente (Components/index.js):

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

3. Creare la funzione PowerShell (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. Compilare e testare:

# 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]
"@
}

Risorse aggiuntive

• Repository GitHub ud-mermaid: https://github.com/ironmansoftware/ud-mermaid - Esempio funzionante completo
• Documentazione di React: https://react.dev
• Documentazione di Webpack: https://webpack.js.org