中文版 | English

vue-web-terminal

A web-side command line plugin built by Vue, supports multiple message formats such as tables, json, and codes, supports custom message styles, command line libraries, typing search prompts, etc., and simulates native terminal support ← → cursor toggle and ↑ ↓ history command toggle.

Feature Support

• Supported message formats: text, table, json, code/multiline text, html
• Highlight.js, Codemirror.js code highlighting
• ← → key cursor switch
• ↑ ↓ key history command toggle
• Full-screen display
• Window drag
• Custom command library
• User inputting filter
• Command search prompt, use the Tab key to quickly fill
• Multiple lots support custom styles
• Support API interface: execute command, push message, simulate drag and drop, get position, full screen, modify context, etc.

Online Experience

Demo：https://tzfun.github.io/vue-web-terminal/

Quick Start

Install vue-web-terminal by npm

//  install for vue2
npm install vue-web-terminal@2.xx --save

//  install for vue3
npm install vue-web-terminal@3.xx --save 

Use Terminal plugin in main.js

import Terminal from 'vue-web-terminal'

// for vue2
Vue.use(Terminal)

// for vue3
const app = createApp(App)
app.use(Terminal)

Example:

<template>
  <div id="app">
    <terminal name="my-terminal" @execCmd="onExecCmd"></terminal>
  </div>
</template>

<script>
import Terminal from "vue-web-terminal"

export default {
  name: 'App',
  components: {Terminal},
  methods: {
    onExecCmd(key, command, success, failed) {
      if (key === 'fail') {
        failed('Something wrong!!!')
      } else {
        let allClass = ['success', 'error', 'system', 'info', 'warning'];

        let clazz = allClass[Math.floor(Math.random() * allClass.length)];
        success({
          type: 'normal',
          class: clazz,
          tag: '成功',
          content: command
        })
      }
    }
  }
}
</script>

<style>
body, html, #app {
  margin: 0;
  padding: 0;
  width: 100%;
  height: 100%;
}
</style>

Document

Attributes

Terminal tag supports attribute parameter table.

Events

Terminal tag support event table

Slots

Terminal supports the following custom slots, this feature is supported in 2.0.11 and 3.0.8 versions and later.

example:

<terminal :name="name" @execCmd="onExecCmd">
  <template #header>
    This is my custom header
  </template>

  <template #json="data">
    {{ data.message }}
  </template>

  <template #helpBox="{showHeader, item}">
    {{ item }}
  </template>
</terminal>

Drag

To enable drag and drop, you need to set showHeader to true and configure dragConf. You can configure the window size through width and height of dragConf.

<terminal name="my-terminal" 
          show-header 
          :drag-conf="{width: 700, height: 500}"></terminal>

The dragConf structure is as follows:

In addition to mouse control, you can also call API to simulate dragging

Api

This plugin provides some APIs that can use Vue to actively initiate event requests to the plugin.

PS：All api calls require the name of the terminal.

import Terminal from "vue-web-terminal"

//  det api
Terminal.$api

pushMessage()

//  Each terminal will define a name, see the previous document for details
let name = 'my-terminal'
let message = {
    type: 'normal',
    class: 'warning',
    content: 'This is a wanning message.'
}

Terminal.$api.pushMessage(name, message)

updateContext()

For example, /vue-web-terminal/tzfun in the current input line $ /vue-web-terminal/tzfun > is the context, and the context text can be freely set by the developer, but you need to use .sync to bind a variable.

<template>
  <div id="app">
    <terminal name="my-terminal" :context.sync="context"></terminal>
  </div>
</template>

<script>
import Terminal from "vue-web-terminal"

export default {
  name: 'App',
  data() {
    return {
      context: '/hello'
    }
  },
  methods: {
    _updateContext(newCtx) {
      Terminal.$api.updateContext("my-terminal", newCtx)
    }
  }
}
</script>

fullscreen()

Make the current terminal enter or exit full screen.

Terminal.$api.fullscreen('my-terminal')

isFullscreen()

Determine if the current state is full screen.

//  true or false
let fullscreen = Terminal.$api.isFullscreen('my-terminal')

dragging()

When Feature Drag is enabled, you can use the following method to simulate drag to change the window position, where the parameter x is the distance from the left border of the terminal to the left border of the browser's visible range, in px, y is the distance from the upper border of the terminal to the upper border of the browser's visible range.

Terminal.$api.dragging('my-terminal', {
    x: 100,
    y: 200
})

execute()

You can use the api to execute a command to the Terminal, and the execution process will be echoed in the Terminal window. This is a way to use a script to simulate the user executing the command.

Terminal.$api.execute('my-terminal', 'help :local')

getPosition()

When in drag mode, this interface can get the position of the window.

let pos = Terminal.$api.getPosition('my-terminal')
console.log(pos.x, pos.y)

focus()

Get input focus

Terminal.$api.focus('my-terminal')

Message

This plugin defines a message object, any message must be defined in this format to display correctly.

normal

