Zum Hauptinhalt springen

Terminal

In ChatGPT öffnen
Schatten dwc-terminal 24.10
Java API

Die Terminal-Komponente ist ein interaktiver Terminalemulator, der sich wie eine traditionelle Systemkonsole verhält. Sie verarbeitet Textausgaben, Benutzereingaben, Steuersequenzen und Bildschirmpuffer und eignet sich daher hervorragend zum Erstellen von Remote-Access-Tools, Text-Dashboards, eingebetteten Befehlszeilen oder Debug-Konsole.

Erstellung eines Terminals​

Importieren von Terminal

Um die Terminal-Komponente in Ihrer Anwendung zu verwenden, stellen Sie sicher, dass Sie die folgende Abhängigkeit in Ihrer pom.xml einfügen.

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

Im folgenden Beispiel wird eine interaktive Befehlszeile mit eingegebenen Befehlen, History-Navigation und benutzerdefinierter Ausgabe erstellt.

Code anzeigen

Funktionsweise​

Das Terminal verwaltet ein Gitter von Textzellen, verarbeitet eingehende Zeichenströme und reagiert auf Benutzeraktionen wie das Tippen oder Auswählen von Text. Es interpretiert automatisch Steuerzeichen und Escape-Sequenzen für die Cursorbewegung, Farbänderungen und das Löschen des Bildschirms.

Die grundlegenden Funktionen umfassen:

  • Daten-Eingabe: Das Schreiben von Daten ins Terminal aktualisiert den Bildschirm und behandelt sowohl Text- als auch Steuersequenzen.
  • Daten-Ausgabe: Erfasst Benutzeranschläge und gibt sie als strukturierte Ereignisse aus.
  • Bildschirmverwaltung: Hält einen scrollbaren Verlaufs-Puffer und den aktuellen Bildschirmstatus.
  • Cursorverwaltung: Verfolgt die Cursorposition für die Texteingabe und die Antworten auf Steuersequenzen.

Das Terminal ist zustandsbehaftet, das bedeutet, dass es mehrbyteige Zeichen richtig rekonstruiert und die Kontinuität über fragmentierte Eingaben aufrechterhält.

Senden von Daten an das Terminal​

Daten werden an das Terminal mit den Methoden write und writeln gesendet:

  • write(Object data): Sendet Daten in den Terminalstrom.
  • writeln(Object data): Sendet Daten gefolgt von einer neuen Zeile.

Das Terminal verarbeitet alle eingehenden Daten als UTF-16-Strings. Es verarbeitet automatisch mehrbyteige Zeichen, selbst wenn die Eingabe in fragmentierten Abschnitten ankommt.

Beispiel​

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

Sie können auch einen Callback anhängen, der ausgeführt wird, sobald das Datenchunk verarbeitet wurde:

terminal.write("Lange Befehlsausgabe", e -> {
  System.out.println("Daten verarbeitet.");
});

Empfang von Benutzereingaben​

Das Terminal erfasst benutzergenerierte Eingaben über zwei Ereignisse:

  • Datenereignis (onData): Wird ausgelöst, wenn eine Texteingabe erfolgt, und sendet Unicode-Zeichen.
  • Tastaturereignis (onKey): Wird für jeden Tastendruck ausgelöst, einschließlich Informationen über Tasten-Codes und Modifikatoren wie Strg oder Alt.

Diese Ereignisse können verwendet werden, um Benutzereingaben an ein Backend weiterzuleiten, UI-Elemente zu aktualisieren oder benutzerdefinierte Aktionen auszulösen.

Beispiel​

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

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

Alle von dem Terminal erfassten Benutzereingaben (z. B. von onData-Ereignissen) werden als UTF-16-Strings ausgegeben. Wenn Ihr Backend eine andere Kodierung (wie UTF-8-Bytes) erwartet, müssen Sie die Daten manuell umkodieren.

Legacy Encodings

Das Terminal unterstützt keine veralteten Kodierungen wie ISO-8859. Wenn Sie eine Kompatibilität mit Nicht-UTF-8-Systemen benötigen, verwenden Sie einen externen Transcoder (z. B. luit oder iconv), um die Daten vor dem Schreiben in oder Lesen aus dem Terminal zu konvertieren.

Verarbeitung großer Datenströme​

Da das Terminal nicht unbegrenzte Eingaben sofort rendern kann, verwaltet es einen internen Eingabepuffer. Wenn dieser Puffer zu groß wird (standardmäßig etwa 50MB), können neue eingehende Daten verworfen werden, um die Systemleistung zu schützen.

Um schnelle Datenquellen richtig zu verwalten, sollten Sie Flusssteuerung implementieren.

Beispiel für grundlegende Flusssteuerung​

Pausieren Sie Ihr Backend, bis das Terminal ein Chunk verarbeitet hat:

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

Beispiel für Flusssteuerung mit Wasserzeichen​

Für eine effizientere Steuerung verwenden Sie Hoch-/Niedrig-Wasserzeichen:

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();
  }
});
Code anzeigen

Anpassung​

Terminal-Optionen​

Die Klasse TerminalOptions ermöglicht es Ihnen, das Verhalten zu konfigurieren:

  • Cursorblinken.
  • Schriftarteinstellungen (Familie, Größe, Gewicht).
  • Größe des Scrollback-Puffers.
  • Zeilenhöhe und Buchstabenabstand.
  • Barrierefreiheitseinstellungen (Bildschirmlesemodus).

Beispiel:

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

terminal.setOptions(options);

Terminal-Thema​

Sie können das Terminal mit TerminalTheme gestalten, das definiert:

  • Hintergrund- und Schriftfarben.
  • Standard ANSI Farbpalette.
  • Hintergrundfarben für Cursor und Auswahl.

Beispiel:

TerminalTheme theme = new TerminalTheme();
theme.setBackground("#1e1e1e");
theme.setForeground("#cccccc");
terminal.setTheme(theme);
Code anzeigen

Unterstützte Sequenzen​

Das Terminal unterstützt eine Vielzahl von standardmäßigen Steuersequenzen, die für Cursorbewegungen, Bildschirmaktualisierungen und Textformatierungen verwendet werden.

Erkannte Gruppen:

  • C0 Steuercodes (einzelbyte 7-Bit-Befehle, \x00, \x1F, wie Rückschritt und Zeilenumbruch)
  • C1 Steuercodes (einzelbyte 8-Bit-Befehle, \x80, \x9F)
  • ESC Sequenzen (beginnend mit ESC (\x1B), wie Speichern/Wiederherstellen des Cursors, Bildschirmausrichtung)
  • CSI Sequenzen (Control Sequence Introducer, ESC [ oder CSI (\x9B), für Operationen wie Scrollen, Löschen und Styling)
  • DCS Sequenzen (Device Control Strings, ESC P oder DCS (\x90))
  • OSC Sequenzen (Operating System Commands, ESC ] oder OSC (\x9D), zum Setzen des Fenstertitels, Hyperlinks und Farben)
Umgang mit exotischen und benutzerdefinierten Sequenzen

Einige exotische Sequenztypen wie APC, PM und SOS werden erkannt, aber stillschweigend ignoriert. Benutzerdefinierte Sequenzen können bei Bedarf über Integrationen unterstützt werden.

Styling​

Loading...