Vue Web Terminal

https://tzfun.github.io/vue-web-terminal/
Admin
A powerful Vue plugin that provides a web-based command line terminal with dragging, zooming,...
Tokens:17,679
Snippets:158
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install vue-web-terminal using pnpm

Source: https://tzfun.github.io/vue-web-terminal/getting-started

Installs the vue-web-terminal plugin using pnpm. Supports both Vue 2 (version 2.x.x) and Vue 3 (version 3.x.x).

```bash
# for vue2
pnpm install vue-web-terminal@2

# for vue3
pnpm install vue-web-terminal@3

```

--------------------------------

### Command Example Usage (JSON)

Source: https://tzfun.github.io/vue-web-terminal/others

An example of a command example object, showing a description for getting task information and the corresponding command string.

```json
{
    "des": "Get all task information",
    "cmd": "task -o pack"
  }

```

--------------------------------

### Basic vue-web-terminal implementation

Source: https://tzfun.github.io/vue-web-terminal/getting-started

Demonstrates the basic implementation of the vue-web-terminal component within a Vue 3 application using `<script setup>`. It includes configurations for drag behavior and command execution handling.

```vue
<script setup lang="ts">
import {Terminal, DragConfig, FailedFunc, SuccessFunc, TerminalMessageClass} from 'vue-web-terminal';
import {reactive} from "vue";

const dragConf = reactive<DragConfig>({
  width: "50%",
  height: "70%",
  zIndex: 100,
  init: {
    x: 200,
    y: 200
  },
  pinned: false
})

const onExecCmd = (key: string, command: string, success: SuccessFunc, failed: FailedFunc) => {
  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 as TerminalMessageClass,
      tag: clazz,
      content: `Your command is '${command}'`
    })
  }
}
</script>

<template>
  <terminal name="my-terminal"
            theme="dark"
            @exec-cmd="onExecCmd"
            :drag-conf="dragConf"
  />
</template>

<style scoped>
</style>

```

--------------------------------

### Install vue-web-terminal using npm

Source: https://tzfun.github.io/vue-web-terminal/getting-started

Installs the vue-web-terminal plugin using npm. Supports both Vue 2 (version 2.x.x) and Vue 3 (version 3.x.x).

```bash
# for vue2
npm install vue-web-terminal@2

# for vue3
npm install vue-web-terminal@3

```

--------------------------------

### Install vue-web-terminal using yarn

Source: https://tzfun.github.io/vue-web-terminal/getting-started

Installs the vue-web-terminal plugin using yarn. Supports both Vue 2 (version 2.x.x) and Vue 3 (version 3.x.x).

```bash
# for vue2
yarn add vue-web-terminal@2

# for vue3
yarn add vue-web-terminal@3

```

--------------------------------

### Command Example Usage

Source: https://tzfun.github.io/vue-web-terminal/zh/others

An example of a command with its description and the command string.

```json
{
    "des": "获取所有任务信息",
    "cmd": "task -o pack"
  }

```

--------------------------------

### Command Example Definition

Source: https://tzfun.github.io/vue-web-terminal/zh/others

Defines the structure for command examples, including a description and the command string.

```typescript
type CommandExample = {
    des?: string,
    cmd?: string
}

```

--------------------------------

### Table Message Example

Source: https://tzfun.github.io/vue-web-terminal/zh/others

An example of a 'table' type message, where content is structured as a table with headers and rows.

```json
{
  "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"
      ]
    ]
  }
}

```

--------------------------------

### Install vue-web-terminal with npm

Source: https://tzfun.github.io/vue-web-terminal/zh/getting-started

Install the vue-web-terminal plugin using npm. Specify version '2' for Vue 2 compatibility and version '3' for Vue 3 compatibility.

```bash
# for vue2
npm install vue-web-terminal@2

# for vue3
npm install vue-web-terminal@3
```

--------------------------------

### Install vue-web-terminal with pnpm

Source: https://tzfun.github.io/vue-web-terminal/zh/getting-started

Install the vue-web-terminal plugin using pnpm. Specify version '2' for Vue 2 compatibility and version '3' for Vue 3 compatibility.

```bash
# for vue2
pnpm install vue-web-terminal@2

# for vue3
pnpm install vue-web-terminal@3
```

--------------------------------

### Code Message Example

Source: https://tzfun.github.io/vue-web-terminal/zh/others

An example of a 'code' type message, used for displaying code snippets or multi-line text with syntax highlighting.

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

```

--------------------------------

### Install vue-web-terminal with yarn

Source: https://tzfun.github.io/vue-web-terminal/zh/getting-started

Install the vue-web-terminal plugin using yarn. Specify version '2' for Vue 2 compatibility and version '3' for Vue 3 compatibility.

```bash
# for vue2
yarn add vue-web-terminal@2

# for vue3
yarn add vue-web-terminal@3
```

--------------------------------

### Using the 'open' command in Vue Web Terminal

Source: https://tzfun.github.io/vue-web-terminal/zh/others

Explains how to use the 'open' command to launch web pages directly from the terminal. Examples include opening a blog and a GitHub profile.

```shell
# 打开谷歌
open www.google.com

