trzsz.js文件傳輸工具

 trzsz ( trz / tsz ) 是一個(gè)兼容 tmux 的文件傳輸工具，和 lrzsz ( rz / sz ) 類似，并且有進(jìn)度條，支持目錄傳輸，支持拖動(dòng)上傳。

GitHub: https://github.com/trzsz/trzsz.js

有關(guān) trzsz 更詳細(xì)的文檔，請(qǐng)查看 https://trzsz.github.io/cn。

trzsz.js 是 trzsz 的 js 版實(shí)現(xiàn)，支持在瀏覽器中運(yùn)行的 webshell，支持用 electron 等實(shí)現(xiàn)的 js 語(yǔ)言的終端。

開(kāi)發(fā)指引

• 添加依賴

  npm install trzsz
  

  或者

  yarn add trzsz
  

• 在 Node.js 中引用

  import { TrzszFilter } from "trzsz";
  

  或者

  const { TrzszFilter } = require("trzsz");
  

• 或者在瀏覽器中引用

  <script src="node_modules/trzsz/lib/trzsz.js"></script>
  

• 創(chuàng)建 TrzszFilter 對(duì)象（ 每個(gè)登錄服務(wù)器的連接創(chuàng)建一個(gè)相應(yīng)的 ）

  const trzszFilter = new TrzszFilter({
    // 這里設(shè)置 trzsz 的屬性，詳情請(qǐng)參考下文。
  });
  

• 一般來(lái)說(shuō)，服務(wù)器的輸出會(huì)轉(zhuǎn)發(fā)到終端進(jìn)行顯示，創(chuàng)建 TrzszFilter 過(guò)濾器，接受服務(wù)器的輸出，并轉(zhuǎn)發(fā)給終端。

  const trzszFilter = new TrzszFilter({
    // 將服務(wù)器的輸出轉(zhuǎn)發(fā)給終端進(jìn)行顯示，當(dāng)用戶在服務(wù)器上執(zhí)行 trz / tsz 命令時(shí)，輸出則會(huì)被接管。
    writeToTerminal: (data) => terminal.write(typeof data === "string" ? data : new Uint8Array(data)),
  });
  
  // 將服務(wù)器的輸出轉(zhuǎn)發(fā)給 TrzszFilter 進(jìn)行處理，一般會(huì)原樣轉(zhuǎn)發(fā)回上面定義的 writeToTerminal 函數(shù)。
  webSocket.addEventListener("message", (ev) => trzszFilter.processServerOutput(ev.data));
  

• 一般來(lái)說(shuō)，用戶的輸入會(huì)轉(zhuǎn)發(fā)到服務(wù)器上，創(chuàng)建 TrzszFilter 過(guò)濾器，接受用戶的輸入，并轉(zhuǎn)發(fā)給服務(wù)器。

  const trzszFilter = new TrzszFilter({
    // 將用戶的輸入轉(zhuǎn)發(fā)到服務(wù)器上，當(dāng) trz / tsz 上傳或下載時(shí)，輸入則會(huì)被忽略，ctrl + c 會(huì)停止傳輸。
    sendToServer: (data) => webSocket.send(data),
  });
  
  // 將用戶的輸入轉(zhuǎn)發(fā)給 TrzszFilter 進(jìn)行處理，一般會(huì)原樣轉(zhuǎn)發(fā)回上面定義的 sendToServer 函數(shù)。
  terminal.onData((data) => trzszFilter.processTerminalInput(data));
  // 將用戶的鼠標(biāo)事件轉(zhuǎn)發(fā)給 TrzszFilter 進(jìn)行處理，一般會(huì)原樣轉(zhuǎn)發(fā)回上面定義的 sendToServer 函數(shù)。
  terminal.onBinary((data) => trzszFilter.processBinaryInput(data));
  

• 需要告知 TrzszFilter 終端的寬度，在顯示進(jìn)度條時(shí)會(huì)使用到。

  const trzszFilter = new TrzszFilter({
    // 終端的初始寬度
    terminalColumns: terminal.cols,
  });
  
  // 當(dāng)終端寬度發(fā)生變化時(shí)，告知 TrzszFilter 最新的寬度。
  terminal.onResize((size) => trzszFilter.setTerminalColumns(size.cols));
  

• 如果遠(yuǎn)程服務(wù)器是 Windows 命令行, 例如 cmd 和 PowerShell。

  const trzszFilter = new TrzszFilter({
    // 聲明遠(yuǎn)程服務(wù)器是 Windows 的 cmd / PowerShell 等
    isWindowsShell: true,
  });
  

• 如果是 Node.js 運(yùn)行環(huán)境，即能正常執(zhí)行 require('fs')，那么 chooseSendFiles and chooseSaveDirectory 是必須的。如果是瀏覽器運(yùn)行環(huán)境，則會(huì)忽略它們。注意是 async 函數(shù)。

  const trzszFilter = new TrzszFilter({
    // 當(dāng)用戶在服務(wù)器上執(zhí)行 trz 命令上傳文件時(shí)，require('fs') 不報(bào)錯(cuò)，則會(huì)回調(diào)此函數(shù)，選擇要上傳的文件。
    chooseSendFiles: async (directory) => {
      // 如果 `directory` 參數(shù)為 `true`，則應(yīng)該允許用戶選擇目錄和文件（ 多選 ）。
      // 如果 `directory` 參數(shù)為 `false`，則應(yīng)該只允許用戶選擇文件（ 多選 ）。
      // 返回 `undefined` 代表用戶取消選擇文件，終止上傳操作。
      // 正常應(yīng)該回一個(gè)數(shù)組，包含文件或目錄的絕對(duì)路徑，如下：
      return ["/path/to/file1", "/path/to/file2", "/path/to/directory3"];
    },
    // 當(dāng)用戶在服務(wù)器上執(zhí)行 tsz 命令下載文件時(shí)，require('fs') 不報(bào)錯(cuò)，則會(huì)回調(diào)此函數(shù)，選擇要保存的路徑。
    chooseSaveDirectory: async () => {
      // 返回 `undefined` 代表用戶取消選擇保存路徑，終止下載操作。
      // 正常應(yīng)該回一個(gè)目錄的絕對(duì)路徑，如下：
      return "/path/to/directory";
    },
  });
  

• 支持拖拽文件和目錄上傳的功能。

  terminalHtmlElement.addEventListener("dragover", (event) => event.preventDefault());
  terminalHtmlElement.addEventListener("drop", (event) => {
    event.preventDefault();
    trzszFilter
      .uploadFiles(event.dataTransfer.items)
      .then(() => console.log("upload success"))
      .catch((err) => console.log(err));
  });
  

• 如果你在使用 xterm-addon-attach 插件，只將簡(jiǎn)單地用 TrzszAddon 替換 AttachAddon 即可。

  import { Terminal } from "xterm";
  import { TrzszAddon } from "trzsz";
  
  const terminal = new Terminal();
  const trzszAddon = new TrzszAddon(webSocket);
  terminal.loadAddon(trzszAddon);
  

開(kāi)發(fā)示例

• 瀏覽器 webshell 例子。

• Electron 終端例子。

• TrzszAddon xterm 插件例子。

錄屏演示

js 版的 trzsz.js，可以在 Chrome 瀏覽器中使用 trzsz ( trz / tsz ) 上傳和下載文件，如圖：

js 版的 trzsz.js，可以集成到 electron 開(kāi)發(fā)的終端中，使用 trzsz ( trz / tsz ) 上傳和下載文件，如圖：