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, was sie geeignet macht für den Bau von Fernzugriffstools, Text-Dashboards, eingebetteten Kommandozeilen oder Debug-Konsolen.

Erstellung eines Terminals​

Importieren von Terminal

Um die Terminal-Komponente in Ihrer App zu verwenden, stellen Sie sicher, dass Sie die folgende Abhängigkeit in Ihrer pom.xml aufnehmen.

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

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

Code anzeigen

Wie es funktioniert​

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

Die Kernverhalten umfassen:

  • Dateninput: Das Schreiben von Daten an das Terminal aktualisiert den Bildschirm und verarbeitet sowohl Text als auch Steuersequenzen.
  • Datenoutput: Erfasst Benutzertasteneingaben und gibt sie als strukturierte Ereignisse aus.
  • Bildschirmverwaltung: Pflegt einen scrollbaren Verlaufsbuffer und den aktuellen Bildschirmstatus.
  • Cursorverwaltung: Verfolgt die Cursorposition für Texteingaben und Reaktionen auf Steuersequenzen.

Das Terminal ist zustandsbehaftet, was bedeutet, dass es mehrbyte Zeichen ordnungsgemäß rekonstruiert und die Kontinuität über fragmentierte Eingaben hinweg aufrechterhält.

Daten an das Terminal senden​

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

  • write(Object data): Sendet Daten in den Terminalstream.
  • writeln(Object data): Sendet Daten gefolgt von einem Zeilenumbruch.

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

Beispiel​

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

Sie können auch eine Rückruffunktion anhängen, die ausgeführt wird, sobald der Datenchunk verarbeitet wurde:

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

Benutzerinput empfangen​

Das Terminal erfasst benutzergenerierte Eingaben über zwei Ereignisse:

  • Datenereignis (onData): Wird ausgelöst, wenn Text eingegeben wird, und sendet Unicode-Zeichen.
  • Tastaturereignis (onKey): Wird für jeden Tastendruck ausgelöst, einschließlich Informationen über Tasten- und Modifikatorkodierungen wie Ctrl 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 Benutzereingaben, die vom Terminal erfasst werden (zum Beispiel von onData-Ereignissen), werden als UTF-16-Strings ausgegeben.
Wenn Ihr Backend eine andere Kodierung erwartet (z. B. UTF-8-Bytes), müssen Sie die Daten manuell transkodieren.

Legacy Encodings

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

Umgang mit großen Datenströmen​

Da das Terminal nicht sofort unbegrenzte Eingaben rendern kann, wird ein interner Eingabepuffer aufrechterhalten. 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 ordnungsgemäß zu verwalten, sollten Sie Flusskontrolle implementieren.

Basis-Flusskontrollbeispiel​

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

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

Wasserstand-Flusskontrollbeispiel​

Zur effizienteren Kontrolle verwenden Sie Hoch-/Niedrigwasserstände:

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​

Terminaloptionen​

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

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

Beispiel:

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

terminal.setOptions(options);

Terminaldesign​

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

  • Hintergrund- und Vordergrundfarben.
  • Standardfarbenpalette ANSI.
  • 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 die Cursorbewegung, Bildschirmaktualisierungen und Textformatierung verwendet werden.

Erkannte Gruppen:

  • C0 Steuerzeichen (einzelbyte 7-Bit-Befehle, \x00, \x1F, wie Rücktaste und Zeilenumbruch)
  • C1 Steuerzeichen (einzelbyte 8-Bit-Befehle, \x80, \x9F)
  • ESC Sequenzen (beginnt mit ESC (\x1B), wie Cursor speichern/wiederherstellen, Bildschirmausrichtung)
  • CSI Sequenzen (Control Sequence Introducer, ESC [ oder CSI (\x9B), für Operationen wie Scrollen, Löschen und Styling)
  • DCS Sequenzen (Gerätesteuerzeichen, ESC P oder DCS (\x90))
  • OSC Sequenzen (Betriebssystembefehle, 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 über Integrationen unterstützt werden, wenn erforderlich.

Styling​

Loading...