# 打开作者GitHub主页
open https://github.com/tzfun
```

--------------------------------

### Shell: Help Command Usage

Source: https://tzfun.github.io/vue-web-terminal/others

Examples demonstrating how to use the built-in 'help' command to view command documentation, including exact matches, fuzzy searches, and group filtering.

```shell
# Show all command information
help

# Fuzzy search command, search for commands with the build prefix
help build*

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

# Search by group. The search keyword needs to start with ":" to search for all commands grouped as server
help :server
```

--------------------------------

### Normal Message Example

Source: https://tzfun.github.io/vue-web-terminal/zh/others

An example of a 'normal' type message, which is plain text and can include HTML tags and styling classes.

```json
{
  "type": "normal",
  "content": "This is a text message",
  "class": "success",
  "tag": "Tag success"
}

```

--------------------------------

### Shell: Open Command Usage

Source: https://tzfun.github.io/vue-web-terminal/others

Examples illustrating the use of the 'open' command to navigate to web addresses directly from the terminal.

```shell
# Open Google
open www.google.com

# Open the author's GitHub homepage
open https://github.com/tzfun
```

--------------------------------

### JSON Message Example

Source: https://tzfun.github.io/vue-web-terminal/zh/others

An example of a 'json' type message, where the content is a JSON object to be displayed in a JSON viewer.

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

```

--------------------------------

### HTML Message Example

Source: https://tzfun.github.io/vue-web-terminal/zh/others

Example of using the 'html' message type to render custom HTML content within the terminal.

```typescript
import { SuccessFunc } from "vue-web-terminal";

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

```

--------------------------------

### HTML Message Example (JavaScript)

Source: https://tzfun.github.io/vue-web-terminal/others

An example of an 'html' type message using a JavaScript function. The content is an HTML string that will be rendered as a block-level element.

```javascript
import {SuccessFunc} from "vue-web-terminal";

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

```

--------------------------------

### ANSI Message Example

Source: https://tzfun.github.io/vue-web-terminal/zh/others

Example of using the 'ansi' message type to display text with ANSI color codes.

```typescript
import { SuccessFunc } from "vue-web-terminal";

function execCmd(key: string, command: string, success: SuccessFunc) {
    // ...
    success({
        type: 'ansi',
        content: '\x1B[1;34mThis are some blue text.\x1B[0m\n\x1B[30;43mThis is a line of text with a background color.\x1B[0m\n\x1B[92;5mThis is blink text.\x1B[0m'
    })
    // ...
}

```

--------------------------------

### Vue Web Terminal Built-in Commands (JSON)

Source: https://tzfun.github.io/vue-web-terminal/zh/others

This JSON array describes the built-in commands 'help', 'clear', and 'open'. Each command object includes its key, title, group, usage, description, and examples.

```json
[
  {
    "key": "help",
    "title": "Help",
    "group": "local",
    "usage": "help [pattern]",
    "description": "Show command document.",
    "example": [
      {
        "des": "Get help documentation for exact match commands.",
        "cmd": "help open"
      },
      {
        "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"
      }
    ]
  }
]
```

--------------------------------

### Shell: Clear Command Usage

Source: https://tzfun.github.io/vue-web-terminal/others

Examples showing how to use the 'clear' command to manage terminal output, including clearing the current screen and clearing command history.

```shell
# Clear current screen record
clear

# Clear command history
clear history
```

--------------------------------

### Configure custom theme in Vue 3

Source: https://tzfun.github.io/vue-web-terminal/getting-started

Configures a custom theme for the terminal in Vue 3 (version 3.4.0+). It requires importing the CSS content and using `configTheme` before calling `app.use()`.

```javascript
//  Export css file content
import customTheme from '/your-style-dir/terminal-custom-theme1.css?inline';

const terminal: VueWebTerminal = createTerminal()
terminal.configTheme('my-custom-theme', customTheme)

app.use(terminal)

```

--------------------------------

### Register vue-web-terminal in Vue 2

Source: https://tzfun.github.io/vue-web-terminal/getting-started

Registers the vue-web-terminal plugin globally in a Vue 2 application. Requires importing `Terminal` from 'vue-web-terminal'.

```javascript
import Terminal from 'vue-web-terminal'

Vue.use(Terminal)

```

--------------------------------

### Register vue-web-terminal in Vue 3

Source: https://tzfun.github.io/vue-web-terminal/getting-started

Registers the vue-web-terminal plugin globally in a Vue 3 application. Requires importing `createTerminal` from 'vue-web-terminal'.

```javascript
import { createTerminal } from 'vue-web-terminal'

const app = createApp(App)

app.use(createTerminal())

app.mount('#app')

```

--------------------------------

### Configure max stored commands in Vue 3

Source: https://tzfun.github.io/vue-web-terminal/getting-started

Configures the maximum number of historical commands to be memorized per terminal instance in Vue 3 (version 3.4.0+). The default is 100. This must be done before calling `app.use()`.

