qwefgh90 / ng-terminal

NgTerminal is a web terminal that leverages xterm.js on Angular 11+. You can easily add it into your application by adding <ng-terminal></ng-terminal> into your component.

NgTerminal provides some features including xtermjs. You can adjust dimensions of a terminal by dragging and to fix the number of rows and cols. New usuful features should be added continuously.

Install

npm install ng-terminal --save

Run an example locally

You can run an example in your local environment.

1. git clone https://github.com/qwefgh90/ng-terminal.git
2. npm install
3. npm run start

Getting started

Import NgTerminalModule in your AppModule.

import { NgTerminalModule } from 'ng-terminal';
//...
@NgModule({
    imports: [
        NgTerminalModule
    //...

And put <ng-terminal> into a source code of Component. Now a web terminal appears where you code it. The terminal will do nothing first. So, you should define how to operate.

  <ng-terminal #term></ng-terminal>

You can print or do something on the terminal with NgTerminal object which has some APIs for developers. You can get it by using @ViewChild in your component. It is important that an object of NgTerminalComponent is populated after ngAfterViewInit() is called.

You can print something in a terminal by passing them to the NgTerminal.write() function as an argument as follows, as soon as it receives user inputs from the terminal.

//...
export class YourComponent implements AfterViewInit{
  @ViewChild('term', { static: true }) child: NgTerminal;
  
  ngAfterViewInit(){
    //...
    this.child.keyEventInput.subscribe(e => {
      console.log('keyboard event:' + e.domEvent.keyCode + ', ' + e.key);

      const ev = e.domEvent;
      const printable = !ev.altKey && !ev.ctrlKey && !ev.metaKey;

      if (ev.keyCode === 13) {
        this.child.write('\n' + FunctionsUsingCSI.cursorColumn(1) + '$ '); // \r\n
      } else if (ev.keyCode === 8) {
        if (this.child.underlying.buffer.active.cursorX > 2) {
          this.child.write('\b \b');
        }
      } else if (printable) {
        this.child.write(e.key);
      }
    })
    //...
  }

  //...

NgTerminal

There are two ways to control the terminal. A first way is passing the arguments to input/output properties. API in NgTerminal is also a way to control the terminal. You can get a instance of NgTerminal by using @ViewChild.

Input/Output properties

Four properties (dataSource, rows, cols and draggable) are helpful to construct your temrinal. Check here.

<ng-terminal #term [dataSource]="writeSubject" (keyEvent)="onKeyEvent($event)" 
[rows]="10" 
[cols]="20" 
[draggable]="false"></ng-terminal>

API

NgTerminal is a interface to provide public APIs you can call directly. You can get a object by using @ViewChild with a type of NgTerminal.

  import { NgTerminal } from 'ng-terminal';
  ...
  @ViewChild('term', { static: true }) child: NgTerminal;

Underlying object (Xtermjs)

You can control a instance of the xtermjs directly by getting a property of underlying. Check out API of the Terminal from the API document.

Addons

ng-terminal uses only one addon which is fit to support the resize feature. If you want to use other addons, you can apply them to a underlying object. Maybe you can do that without any problem.

Control sequences

Control sequences is a programing interface to control terminal emulators. There are functions to return control sequences in a class of FunctionUsingCSI.

    import { FunctionsUsingCSI } from 'ng-terminal';
    ...
    const sequences = "data..1" + FunctionsUsingCSI.cursorBackward(1) + '2';
    component.write(sequences);

You can find official supported terminal sequences in https://xtermjs.org/docs/api/vtfeatures/. And you can also read helpful article here. For example, you can move a cursor down by passing \x1b[1E to write(). Try in the sample page

Contribution

NgTerminal is developed with Angular CLI. You can always write issue and contribute through PR to master branch.

Available commands

• Running an example app in your environment: npm start
• Testing ng-terminal: npm test
• Creating a tarball for testing with external angular apps: npm run local
• (Travis) Creating a static page for this project: npm run page
• (Maintainer) Deploying a library to the npm registry: npm run publish