Saltar al contenido principal

Terminal

Abrir en ChatGPT
Sombra dwc-terminal 24.10
Java API

El componente Terminal es un emulador de terminal interactivo que se comporta como una consola de sistema tradicional. Maneja la salida de texto, la entrada del usuario, las secuencias de control y los buffers de pantalla, lo que lo hace adecuado para construir herramientas de acceso remoto, dashboards de texto, shells de comandos integrados o consolas de depuración.

Creación de un terminal​

Importando Terminal

Para utilizar el componente Terminal en tu aplicación, asegúrate de incluir la siguiente dependencia en tu pom.xml.

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

El siguiente ejemplo construye un shell de comandos interactivo con comandos escritos, navegación por el historial y salida personalizada.

Mostrar Código

Cómo funciona​

El terminal gestiona una cuadrícula de celdas de texto, procesa flujos de caracteres entrantes y reacciona a acciones del usuario como escribir o seleccionar texto. Interpreta automáticamente los caracteres de control y las secuencias de escape para el movimiento del cursor, cambios de color y borrado de pantalla.

Los comportamientos principales incluyen:

  • Entrada de datos: Escribir datos en el terminal actualiza la pantalla, manejando tanto texto como secuencias de control.
  • Salida de datos: Captura las pulsaciones del usuario y las emite como eventos estructurados.
  • Gestión de pantalla: Mantiene un buffer de historial desplazable y el estado actual de la pantalla.
  • Manejo del cursor: Rastrear la posición del cursor para la entrada de texto y las respuestas a las secuencias de control.

El terminal es con estado, lo que significa que reconstruye correctamente los caracteres multibyte y mantiene la continuidad a través de entradas fragmentadas.

Enviando datos al terminal​

Los datos se envían al terminal utilizando los métodos write y writeln:

  • write(Object data): Envía datos al flujo del terminal.
  • writeln(Object data): Envía datos seguidos de una nueva línea.

El terminal procesa todos los datos entrantes como cadenas UTF-16. Maneja automáticamente los caracteres multibyte, incluso cuando la entrada llega en fragmentos.

Ejemplo​

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

También puedes adjuntar una devolución de llamada que se ejecute una vez que se haya procesado el fragmento de datos:

terminal.write("Salida de comando larga", e -> {
  System.out.println("Datos procesados.");
});

Recibiendo la entrada del usuario​

El terminal captura la entrada generada por el usuario a través de dos eventos:

  • Evento de Datos (onData): Se activa cuando ocurre una entrada de texto, enviando caracteres Unicode.
  • Evento de Tecla (onKey): Se activa por cada pulsación de tecla, incluyendo información sobre códigos de tecla y modificadores como Ctrl o Alt.

Estos eventos se pueden usar para retransmitir la entrada del usuario a un backend, actualizar elementos de la interfaz o activar acciones personalizadas.

Ejemplo​

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

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

Toda la entrada del usuario capturada por el terminal (como la de eventos onData) se emite como cadenas UTF-16.
Si tu backend espera un tipo de codificación diferente (como bytes UTF-8), debes transcodificar manualmente los datos.

Codificaciones Legadas

El terminal no soporta codificaciones legadas como ISO-8859.
Si necesitas compatibilidad con sistemas que no sean UTF-8, utiliza un transcodificador externo (por ejemplo, luit o iconv) para convertir los datos antes de escribirlos o leerlos desde el terminal.

Manejo de grandes flujos de datos​

Debido a que el terminal no puede renderizar instantáneamente una entrada ilimitada, mantiene un buffer interno de entrada. Si este buffer crece demasiado (generalmente alrededor de 50MB), los nuevos datos entrantes pueden ser descartados para proteger el rendimiento del sistema.

Para gestionar adecuadamente fuentes de datos rápidas, debes implementar control de flujo.

Ejemplo básico de control de flujo​

Pausa tu backend hasta que el terminal haya terminado de procesar un fragmento:

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

Ejemplo de control de flujo con marca de agua​

Para un control más eficiente, utiliza marcas de agua alta/baja:

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();
  }
});
Mostrar Código

Personalización​

Opciones del terminal​

La clase TerminalOptions te permite configurar el comportamiento:

  • Parpadeo del cursor.
  • Configuraciones de fuente (familia, tamaño, peso).
  • Tamaño del buffer de retroceso.
  • Altura de línea y espaciado de letras.
  • Configuraciones de accesibilidad (modo lector de pantalla).

Ejemplo:

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

terminal.setOptions(options);

Tema del terminal​

Puedes estilizar el terminal utilizando TerminalTheme, que define:

  • Colores de fondo y primer plano.
  • Paleta de colores ANSI estándar.
  • Colores de fondo del cursor y de selección.

Ejemplo:

TerminalTheme theme = new TerminalTheme();
theme.setBackground("#1e1e1e");
theme.setForeground("#cccccc");
terminal.setTheme(theme);
Mostrar Código

Secuencias soportadas​

El terminal soporta una amplia gama de secuencias de control estándar utilizadas para el movimiento del cursor, actualizaciones de pantalla y formato de texto.

Grupos reconocidos:

  • Códigos de control C0 (comandos de 7 bits de un solo byte, \x00, \x1F, como retroceso y avance de línea)
  • Códigos de control C1 (comandos de 8 bits de un solo byte, \x80, \x9F)
  • Secuencias ESC (comenzando con ESC (\x1B), como guardar/restaurar cursor, alineación de pantalla)
  • Secuencias CSI (Introducción de Secuencia de Control, ESC [ o CSI (\x9B), para operaciones como desplazamiento, borrado y estilo)
  • Secuencias DCS (Cadenas de Control de Dispositivo, ESC P o DCS (\x90))
  • Secuencias OSC (Comandos del Sistema Operativo, ESC ] o OSC (\x9D), para establecer título de ventana, hipervínculos y colores)
Manejo de Secuencias Exóticas y Personalizadas

Algunos tipos de secuencias exóticas como APC, PM y SOS son reconocidos pero se ignoran silenciosamente.
Las secuencias personalizadas pueden ser soportadas a través de integraciones si es necesario.

Estilo​

Loading...