```javascript
const terminal: VueWebTerminal = createTerminal()
//  default is 100
terminal.configMaxStoredCommandCountPerInstance(200)

app.use(terminal)

```

--------------------------------

### ANSI Message Example (JavaScript)

Source: https://tzfun.github.io/vue-web-terminal/others

An example of an 'ansi' type message using a JavaScript function. The content is a string with ANSI escape codes for styling, primarily supporting xterm-256color.

```javascript
import {SuccessFunc} from "vue-web-terminal";

function execCmd(key: string, command: string, success: SuccessFunc) {
    // ...
    success({
        type: 'ansi',
        content: '\x1B[1;34mThis are some blue text.\x1B[0m\n\x1B[30;43mThis is a line of text with a background color.\x1B[0m\n\x1B[92;5mThis is blink text.\x1B[0m'
    })
    // ...
}

```

--------------------------------

### Get Command API

Source: https://tzfun.github.io/vue-web-terminal/api

Retrieves the command currently being entered in the terminal.

```APIDOC
## GET /api/terminal/getCommand

### Description
Get the command currently being entered.

### Method
GET

### Endpoint
/api/terminal/getCommand

### Parameters
#### Query Parameters
- **terminalId** (string) - Required - The identifier of the terminal.

### Request Example
```json
{
  "terminalId": "my-terminal"
}
```

### Response
#### Success Response (200)
- **command** (string) - The current command entered.

#### Response Example
```json
{
  "command": "customCmd -a hello"
}
```
```

--------------------------------

### Configure terminal storage name in Vue 3

Source: https://tzfun.github.io/vue-web-terminal/getting-started

Configures the local storage name for the terminal instance in Vue 3 (version 3.4.0+). The default name is 'terminal'. This must be done before calling `app.use()`.

```javascript
const terminal: VueWebTerminal = createTerminal()
//  default is 'terminal'
terminal.configStoreName('my-terminal-storage')

app.use(terminal)

```

--------------------------------

### Get Current Command (JavaScript)

Source: https://tzfun.github.io/vue-web-terminal/api

Retrieves the command that is currently being entered by the user in the terminal.

```javascript
type getCommand = () => string;

TerminalApi.getCommand('my-terminal')
```

--------------------------------

### Get Terminal Outputs

Source: https://tzfun.github.io/vue-web-terminal/zh/api

Retrieves all outputs currently displayed on the terminal screen. The outputs are returned as a structured object, providing programmatic access to the terminal's content.

```typescript
type getOutputs = (name: string) => MessageGroup[];
```

```javascript
const outputs = TerminalApi.getOutputs('my-terminal')
```

--------------------------------

### Customizing Text Editor with Slots and Shortcut Keys in Vue

Source: https://tzfun.github.io/vue-web-terminal/functions

Provides a complete Vue component example showing how to open a text editor, customize its appearance using a `<textarea>` within the `#textEditor` slot, and implement a 'Ctrl + S' shortcut to save and close the editor. It utilizes Vue's reactivity and event handling.

```vue
<script setup lang="ts">
  import {SuccessFunc, FailedFunc, TerminalApi} from "vue-web-terminal";
  import {ref} from "vue";

  const name = ref<string>("my-terminal")
  const enableTextEditor = ref<boolean>(false)
  const onExecCmd = (key: string, command: string, success: SuccessFunc, failed: FailedFunc) => {
    if (key === 'edit') {
      TerminalApi.textEditorOpen(name.value, {
        content: 'Please edit this file',
        onClose: (value) => {
          enableTextEditor.value = false
          success({
            type: "code",
            content: value
          })
        }
      })
      enableTextEditor.value = true
    }
  }

  const onKeydown = (event: Event) => {
    if (enableTextEditor.value && event.key === 's' && event.ctrlKey) {
      _textEditorClose(true)
      event.preventDefault()
    }
  }

  const _textEditorClose = (option: boolean) => {
    TerminalApi.textEditorClose(name.value, option)
  }
</script>

<template>
  <terminal :name="name" @exec-cmd="onExecCmd" @on-keydown="onKeydown">
    <template #textEditor="{ data }">
      <textarea name="editor"
                class="t-text-editor"
                v-model="data.value"
                @focus="data.onFocus"
                @blur="data.onBlur"></textarea>

      <div class="t-text-editor-floor" align="center">
        <button class="t-text-editor-floor-btn" @click="_textEditorClose(false)">Cancel</button>
        <button class="t-text-editor-floor-btn" @click="_textEditorClose(true)">Save & Close</button>
      </div>

    </template>
  </terminal>
</template>
```

--------------------------------

### Pushing Various Message Types with TerminalApi

Source: https://tzfun.github.io/vue-web-terminal/api

Provides examples of using the TerminalApi.pushMessage method to send different types of messages: a simple text message, a structured warning message, and an array of multiple messages with different styles.

```javascript
//  Push a text message
TerminalApi.pushMessage('my-terminal', 'Hello world!')

//  push a message
TerminalApi.pushMessage('my-terminal', {
    class: 'warning',
    tag: 'WARN',
    content: 'This is warning message!'
})

//  Push multiple messages
TerminalApi.pushMessage('my-terminal', [
    {content: 'message 1'},
    {content: 'message 2', class: 'info'},
    {content: 'message 3', class: 'success'},
])

```