The content is in string format and supports html tags. The time field will be automatically filled in when pushing. The content is required, and the others are optional.

{
  "time": "2022-02-17 18:12:20",
  "class": "success",
  "type": "normal",
  "content": "这是一条普通文本消息",
  "tag": "Tag success"
}

json

When type is json, content needs to pass a json object.

{
  "type": "json",
  "content": {
    "key": "value",
    "num": 1
  }
}

code

When type is code, the content type is a string, and you can directly pass in text or code.

{
  "type": "json",
  "content": "import Terminal from 'vue-web-terminal'\n\nVue.use(Terminal)"
}

highlight.js

code type messages support highlight.js highlighting.

First you need to configure Highlight.js, install it at the main.js entry, see [https://www.npmjs.com/package/highlight.js](https://www.npmjs.com/ package/highlight.js)

import Terminal from 'vue-web-terminal'
import hljs from 'highlight.js'
import java from 'highlight.js/lib/languages/java'
import vuePlugin from "@highlightjs/vue-plugin"
import 'highlight.js/styles/tomorrow-night-bright.css'

hljs.registerLanguage('java', java)
Vue.use(vuePlugin)
Vue.use(Terminal, {highlight: true})

vue2 version dependency recommendation:

{
  "@highlightjs/vue-plugin": "^1.0.2",
  "highlight.js": "^10.7.3"
}

codemirror.js

code type messages also support codemirror highlighting. For detailed configuration, see https://www.npmjs.com/package/vue-codemirror

It also only needs to be installed at the main.js entry. Recommended version: "vue-codemirror": "^4.0.6"

import VueCodemirror from 'vue-codemirror'
import 'codemirror/lib/codemirror.css'
import 'codemirror/theme/darcula.css'
import 'codemirror/mode/clike/clike.js'
import 'codemirror/addon/edit/closebrackets.js'

Vue.use(VueCodemirror)
Vue.use(Terminal, {
    codemirror: {
        tabSize: 4,
        mode: 'text/x-java',
        theme: "darcula",
        lineNumbers: true,
        line: true,
        smartIndent: true
    }
})

table

When type is table, content is the table configuration, head is the table header, rows is the data of each row, and html tags are supported.

{
  "type": "table",
  "content": {
    "head": [
      "title1",
      "title2",
      "title3",
      "title4"
    ],
    "rows": [
      [
        "name1",
        "hello world",
        "this is a test1",
        "xxxxxxxx"
      ],
      [
        "name2",
        "hello world",
        "this is a test2 test2",
        "xxxxxxxx"
      ]
    ]
  }
}

html

When type is html, the content format can be customized, and content is composed of html tags.

execCmd(key, command, success)
{
    // ...
    success({
        type: 'html',
        content: `
          <ul class="custom-content">
            <li class="t-dir">目录1</li>
            <li class="t-dir">目录2</li>
            <li class="t-dir">目录3</li>
            <li class="t-file">文件1</li>
            <li class="t-file">文件2</li>
            <li class="t-file">文件3</li>
          </ul>
          `
    })
    // ...
}

Command

If the command help search function is enabled, you need to pass in a custom command library before instantiating Terminal. The incoming command library is an array of N commands. The following are the rules for defining the command format:

CommandExample

The format of the example is relatively simple, des is a description, cmd is a specific command, and the json format is as follows:

[
  {
    "des": "Get all network information",
    "cmd": "netstat -a"
  },
  {
    "des": "Open a website",
    "cmd": "open blog.beifengtz.com"
  }
]

Help

The plugin has a built-in help command to facilitate users to search the command library. Through the help command, you can view the key, grouping, and explanation sample information of the command.

# Show all command information
help

# Fuzzy search command, search for build prefixed commands
help build*

# Fuzzy search name, search for commands with build
help *build*

# Search by group, search keywords need to start with ":", search for all commands grouped as build
help :build

Local

Terminal has the following built-in commands by default and cannot be replaced.

[
  {
    "key": "help",
    "title": "Help",
    "group": "local",
    "usage": "help [pattern]",
    "description": "Show command document.",
    "example": [
      {
        "des": "Get help documentation for exact match commands.",
        "cmd": "help refresh"
      },
      {
        "des": "Get help documentation for fuzzy matching commands.",
        "cmd": "help *e*"
      },
      {
        "des": "Get help documentation for specified group, match key must start with ':'.",
        "cmd": "help :groupA"
      }
    ]
  },
  {
    "key": "clear",
    "title": "Clear logs",
    "group": "local",
    "usage": "clear [history]",
    "description": "Clear screen or history.",
    "example": [
      {
        "cmd": "clear",
        "des": "Clear all records on the current screen."
      },
      {
        "cmd": "clear history",
        "des": "Clear command history."
      }
    ]
  },
  {
    "key": "open",
    "title": "Open page",
    "group": "local",
    "usage": "open <url>",
    "description": "Open a specified page.",
    "example": [
      {
        "cmd": "open blog.beifengtz.com"
      }
    ]
  }
]

License

Apache License 2.0