Interaction

Fonctionnalités d'interaction des applications Universal

Universal Apps permet de créer des sites web interactifs avec PowerShell. Plusieurs cmdlets ont été implémentés pour fournir des retours à l'utilisateur, mettre à jour des composants et lire l'état des composants.

Presse-papiers

Vous pouvez placer des données de type chaîne dans le presse-papiers de l'utilisateur avec Set-UDClipboard.

New-UDButton -Text 'Clipboard' -OnClick {
    Set-UDClipboard -Data 'Hello, there!'
}

API

• Set-UDClipboard

Téléchargements

Vous pouvez lancer un téléchargement dans le navigateur de l'utilisateur en utilisant Start-UDDownload. En raison des contraintes de sécurité des navigateurs web, l'utilisateur devra effectuer une action (par exemple, cliquer sur un bouton) pour autoriser le téléchargement. Start-UDDownload n'est pas adapté aux téléchargements de fichiers volumineux.

New-UDButton -Text 'Download' -OnClick {
    Start-UDDownload -StringData 'Hello, World!'
}

Gestionnaires d'événements

De nombreux composants prennent en charge les gestionnaires d'événements sous forme de blocs de script. Vous pouvez également les voir désignés sous le terme de points de terminaison, car c'est ainsi qu'ils étaient appelés dans Universal Dashboard v2. Ces gestionnaires d'événements vous permettent d'invoquer des scripts PowerShell lorsque certaines actions se produisent sur la page.

Par exemple, vous pouvez avoir un clic sur un bouton qui appelle un gestionnaire d'événements. Ce bouton affichera un toast lorsqu'on clique dessus. Vous pouvez inclure n'importe quel cmdlet PowerShell valide dans le code du gestionnaire d'événements.

New-UDButton -Text 'Click Me' -OnClick {
   Show-UDToast 'Hello!'
}

Portée des variables

Les variables sont automatiquement incluses dans la portée des gestionnaires d'événements. Vous pourrez accéder aux variables définies en dehors du gestionnaire d'événements depuis celui-ci.

$MyVariable = "Hello!"
New-UDButton -Text 'Click Me' -OnClick {
   Show-UDToast $MyVariable
}

Données d'événement

Certains gestionnaires d'événements fourniront des données sous forme de chaîne ou de table de hachage. Cela dépend du gestionnaire d'événements utilisé. Par exemple, le gestionnaire d'événements -OnClick de New-UDButton ne fournit aucune donnée. En revanche, -OnChange de New-UDSelect fournit des données d'événement.

Vous pouvez accéder aux données d'événement en utilisant la variable $Body pour accéder aux données sous forme de chaîne (parfois formatée en JSON) ou sous forme de table de hachage en utilisant la variable $EventData.

New-UDSelect -Option {
    New-UDSelectOption -Name 'One' -Value 1
    New-UDSelectOption -Name 'Two' -Value 2
    New-UDSelectOption -Name 'Three' -Value 3
} -OnChange { Show-UDToast -Message $EventData }

Formulaires

Soumettre un formulaire

Vous pouvez forcer la soumission d'un formulaire en utilisant le cmdlet Invoke-UDForm. Vous pouvez optionnellement choisir d'appliquer la validation en incluant le paramètre -Validate.

New-UDForm -Id 'form' -Content {
   New-UDTextbox -Id 'Text' -Label 'Submit Me'
} -OnSubmit {
   Show-UDToast "Hello!"
}

New-UDButton -Text "Submit Form" -OnClick {
   Invoke-UDForm -Id 'form'
}

Valider un formulaire

Vous pouvez forcer la validation d'un formulaire en utilisant Test-UDForm.

New-UDForm -Id 'form' -Content {
   New-UDTextbox -Id 'Text' -Label 'Submit Me'
} -OnSubmit {
   Show-UDToast "Hello!"
} -OnValidate {
   New-UDValidationResult
}

New-UDButton -Text "Submit Form" -OnClick {
   Test-UDForm -Id 'form'
}

JavaScript

Vous pouvez invoquer du JavaScript depuis PowerShell en utilisant le cmdlet Invoke-UDJavaScript.

New-UDButton -Text 'Alert Me' -OnClick {
    Invoke-UDJavaScript -JavaScript 'alert("Hello!")'
}

API

• Invoke-UDJavaScript

Toast

Afficher un toast

Vous pouvez utiliser le cmdlet Show-UDToast pour créer un message toast qui apparaîtra sur la page web de l'utilisateur final. Cela se produit via un websocket et affiche le toast immédiatement au moment de l'appel.

Show-UDToast -Message 'Hello, World!'

Afficher un toast avec une icône

Les toasts prennent en charge les icônes sous forme de chaînes. Vous pouvez utiliser toutes les icônes FontAwesome v5.

Show-UDToast -Icon "Ad" -Message "Test"

Masquer un toast

Masque un toast en fonction de l'identifiant spécifié.

Show-UDToast -Message 'Hello, World!' -Id 'Toast' -Duration 30000

New-UDButton -Text 'Click' -OnClick {
    Hide-UDToast -Id 'Toast'
}

API

• Show-UDToast
• Hide-UDToast

Redirection

Vous pouvez rediriger les utilisateurs vers différentes pages en utilisant le cmdlet Invoke-UDRedirect. Cela se produit via un websocket et effectue la redirection dès que le cmdlet est appelé.

Invoke-UDRedirect http://www.ironmansoftware.com

Invoke-UDRedirect redirigera automatiquement vers les pages du tableau de bord lorsqu'un chemin relatif est utilisé.

Invoke-UDRedirect '/page1' 