--------------------------------

### Dynamically Change Terminal Theme in Vue

Source: https://tzfun.github.io/vue-web-terminal/theme

This Vue script setup code shows how to dynamically change the terminal's theme by using a `ref` for the theme variable and toggling between 'dark' and 'light' themes. The template binds the `theme` prop to this reactive variable.

```javascript
<script setup lang="ts">
  import { ref } from 'vue';

  const theme = ref('dark')

  //  Modify the current window theme
  const changeTheme = () => {
    if (theme.value === 'dark') {
      theme.value = 'light'
    } else {
      theme.value = 'dark'
    }
  }
</script>
<template>
  <terminal name='my-terminal' :theme='theme'></terminal>
</template>


```

--------------------------------

### Get Current Command Input

Source: https://tzfun.github.io/vue-web-terminal/zh/api

Retrieves the command currently being entered by the user in the terminal. This is useful for real-time command processing or manipulation.

```typescript
type getCommand = () => string;
```

```javascript
TerminalApi.getCommand('my-terminal')
```

--------------------------------

### Configure Custom Themes in Vue 2

Source: https://tzfun.github.io/vue-web-terminal/theme

This Vue 2 code snippet illustrates how to import custom CSS theme files using `raw-loader` and register them with the vue-web-terminal plugin via `configTheme`. It also shows how to install the `Terminal` plugin and use custom themes in the application's template.

```javascript
import {Terminal, configTheme} from 'vue-web-terminal';

//  Export css file content to variables
import customTheme1 from '!!raw-loader!/your-style-dir/terminal-custom-theme1.css';
import customTheme2 from '!!raw-loader!/your-style-dir/terminal-custom-theme2.css';

configTheme('customTheme1', customTheme1);
configTheme('customTheme2', customTheme2);

Vue.use(Terminal);


```

--------------------------------

### Override Default Themes in Vue 3

Source: https://tzfun.github.io/vue-web-terminal/theme

This Vue 3 example demonstrates how to override the default 'dark' and 'light' themes by using `configTheme` with the theme names 'dark' and 'light' respectively, and providing custom CSS content.

```javascript
terminal.configTheme('dark', customTheme1);
terminal.configTheme('light', customTheme2);


```

--------------------------------

### Get Terminal Window DOM Information (JavaScript)

Source: https://tzfun.github.io/vue-web-terminal/api

Retrieves DOM information for the terminal window, including dimensions, content size, position, and character width. Note that this information might be invalid if the window is not yet displayed.

```javascript
type elementInfo = () => TerminalElementInfo;

let info = TerminalApi.elementInfo('my-terminal')
console.log(info)
```

--------------------------------

### Vue-Web-Terminal Custom Text Editor Slot

Source: https://tzfun.github.io/vue-web-terminal/slots

Provides an example of customizing the text editor interface in Vue-Web-Terminal using the '#textEditor' slot. This allows for custom input fields and buttons, including 'Cancel' and 'Save & Close' functionality.

```html
<terminal :name="name" @exec-cmd="onExecCmd">
    <!--  Customize text editor style  -->
    <template #textEditor="{data}">
        <textarea name="editor" 
                  class="t-text-editor" 
                  v-model="data.value" 
                  @focus="data.onFocus" 
                  @blur="data.onBlur"></textarea>
        <div class="t-text-editor-floor" align="center">
            <button class="t-text-editor-floor-btn" @click="_textEditorClose(false)">Cancel</button>
            <button class="t-text-editor-floor-btn" @click="_textEditorClose(true)">Save & Close(Ctrl + S)</button>
        </div>
    </template>
</terminal>
```

--------------------------------

### Get Terminal Input Focus (JavaScript)

Source: https://tzfun.github.io/vue-web-terminal/api

Obtains input focus for the terminal. Can forcibly acquire focus or just cursor focus to trigger the on-active event. Also handles focus for user input and text editor modes.

```javascript
type focus = (enforceFocus?: boolean | MouseEvent) => void;

TerminalApi.focus('my-terminal', true)
```

--------------------------------

### Using the 'help' command in Vue Web Terminal

Source: https://tzfun.github.io/vue-web-terminal/zh/others

Demonstrates how to use the 'help' command to display command documentation. It covers exact matches, fuzzy matching using wildcards, and searching by command group.

```shell
# 显示全部命令信息
help

# 模糊搜索命令，搜索build前缀的命令
help build*

# 模糊搜索名，搜索带有event的命令
help *event*

# 按分组搜索，搜索关键词需要以":"开头，搜索分组为server的所有命令
help :server
```

--------------------------------

### InputTipsItem Type Definition

Source: https://tzfun.github.io/vue-web-terminal/zh/others

Defines an item for input tips, including content, an optional description, and an associated command.

```typescript
type InputTipItem = {
    content: string,
    description?: string,
    command?: Command
}

```

--------------------------------

### TypeScript: InputTipItem Type Definition

