battlefieldduck / xtermblazor Goto Github PK

View Code? Open in Web Editor NEW

38.0 2.0 8.0 3.89 MB

Blazor library that integrates the xterm.js terminal emulator into Blazor applications. Over 22,000 downloads.

Home Page: https://xtermblazor.pages.dev

License: MIT License

HTML 26.65% C# 56.92% CSS 5.00% JavaScript 2.03% TypeScript 9.40%

xterm xterm-js blazor blazor-server blazor-webassembly blazor-wasm xtermblazor

xtermblazor's Introduction

XtermBlazor

Brings xterm.js to Blazor

Live Demo: https://xtermblazor.pages.dev

Demo Projects

XtermBlazor.Demo.Server (Blazor Server)
XtermBlazor.Demo.Wasm (Blazor WebAssembly)

Prerequisites

Before you get started with this project, make sure you have the following software installed on your system:

.NET: You will need .NET 6.0 or later for this project.
Node.js: This project also requires Node.js version 18 or later.

Installation

1. Install the package

Find the package through NuGet Package Manager or install it with following command.

dotnet add package XtermBlazor

2. Add Imports

After the package is added, you need to add the following in your _Imports.razor

@using XtermBlazor

3. Add CSS & Font references

Add the following to your HTML head section, it's either index.html or _Host.cshtml depending on whether you're running WebAssembly or Server.

<link href="_content/XtermBlazor/XtermBlazor.min.css" rel="stylesheet" />

In the HTML body section of either index.html or _Host.cshtml add this:

<script src="_content/XtermBlazor/XtermBlazor.min.js"></script>

Basic Usage

<Xterm @ref="_terminal" Options="_options" OnFirstRender="@OnFirstRender" />

@code {
    private Xterm _terminal;

    private TerminalOptions _options = new TerminalOptions
    {
        CursorBlink = true,
        CursorStyle = CursorStyle.Bar,
        Theme =
        {
            Background = "#17615e",
        },
    };

    private async Task OnFirstRender()
    {
        await _terminal.WriteLine("Hello World");
    }
}

Addons

Xterm supports Addons

To use @xterm/addon-fit addon, you need to add the following to your HTML body section either index.html or _Host.cshtml.

Blazor WebAssembly index.html

<!-- Add addon-fit.min.js before blazor.webassembly.js and XtermBlazor.min.js -->
<script src="https://cdn.jsdelivr.net/npm/@xterm/[email protected]/lib/addon-fit.min.js"></script>

<script src="_framework/blazor.webassembly.js"></script>
<script>navigator.serviceWorker.register('service-worker.js');</script>

<!-- Load the XtermBlazor library and register addons -->
<script src="_content/XtermBlazor/XtermBlazor.min.js"></script>
<script>XtermBlazor.registerAddons({"addon-fit": new FitAddon.FitAddon()});</script>

Blazor Server _Host.cshtml

<!-- Add addon-fit.min.js before blazor.server.js and XtermBlazor.min.js -->
<script src="https://cdn.jsdelivr.net/npm/@@xterm/[email protected]/lib/addon-fit.min.js"></script>

<script src="_framework/blazor.server.js"></script>

<!-- Load the XtermBlazor library and register addons -->
<script src="_content/XtermBlazor/XtermBlazor.min.js"></script>
<script>XtermBlazor.registerAddons({"addon-fit": new FitAddon.FitAddon()});</script>

Usage with addons

<Xterm @ref="_terminal" Options="_options" Addons="_addons" OnFirstRender="@OnFirstRender" />

@code {
    private Xterm _terminal;

    private TerminalOptions _options = new TerminalOptions
    {
        CursorBlink = true,
        CursorStyle = CursorStyle.Bar,
    };

    private HashSet<string> _addons = new HashSet<string>()
    {
        "addon-fit",
    };

    private async Task OnFirstRender()
    {
        // Invoke fit() function
        await _terminal.Addon("addon-fit").InvokeVoidAsync("fit");

        await _terminal.WriteLine("Hello World");
    }
}

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

License

XtermBlazor is licensed under the MIT License. See the LICENSE file for more details.

Stargazers over time

xtermblazor's People

Contributors

Stargazers

Watchers

Forkers

jasona jingxi0109 huafangyun datutech petterrein fjsnogueira aaasoft hastaroth1

xtermblazor's Issues

customKeyEventHandler is not invoked properly

First of all, thank you for this package.

Describe the bug

When using the customKeyEventHandler to intercept keys, the KeyBoardEvent object is not passed as a parameter as expected. Instead is it passed as the this:

I believe the issue is that call expects the first parameter to be the this context but it is called only with the KeyboardEvent

https://github.com/BattlefieldDuck/XtermBlazor/blob/main/XtermBlazor/src/index.ts#L47

I'm not sure what the this object is when Xtermjs calls the handler directly, but it would make sense to me to pass the terminal as the this.

To Reproduce
Steps to reproduce the behavior:

Create a terminal
In OnFirstRender or some other lifecycle method, use terminal.SetCustomKeyEventHandler to set a custom key handler.
Type anything inside the terminal
The function called in SetCustomKeyEventHandler will have no param passed and instead the this object will contain the event information.

Expected behavior

The first function param should contain the KeyboardEvent object.

Desktop (please complete the following information):

OS: Windows
Browser: Edge (WebView2)
Version [e.g. 22

Ctrl+C doesn't work

Hi!

Are there any chances attachCustomKeyEventHandler will be implemented?

As for now all ctrl+cs are ignored.

Fit addon not updating the height

Hi,

Thank you for this awesome library!

I have been experiencing an issue where the xterm-addon-fit would not fill the full height of its parent container. I did some quick troubleshooting and it appears its due to the parent div not having a height: 100%.

My recommendation would be to set it to 100% or allow the parent div style to be configurable.

Before:

After:

AttachCustomKeyEventHandlerEvaluate

How does the "AttachCustomKeyEventHandlerEvaluate" function work? I have tried to deactivate a certain key. However, JS errors come up.
Example:
xterm.AttachCustomKeyEventHandlerEvaluate("(event) => event.keyCode != 38;");

I want to disable ArrowUp and ArrowDown so that they do not move the cursor up or down.

Running XtermBlazor on IOS

Hi
I am trying the XtermBlazor library to run on IOS and Android. I am able to launch a basic xterm on both, the Android xterm seems to be working fine, however when running on IOS and trying to type something on the xterm I get the following error for every character I type :

2022-10-24 08:43:50.420439-0400 TestBlazorApp[14028:354017] [UIFocus] Failed to update focus with context <UIFocusUpdateContext: 0x600002764640: previouslyFocusedItem=(null), nextFocusedItem=(null), focusHeading=None>. No additional info available.

Have you seen this error before ? is there is known workaround?

Thanks

Cannot register addon

I get the following error in the console:

Uncaught TypeError: Cannot read properties of undefined (reading 'FitAddon')

index.html file:

<script src="_content/XtermBlazor/XtermBlazor.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/lib/xterm-addon-fit.min.js"></script>
<script>
    window.XtermBlazor.registerAddon("xterm-addon-fit", new window.FitAddon.FitAddon()); // <- error is thrown here
</script>

Are there any ideas what is configured incorrectly?

I use .NET 7 Preview 7 + Self-hosted Blazor Web Assembly.

XtermBlazor for color

Whether the colors can be modified when the OnData method renders