Si vous souhaitez rediriger vers un chemin local en dehors du tableau de bord, vous pouvez utiliser le paramètre -Native.

Invoke-UDRedirect '/publishedFolder/test.txt' -Native

API

• Invoke-UDRedirect

Modal

Vous pouvez ouvrir un modal en utilisant le cmdlet Show-UDModal. Il s'ouvre dès que vous l'appelez. Vous pouvez inclure n'importe quel composant dans le modal.

En savoir plus sur les modals ici.

Gestion de l'état des composants

Vous pouvez gérer l'état des composants dynamiquement en utilisant les commandes UDElement.

Obtenir l'état d'un composant

Vous pouvez récupérer l'état d'un élément en utilisant Get-UDElement. L'état sera retourné sous forme de table de hachage. Cela est principalement utile pour les composants de saisie.

$Value = (Get-UDElement -Id 'txtExample').value

Définir l'état d'un composant

Vous pouvez également définir l'état d'un composant en utilisant Set-UDElement. Vous devrez spécifier un identifiant et une table de hachage de propriétés à définir sur le composant. Tous les composants intégrés prennent en charge Set-UDElement.

New-UDTextbox -Id 'textbox'

New-UDButton -Text 'Click' -OnClick {
    Set-UDElement -Id 'textbox' -Properties @{
        Value = 'My Value'
    }
}

Supprimer un composant

Vous pouvez supprimer des composants de la page en utilisant Remove-UDElement. Le composant n'apparaîtra plus sur la page.

Remove-UDComponent -Id 'txtExample'

Ajouter un composant

Ajoutez un composant enfant à un composant parent existant.

New-UDElement -Id 'myDiv' -Tag div

New-UDButton -Text 'Click' -OnClick {
    Add-UDElement -ParentId 'myDiv' -Content {
        New-UDTypography -Text 'Hi'
    }
}

Vider un composant

Vous pouvez supprimer tous les composants enfants d'un composant en utilisant Clear-UDElement.

New-UDElement -Id 'myDiv' -Tag div

New-UDButton -Text 'Click' -OnClick {
    Add-UDElement -ParentId 'myDiv' -Content {
        New-UDTypography -Text 'Hi'
    }
    Add-UDElement -ParentId 'myDiv' -Content {
        New-UDTypography -Text 'Hi'
    }
    Add-UDElement -ParentId 'myDiv' -Content {
        New-UDTypography -Text 'Hi'
    }
}

New-UDButton -Text 'Clear' -OnClick {
    Clear-UDElement -Id 'myDiv'
}

Recharger un composant

Certains composants prennent en charge le rechargement. Vous pouvez déclencher le rechargement d'un composant en utilisant Sync-UDElement.

New-UDDynamic -Id 'reloadMe' -Content {
    Get-Date
}

New-UDButton -Text 'Reload' -OnClick {
    Sync-UDElement -Id 'reloadMe'
}

Sélectionner un composant

Vous pouvez sélectionner un composant avec Select-UDElement.

New-UDElement -Id 'txt' -Tag input -Properties @{ type = text }

New-UDButton -Text 'Select' -OnClick {
    Select-UDElement -Id 'txt' -ScrollToElement
}

Intégration avec l'hôte PowerShell

Les tableaux de bord s'intègrent directement avec l'hôte PowerShell pour fournir des fonctionnalités basées sur des cmdlets standard.

Read-Host

L'utilisation du cmdlet Read-Host provoque l'affichage d'une boîte de dialogue sur le tableau de bord de l'utilisateur. Le texte saisi sera retourné par le cmdlet.

$Text = Read-Host 'Enter Some Text'
Show-UDToast $Text

Get-Credential

L'utilisation de Get-Credential provoque l'affichage d'une boîte de dialogue qui accepte un nom d'utilisateur et un mot de passe. Un objet PSCredential sera retourné par le cmdlet.

Get-Credential -UserName "adam"

Write-Progress

Les cmdlets qui utilisent le flux de progression ou l'utilisation du cmdlet Write-Progress entraîneront l'affichage d'une boîte de dialogue de progression. La fenêtre contextuelle affichera l'activité, le pourcentage d'avancement et l'opération en cours.

1..100 | ForEach-Object {
    Write-Progress -PercentComplete $_ -Activity 'Processing...' -CurrentOperation "User $_"
    Start-Sleep -Milliseconds 500
}

Vous pouvez désactiver l'intégration de Write-Progress en définissant $ProgressPreference sur SilentlyContinue.

$ProgressPreference = 'SilentlyContinue'

Invite de choix

Vous pouvez utiliser la fonction $Host.UI.PromptForChoice pour afficher une boîte de dialogue à sélection multiple.

$Title = "Welcome"
$Info = "Just to Demo Prompt for Choice"

$options = [System.Management.Automation.Host.ChoiceDescription[]] @("Power", "Shell", "Quit")
[int]$defaultchoice = 2
$opt = $host.UI.PromptForChoice($Title , $Info , $Options, $defaultchoice)
switch ($opt) {
    0 { Show-UDToast "Power" }
    1 { Show-UDToast "Shell" }
    2 { Show-UDToast "Good Bye!!!" }
}

Write-Host

Write-Host dans les applications écrira dans l'onglet Journal de la console d'administration pour l'application. Si vous souhaitez recevoir ces messages de journal dans la console de votre navigateur dans les outils de développement, vous pouvez activer la journalisation de la console dans appsettings.json.

{
    "UniversalDashboard": {
        "ConsoleLog": true
    }
}

API

• Get-UDElement
• Set-UDElement
• Clear-UDElement
• Remove-UDElement
• Sync-UDElement
• Select-UDElement