Source: https://tzfun.github.io/vue-web-terminal/others

Defines the structure for input suggestions, including content, an optional description, and an optional associated command.

```typescript
type InputTipItem = {
    content: string,
    description?: string,
    command?: Command
}
```

--------------------------------

### Executing Commands in Terminal with TerminalApi

Source: https://tzfun.github.io/vue-web-terminal/api

Shows how to simulate a user executing a command in the terminal using TerminalApi.execute, which also echoes the command execution process.

```javascript
TerminalApi.execute('my-terminal', 'help :local')

```

--------------------------------

### Configure custom theme for Vue 3

Source: https://tzfun.github.io/vue-web-terminal/zh/getting-started

Configure a custom theme for the terminal in Vue 3 by providing a theme name and the CSS content. This must be done before registering the plugin.

```javascript
//  Export CSS file content
import customTheme from '/your-style-dir/terminal-custom-theme1.css?inline';

const terminal: VueWebTerminal = createTerminal()
terminal.configTheme('my-custom-theme', customTheme)

app.use(terminal)
```

--------------------------------

### Handle User Input with TerminalAsk

Source: https://tzfun.github.io/vue-web-terminal/functions

Illustrates how to use `TerminalAsk` to prompt users for input. The `success` callback in `exec-cmd` receives a `TerminalAsk` object with an `ask` method for questions, password input, and callbacks.

```javascript
import {FailedFunc, SuccessFunc, TerminalAsk} from 'vue-web-terminal'

const onExecCmd = (key: string, command: string, success: SuccessFunc, failed: FailedFunc) => {
    let asker = new TerminalAsk()
    success(asker)

    asker.ask({
        question: 'Please input github username: ',
        autoReview: true,
        callback: value => {
            console.log(value)
            asker.ask({
                question: 'Please input github password: ',
                autoReview: true,
                isPassword: true,
                callback: () => {
                    //    do something
                    asker.finish()
                }
            })
        }
    })
}

```

--------------------------------

### Configure max stored commands per instance for Vue 3

Source: https://tzfun.github.io/vue-web-terminal/zh/getting-started

Configure the maximum number of historical commands to store for each terminal instance in Vue 3. This must be done before registering the plugin.

```javascript
const terminal: VueWebTerminal = createTerminal()
//  default is 100
terminal.configMaxStoredCommandCountPerInstance(200)

app.use(terminal)
```

--------------------------------

### Command Type Definition

Source: https://tzfun.github.io/vue-web-terminal/zh/others

Defines the structure for commands used in the help and command search features.

```typescript
type Command = {
    key: string;
    title?: string;
    group?: string;
    usage?: string;
    description?: string;
    example?: Array<CommandExample>;
};

```

--------------------------------

### Register vue-web-terminal in Vue 2

Source: https://tzfun.github.io/vue-web-terminal/zh/getting-started

Register the vue-web-terminal plugin in your Vue 2 application's main entry file.

```javascript
import Terminal from 'vue-web-terminal'

Vue.use(Terminal)
```

--------------------------------

### Using the 'clear' command in Vue Web Terminal

Source: https://tzfun.github.io/vue-web-terminal/zh/others

Illustrates the usage of the 'clear' command to manage terminal output. It shows how to clear the current screen's records and how to clear the command history.

```shell
# 清除当前屏幕记录
clear

# 清除命令历史记录
clear history
```

--------------------------------

### Register vue-web-terminal in Vue 3

Source: https://tzfun.github.io/vue-web-terminal/zh/getting-started

Register the vue-web-terminal plugin in your Vue 3 application's main entry file.

```javascript
import { createTerminal } from 'vue-web-terminal'

const app = createApp(App)

app.use(createTerminal())

app.mount('#app')
```

--------------------------------

### Plugin Initialization Hooks (init-before, init-complete)

Source: https://tzfun.github.io/vue-web-terminal/zh/events

These events are part of the plugin's lifecycle. init-before is triggered before the plugin is initialized, and init-complete is triggered after initialization is finished.

```javascript
terminal.on('init-before', (name) => {
  console.log(`Plugin initialization starting for terminal: ${name}`);
});

terminal.on('init-complete', (name) => {
  console.log(`Plugin initialization complete for terminal: ${name}`);
});
```

--------------------------------

### Text Editor Open API

Source: https://tzfun.github.io/vue-web-terminal/api

Opens the text editor with optional initial content and a close event callback.

