Passer au contenu principal

Terminal

Ouvrir dans ChatGPT
Ombre dwc-terminal 24.10
Java API

Le composant Terminal est un émulateur de terminal interactif qui se comporte comme une console système traditionnelle. Il gère la sortie de texte, l'entrée utilisateur, les séquences de contrôle et les tampons d'écran, ce qui le rend adapté à la construction d'outils d'accès à distance, de dashboards textuels, de shells de commande intégrés ou de consoles de débogage.

Création d'un terminal​

Importation du Terminal

Pour utiliser le composant Terminal dans votre application, assurez-vous d'inclure la dépendance suivante dans votre pom.xml.

<dependency>
  <groupId>com.webforj</groupId>
  <artifactId>webforj-terminal</artifactId>
</dependency>

L'exemple suivant construit un shell de commande interactif avec commandes tapées, navigation dans l'historique et sortie personnalisée.

Afficher le code

Comment cela fonctionne​

Le terminal gère une grille de cellules de texte, traite les flux de caractères entrants et réagit aux actions de l'utilisateur comme la saisie ou la sélection de texte. Il interprète automatiquement les caractères de contrôle et les séquences d'échappement pour le mouvement du curseur, les changements de couleur et l'effacement de l'écran.

Les comportements principaux incluent :

  • Entrée de données : L'écriture de données dans le terminal met à jour l'écran, gérant à la fois le texte et les séquences de contrôle.
  • Sortie de données : Capture les frappes de l'utilisateur et les émet sous forme d'événements structurés.
  • Gestion de l'écran : Maintient un tampon d'historique déroulant et l'état actuel de l'écran.
  • Gestion du curseur : Suit la position du curseur pour les entrées de texte et les réponses aux séquences de contrôle.

Le terminal est à état, ce qui signifie qu'il reconstruit correctement les caractères multibytes et maintient la continuité à travers les entrées fragmentées.

Envoi de données au terminal​

Les données sont envoyées au terminal en utilisant les méthodes write et writeln :

  • write(Object data): Envoie des données dans le flux du terminal.
  • writeln(Object data): Envoie des données suivies d'un saut de ligne.

Le terminal traite toutes les données entrantes comme des chaînes UTF-16. Il gère automatiquement les caractères multibytes, même lorsque l'entrée arrive en morceaux fragmentés.

Exemple​

terminal.write("echo Hello World\n");
terminal.writeln("Ready.");

Vous pouvez également attacher un rappel qui s'exécute une fois que le morceau de données a été traité :

terminal.write("Long command output", e -> {
  System.out.println("Données traitées.");
});

Réception de l'entrée utilisateur​

Le terminal capture les entrées générées par l'utilisateur via deux événements :

  • Événement de données (onData) : Se déclenche lorsque du texte est saisi, envoyant des caractères Unicode.
  • Événement de clé (onKey) : Se déclenche pour chaque pression de touche, y compris des informations sur les codes de touche et les modificateurs comme Ctrl ou Alt.

Ces événements peuvent être utilisés pour relayer l'entrée utilisateur à un backend, mettre à jour des éléments d'interface utilisateur ou déclencher des actions personnalisées.

Exemple​

terminal.onData(event -> {
  String userInput = event.getValue();
  backend.send(userInput);
});

terminal.onKey(event -> {
  if (event.isControlKey() && "C".equals(event.getKey())) {
      backend.send("SIGINT");
  }
});

Toutes les entrées utilisateur capturées par le terminal (comme celles des événements onData) sont émises sous forme de chaînes UTF-16.
Si votre backend s'attend à un encodage différent (comme des octets UTF-8), vous devez transcoder manuellement les données.

Encodages hérités

Le terminal ne prend pas en charge les encodages hérités tels que ISO-8859.
Si vous avez besoin de compatibilité avec des systèmes non-UTF-8, utilisez un transcoder externe (par exemple, luit ou iconv) pour convertir les données avant de les écrire ou de les lire dans ou du terminal.

Gestion de grands flux de données​

Parce que le terminal ne peut pas rendre instantanément un input illimité, il maintient un tampon d'entrée interne. Si ce tampon devient trop grand (environ 50 Mo par défaut), de nouvelles données entrantes peuvent être supprimées pour protéger la performance du système.

Pour gérer correctement les sources de données rapides, vous devez mettre en œuvre un contrôle de flux.

Exemple de contrôle de flux de base​

Mettez en pause votre backend jusqu'à ce que le terminal ait fini de traiter un morceau :

pty.onData(chunk -> {
  pty.pause();
  terminal.write(chunk, result -> {
    pty.resume();
  });
});

Exemple de contrôle de flux de jauge​

Pour un contrôle plus efficace, utilisez des jauges hautes/basses :

int HIGH_WATERMARK = 100_000;
int LOW_WATERMARK = 10_000;

int bufferedBytes = 0;

pty.onData(chunk -> {
  bufferedBytes += chunk.length;

  terminal.write(chunk, e -> {
    bufferedBytes -= chunk.length;
    if (bufferedBytes < LOW_WATERMARK) {
        pty.resume();
    }
  });

  if (bufferedBytes > HIGH_WATERMARK) {
    pty.pause();
  }
});
Afficher le code

Personnalisation​

Options du terminal​

La classe TerminalOptions vous permet de configurer le comportement :

  • Clignotement du curseur.
  • Paramètres de police (famille, taille, poids).
  • Taille du tampon de retour en arrière.
  • Hauteur de ligne et espacement des lettres.
  • Paramètres d'accessibilité (mode lecteur d'écran).

Exemple :

TerminalOptions options = new TerminalOptions()
  .setCursorBlink(true)
  .setFontFamily("Courier New, monospace")
  .setFontSize(13)
  .setScrollback(5000);

terminal.setOptions(options);

Thème du terminal​

Vous pouvez styliser le terminal en utilisant TerminalTheme, qui définit :

  • Couleurs d'arrière-plan et de premier plan.
  • Palette de couleurs ANSI standard.
  • Couleurs d'arrière-plan du curseur et de sélection.

Exemple :

TerminalTheme theme = new TerminalTheme();
theme.setBackground("#1e1e1e");
theme.setForeground("#cccccc");
terminal.setTheme(theme);
Afficher le code

Séquences prises en charge​

Le terminal prend en charge un large éventail de séquences de contrôle standard utilisées pour le mouvement du curseur, les mises à jour de l'écran et le formatage de texte.

Groupes reconnus :

  • Codes de contrôle C0 (commandes à 7 bits à octet unique, \x00, \x1F, comme retour en arrière et saut de ligne)
  • Codes de contrôle C1 (commandes à 8 bits à octet unique, \x80, \x9F)
  • Séquences ESC (commençant par ESC (\x1B), comme enregistrer/restaurer le curseur, alignement de l'écran)
  • Séquences CSI (Introducer de séquence de contrôle, ESC [ ou CSI (\x9B), pour des opérations comme le défilement, l'effacement et le style)
  • Séquences DCS (Chaînes de contrôle de périphérique, ESC P ou DCS (\x90))
  • Séquences OSC (Commandes du système d'exploitation, ESC ] ou OSC (\x9D), pour définir le titre de la fenêtre, les liens hypertextes et les couleurs)
Gestion des séquences exotiques et personnalisées

Certaines séquences exotiques comme APC,PM, et SOS sont reconnues mais ignorées silencieusement.
Des séquences personnalisées peuvent être prises en charge via des intégrations si nécessaire.

Stylisation​

Loading...