```APIDOC
## POST /api/terminal/textEditorOpen

### Description
Open the text editor. When opening, you can pass in the initial text content and define the close event callback. `content` is the preset content when opening the editor. If you don't want to preset any content, you can leave this parameter blank. When the user clicks Close or actively calls the `textEditorClose()` method, the `onClose` callback will be triggered. The parameter value is the text content in the current editor and the passed parameter options.

### Method
POST

### Endpoint
/api/terminal/textEditorOpen

### Parameters
#### Request Body
- **terminalId** (string) - Required - The identifier of the terminal.
- **setting** (object) - Required - Settings for the text editor.
  - **content** (string) - Optional - The initial content for the editor.
  - **onClose** (function) - Optional - Callback function triggered when the editor is closed. Receives current content and options as parameters.

### Request Example
```json
{
  "terminalId": "my-terminal",
  "setting": {
    "content": "This is the preset content",
    "onClose": "(value, options) => { console.log('Final content: ', value, 'options:', options) }"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success status.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Execute Command API

Source: https://tzfun.github.io/vue-web-terminal/api

Executes a command within the terminal, simulating user input and displaying the execution process.

```APIDOC
## POST /api/terminal/{name}/execute

### Description
Execute a command to the terminal.

### Method
POST

### Endpoint
`/api/terminal/{name}/execute`

### Parameters
#### Path Parameters
- **name** (string) - Required - The unique name of the terminal instance.

#### Request Body
- **cmd** (string) - Required - The command to execute.

### Request Example
```json
{
  "cmd": "help :local"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "Command executed successfully"
}
```
```

--------------------------------

### Enable Drag and Drop Functionality in Terminal

Source: https://tzfun.github.io/vue-web-terminal/functions

Demonstrates how to enable the drag-and-drop feature for the terminal window. This requires setting `show-header` to true and configuring `drag-conf` with parameters like width, height, initial position, and pinned status.

```html
<terminal name="my-terminal"
          show-header
          :drag-conf="{width: 700, height: 500, init:{ x: 50, y: 50 }, pinned: false}">
</terminal>

```

--------------------------------

### Terminal Focus API

Source: https://tzfun.github.io/vue-web-terminal/api

Manages input focus for the terminal, supporting command line, ask, and text editor modes.

```APIDOC
## POST /api/terminal/focus

### Description
Get the terminal input focus. There are three input points in the plugin: 
* For command line input, passing true to the focus method means forcibly obtaining the input focus. Otherwise, it only obtains the cursor focus and causes the terminal to trigger the on-active event.
* Ask user input, get the corresponding input focus when in ask mode.
* Text editor input, when in text editing mode, get the corresponding input box focus. If you use slot to customize the implementation, you need to provide the entry of focus event in the slot.

### Method
POST

### Endpoint
/api/terminal/focus

### Parameters
#### Query Parameters
- **enforceFocus** (boolean | MouseEvent) - Optional - Indicates whether to forcibly obtain input focus.

### Request Example
```json
{
  "terminalId": "my-terminal",
  "enforceFocus": true
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success status.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Implement Real-time Echo with TerminalFlash

Source: https://tzfun.github.io/vue-web-terminal/functions

Shows how to use `TerminalFlash` for real-time content updates within the terminal. The `success` callback in `exec-cmd` receives a `TerminalFlash` object with `flush` and `finish` methods to manage dynamic output.

```javascript
import {FailedFunc, SuccessFunc, TerminalFlash} from 'vue-web-terminal'

const onExecCmd = (key: string, command: string, success: SuccessFunc, failed: FailedFunc) => {

  let flash = new TerminalFlash()
  success(flash)

  let count = 0
  let flashInterval = setInterval(() => {
    flash.flush(`This is flash content: ${count}`)

    if (++count >= 20) {
      clearInterval(flashInterval)
      flash.finish()
    }
  }, 200)

}

```

--------------------------------

### Vue Event Naming Convention (Vue-web-terminal)

Source: https://tzfun.github.io/vue-web-terminal/questions

This snippet explains the recommended event naming convention for the vue-web-terminal plugin. It advises using kebab-case instead of camelCase for emitting events to ensure compatibility and consistent code style with Vue versions.

```html
<template>
  <WebTerminal @exec-cmd="handleExecCmd" />
</template>

<script>
import WebTerminal from 'vue-web-terminal';

export default {
  components: {
    WebTerminal
  },
  methods: {
    handleExecCmd(command) {
      console.log('Command executed:', command);
    }
  }
};
</script>
```

--------------------------------

### Switch All Fold State API

Source: https://tzfun.github.io/vue-web-terminal/api

Collapses or expands all command groups within the terminal.

```APIDOC
## POST /api/terminal/switchAllFoldState

### Description
Collapse or expand all command groups.

### Method
POST

### Endpoint
/api/terminal/switchAllFoldState

### Parameters
#### Request Body
- **terminalId** (string) - Required - The identifier of the terminal.
- **state** (boolean) - Required - `true` to collapse, `false` to expand.

### Request Example
```json
{
  "terminalId": "my-terminal",
  "state": true
}
```

### Response
#### Success Response (200)
- **count** (number) - The number of command groups affected.

#### Response Example
```json
{
  "count": 5
}
```
```

--------------------------------

### Customize Input Tips Search Handling (TypeScript)

Source: https://tzfun.github.io/vue-web-terminal/attributes

Defines a function type for customizing how search prompts are processed when a user types. It takes the current command, cursor position, command store, and a callback function to display the tips.

```typescript
/**
 * Implementation of user-defined command search prompt
 *
 * @param command       The complete command line entered by the current user
 * @param cursorIndex   Current cursor position
 * @param commandStore  Command collection
 * @param callback      Search end callback, the callback format is an array
 */
type InputTipsSearchHandlerFunc = (command: string, cursorIndex: number, commandStore: Command[], callback: (tips: InputTipItem[], openTips?: boolean) => void) => void
```

--------------------------------

### Open Text Editor (JavaScript)

Source: https://tzfun.github.io/vue-web-terminal/api

Opens a text editor with optional initial content and a callback for when the editor is closed. The callback receives the final content and any options passed during closure.

```javascript
type textEditorOpen = (setting: EditorSetting) => any;

TerminalApi.textEditorOpen('my-terminal', {
    content: 'This is the preset content',
    onClose: (value, options) => {
        console.log('Final content: ', value, "options:", options)
    }
})
```

--------------------------------

### Jump to Bottom API

Source: https://tzfun.github.io/vue-web-terminal/api

Scrolls the terminal window to the bottom.

```APIDOC
## POST /api/terminal/jumpToBottom

### Description
Jump to the bottom of the window.

### Method
POST

### Endpoint
/api/terminal/jumpToBottom

### Parameters
#### Request Body
- **terminalId** (string) - Required - The identifier of the terminal.
- **force** (boolean) - Required - If true, forces the jump to the bottom, even if the latest line is far from the visible area.

### Request Example
```json
{
  "terminalId": "my-terminal",
  "force": true
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success status.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Dragging Terminal Window with TerminalApi

Source: https://tzfun.github.io/vue-web-terminal/api

Demonstrates how to reposition the terminal window when dragging is enabled using TerminalApi.dragging, specifying the x and y coordinates.

```javascript
TerminalApi.dragging('my-terminal', { x: 100, y: 200 })

```

--------------------------------

### Push Message API

Source: https://tzfun.github.io/vue-web-terminal/api

Allows pushing single or multiple messages to a terminal instance. Messages can be plain strings or structured objects with styling and tags.

```APIDOC
## POST /api/terminal/{name}/message

### Description
Push one or more messages to the terminal.

### Method
POST

### Endpoint
`/api/terminal/{name}/message`

### Parameters
#### Path Parameters
- **name** (string) - Required - The unique name of the terminal instance.

#### Request Body
- **message** (string | object | array) - Required - The message content. Can be a single string, a message object, or an array of messages.

### Request Example
```json
{
  "message": "hello world!"
}
```
```json
{
  "message": {
    "class": "warning",
    "tag": "WARN",
    "content": "This is warning message!"
  }
}
```
```json
{
  "message": [
    {"content": "message 1"},
    {"content": "message 2", "class": "info"},
    {"content": "message 3", "class": "success"}
  ]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "Message pushed successfully"
}
```
```

--------------------------------

### Ref Call to pushMessage in Vue 3

Source: https://tzfun.github.io/vue-web-terminal/api

Shows how to push a message to a terminal instance in Vue 3 using a ref. It involves importing the Terminal component, creating a ref, and then calling pushMessage on the ref's value.

```javascript
import {onMounted, ref} from "vue";
import {Terminal} from 'vue-web-terminal'

const myTerminalRef = ref<InstanceType<typeof Terminal>>()

onMounted(() => {
  myTerminalRef.value!.pushMessage("hello world!")
})

```

--------------------------------

### Toggling Fullscreen Mode with TerminalApi

Source: https://tzfun.github.io/vue-web-terminal/api

Shows how to use TerminalApi.fullscreen to toggle the terminal window's fullscreen mode.

```javascript
TerminalApi.fullscreen('my-terminal')

```

--------------------------------

### Global Call to pushMessage in Vue

Source: https://tzfun.github.io/vue-web-terminal/api

Demonstrates how to use the global TerminalApi to push a message to a terminal instance in a Vue 3 application. It requires importing TerminalApi and calling pushMessage with the terminal's name and the message content.

```javascript
import {TerminalApi} from 'vue-web-terminal';
import {onMounted} from "vue";

onMounted(() => {
  TerminalApi.pushMessage('my-terminal', "hello world!")
})

```

--------------------------------

### Using Light Theme in Vue Web Terminal

Source: https://tzfun.github.io/vue-web-terminal/zh/theme

This snippet shows how to apply the built-in light theme to the terminal by setting the 'theme' attribute to 'light'.

```html
<template>
    <terminal name='my-terminal' theme='light'></terminal>
</template>

```

--------------------------------

### EditorSetting Type Definition

Source: https://tzfun.github.io/vue-web-terminal/zh/others

Settings for an editor component, including its content and a close callback function.

```typescript
type EditorSetting = {
    content: string,
    onClose: Function,
}

```

--------------------------------

### Open and Close Text Editor using Vue Web Terminal API

Source: https://tzfun.github.io/vue-web-terminal/functions

Demonstrates the basic usage of `textEditorOpen` to initiate the text editor and `textEditorClose` to conclude the editing session. The `onClose` callback provides the edited content.

```typescript
const onExecCmd = (key: string, command: string, success: SuccessFunc, failed: FailedFunc) => {
    TerminalApi.textEditorOpen('my-terminal', {
        content: 'Please edit this file',
        onClose: (value, options) => {
            console.log("User editing is complete, text result:", value, "options:", options)
        }
    })
}

const closeEditor = () => {
    TerminalApi.textEditorClose('my-terminal', { fromUser: false })
}
```

--------------------------------

### Vue-Web-Terminal Custom Help Box Slot

Source: https://tzfun.github.io/vue-web-terminal/slots

Illustrates customization of the help prompt box in Vue-Web-Terminal via the '#helpBox' slot. It provides access to 'showHeader' and 'item' for rendering custom help prompts.

```html
<terminal :name="name" @exec-cmd="onExecCmd">
    <!--  Customize the help prompt box style  -->
    <template #helpBox="{showHeader, item}">
      {{ item }}
    </template>
</terminal>
```

--------------------------------

### DragConfig Type Definition

Source: https://tzfun.github.io/vue-web-terminal/zh/others

Configuration interface for draggable terminal elements, specifying dimensions, z-index, initial position, and pinning.

```typescript
type DragConfig = {
    width: string | number;
    height: string | number;
    zIndex?: string;
    init?: Position;
    pinned: boolean;
};

```

--------------------------------

### TypeScript: EditorSetting Type Definition

Source: https://tzfun.github.io/vue-web-terminal/others

Defines settings for an editor, including its content and a callback function to execute when the editor is closed.

```typescript
type EditorSetting = {
    content: string,
    onClose: Function,
}
```

--------------------------------

### TypeScript: DragConfig Type Definition

Source: https://tzfun.github.io/vue-web-terminal/others

Defines the configuration options for draggable elements, including width, height, z-index, initial position, and pinned state.

```typescript
type DragConfig = {
    width: string | number;
    height: string | number;
    zIndex?: string;
    init?: Position;
    pinned: boolean;
};
```

--------------------------------

### Vue Web Terminal: before-exec-cmd Event

Source: https://tzfun.github.io/vue-web-terminal/events

Fires after the user presses Enter but before the command is actually executed. It receives the command key, the command string, and the terminal instance name.

```TypeScript
emit('before-exec-cmd', commandKey, command, name);
```

--------------------------------

### Fullscreen Toggle API

Source: https://tzfun.github.io/vue-web-terminal/api

Toggles the terminal window between normal and fullscreen mode.

```APIDOC
## POST /api/terminal/{name}/fullscreen

### Description
Toggle full screen mode for the terminal.

### Method
POST

### Endpoint
`/api/terminal/{name}/fullscreen`

### Parameters
#### Path Parameters
- **name** (string) - Required - The unique name of the terminal instance.

### Request Example
```
POST /api/terminal/my-terminal/fullscreen
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "Fullscreen toggled successfully"
}
```
```

--------------------------------

### Terminal Element Information API

Source: https://tzfun.github.io/vue-web-terminal/api

Retrieves DOM information for the terminal window, including dimensions and character metrics.

```APIDOC
## GET /api/terminal/elementInfo

### Description
Get the Terminal window DOM information. You can use this API to get the Terminal window width and height, the width and height of the displayed content, the location, the width of a single character, etc. The unit is px.

**Notice**
If your window has been created but not displayed on the page (for example, if v-show is used to control the display), some information may become invalid.

### Method
GET

### Endpoint
/api/terminal/elementInfo

### Parameters
#### Query Parameters
- **terminalId** (string) - Required - The identifier of the terminal.

### Request Example
```json
{
  "terminalId": "my-terminal"
}
```

### Response
#### Success Response (200)
- **pos** (object) - The position of the terminal window.
  - **x** (number) - The x-coordinate.
  - **y** (number) - The y-coordinate.
- **screenWidth** (number) - The width of the terminal screen.
- **screenHeight** (number) - The height of the terminal screen.
- **clientWidth** (number) - The client width of the terminal.
- **clientHeight** (number) - The client height of the terminal.
- **charWidth** (object) - The width of characters.
  - **en** (number) - Width for English characters.
  - **cn** (number) - Width for Chinese characters.

#### Response Example
```json
{
  "pos": {
    "x": 100,
    "y": 100
  },
  "screenWidth": 700,
  "screenHeight": 500,
  "clientWidth": 690,
  "clientHeight": 490,
  "charWidth": {
    "en": 7.2,
    "cn": 14
  }
}
```
```

--------------------------------

### Configuring Custom Themes in Vue 2

Source: https://tzfun.github.io/vue-web-terminal/zh/theme

This JavaScript snippet demonstrates how to configure custom themes for the vue-web-terminal in a Vue 2 application using `configTheme` and `raw-loader` for importing CSS content.

```javascript
import {Terminal, configTheme} from 'vue-web-terminal';

//  导出css文件内容
import customTheme1 from '!!raw-loader!/your-style-dir/terminal-custom-theme1.css';
import customTheme2 from '!!raw-loader!/your-style-dir/terminal-custom-theme2.css';

configTheme('customTheme1', customTheme1);
configTheme('customTheme2', customTheme2);

Vue.use(Terminal);

```
Tokens:
Raw