跳到主要内容

自定义小组件

widgets.json 定义添加面板菜单、自定义标签栏工具按钮与可搜索启动器中的条目。可以配置特定 shell、一次性命令、网页、监控或本机 Git 仓库。它不是安装第三方代码的扩展机制。

widgets.json 的位置​

可编辑文件位于配置目录,默认 ~/.config/termia/widgets.json(平台覆盖规则见配置)。右键标签栏的添加面板按钮,选择编辑 widgets.json,或运行 wsh editconfig widgets.json 打开。它与内置 Terminal/File/Web/Monitor/Git 条目合并;同 ID 覆盖内置值。

当前没有旧版左侧添加面板菜单。添加面板菜单把图标名称映射到应用图形;svg 是兼容旧配置字段,不控制当前菜单图形。启动器按自身规则显示图标。不要创建当前客户端不支持的 view 类型。

一条小组件配置的结构​

widgets.json 里的每一条都是一个 JSON 对象,键是你自己起的唯一 id(字母、数字、-、_、 @ 都可以,界面上不会显示这个 id)。它的值是这样的结构:

{
    "my-widget": {
        "icon": "star",
        "label": "My Widget",
        "color": "#ffd700",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "shell"
            }
        }
    }
}

外层的这些键(icon、label、color、blockdef,以及下面这些)对所有小组件都是一样的,与 类型无关:

键说明
display:order排序值;越小越靠前。默认 0。
display:hiddentrue 隐藏菜单/工具按钮/启动器条目。
icon图标名称,见下文。
svg兼容旧版的字段,当前添加面板菜单不使用。
color自定义工具按钮图标颜色。
label显示名称。
description说明/工具提示。
magnified(可选)true 表示打开时直接处于放大状态。默认为 false。
blockdef必填。{ "meta": { ... } }——点击图标时创建的区块。其中 meta.view 决定小组件类型,meta 里其余的字段取决于这个类型(见下文)。

图标​

建议填写 Font Awesome 名称(如 star、brands@github)或应用识别的图标名称。菜单/标签栏映射到应用图形,无法识别时按视图类型回退;启动器使用 Font Awesome 图标。color 为自定义工具按钮着色;label 是显示名称,description 可提供工具提示。

终端与命令类小组件​

配置后的小组件从启动入口打开面板,命令与视图由 widgets.json 决定。
配置后的小组件从启动入口打开面板,命令与视图由 widgets.json 决定。查看原图 ↗

"view": "term" 打开一个终端区块。controller 决定其中运行什么,且必须填写——没有默认值:

  • "controller": "shell" —— 一个常驻的可交互 Shell。
  • "controller": "cmd" —— 运行单条命令。该区块头部会出现状态/重启图标,右键头部还能看到强制 重启控制器。
{
    "my-widget": {
        "icon": "fa-solid fa-terminal",
        "label": "My Widget",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "cmd",
                "cmd": "<要运行的 CLI 命令>"
            }
        }
    }
}

终端类小组件在 blockdef.meta 下可用的字段:

键说明
view必须是 "term"。
controller"shell" 或 "cmd"——必填,没有默认值。
cmdcontroller 为 "cmd" 时要运行的命令。
cmd:shell(可选,布尔值)默认为**true**:cmd 会原样交给一个 Shell 去解释,因此可以包含空格、管道或重定向。设为 false 可以做到精确的参数级执行——此时 cmd 不能包含空格(把参数放进 cmd:args),应用会自动帮你做 Shell 转义。
cmd:args(可选,字符串数组)当 cmd:shell 为 false 时,追加在 cmd 后面的参数。
cmd:interactive(可选,布尔值)启动时加上交互模式标志。默认为 false。
cmd:login(可选,布尔值)启动时加上登录 Shell 标志。默认为 false。
cmd:runonstart(可选,布尔值)区块一创建就运行该命令。默认为 true。
cmd:runonce(可选,布尔值)效果类似 cmd:runonstart,但运行一次后会把 cmd:runonce 和 cmd:runonstart 都自动改成 false,之后手动重启才会再运行。
cmd:clearonstart(可选,布尔值)每次命令(重新)运行时清空区块内容。默认为 false。
cmd:closeonexit(可选,布尔值)命令以退出码 0 结束时自动关闭区块。
cmd:closeonexitforce(可选,布尔值)命令无论成功还是失败退出都自动关闭区块。
cmd:closeonexitdelay(可选,数字)关闭前等待的毫秒数。默认为 2000。
cmd:env(可选,对象)传给命令的额外环境变量。
cmd:cwd(可选,字符串)工作目录。仅本地连接有效。默认为你的主目录。
cmd:nowsh(可选,布尔值)为这条命令关闭 wsh 集成。默认为 false。
cmd:jwt(可选,布尔值)强制把一个 JWT 放进命令的环境变量。
cmd:initscript、cmd:initscript.sh、cmd:initscript.bash、cmd:initscript.zsh、cmd:initscript.pwsh、cmd:initscript.fish(可选,仅 controller: "shell")Shell 启动前要执行的脚本(可以是内联脚本,也可以是脚本文件的绝对路径);带后缀的变体只对对应的 Shell 生效。
term:localshellpath(可选)覆盖要启动的 Shell 可执行文件。仅本地连接有效;留空则使用系统默认 Shell。
term:localshellopts(可选)传给 term:localshellpath 的额外选项。仅本地连接有效。
connection(可选)让终端连到某个已保存的连接,而不是本机——见远程小组件。

示例:另一个本地 Shell​

{
    "fish": {
        "icon": "fa-solid fa-fish",
        "color": "#4abc39",
        "label": "fish",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "shell",
                "term:localshellpath": "/usr/local/bin/fish",
                "term:localshellopts": "-i -l"
            }
        }
    }
}

如果 fish 不在你的 PATH 里,给 term:localshellpath 一个完整路径(用 which fish 查找)。

远程小组件​

在任意终端、文件预览或 Git 小组件上加一个 "connection",就能让它指向某个已保存的连接,而不是 本机。使用 connections.json 里的规范名称,而不是你自定义的显示名——SSH 连接是 user@host,WSL 连接是 wsl://<发行版>:

{
    "remote-term": {
        "icon": "fa-solid fa-server",
        "label": "prod",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "shell",
                "connection": "user@prod-host"
            }
        }
    }
}

示例:一次性命令​

{
    "speedtest": {
        "icon": "fa-solid fa-gauge-high",
        "label": "speed",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "cmd",
                "cmd": "speedtest-go --unix",
                "cmd:clearonstart": true
            }
        }
    }
}

这个例子依赖 cmd:shell: true 这个默认值,所以命令行会照原样交给你的 Shell 解释。如果想用精确 的参数级执行方式(不经过 Shell 解析)运行同一条命令,可以这样写:

{
    "speedtest": {
        "icon": "fa-solid fa-gauge-high",
        "label": "speed",
        "blockdef": {
            "meta": {
                "view": "term",
                "controller": "cmd",
                "cmd": "speedtest-go",
                "cmd:shell": false,
                "cmd:args": ["--unix"],
                "cmd:clearonstart": true
            }
        }
    }
}

网页类小组件​

Web 小组件在面板内展示网页,不提供 SSH 命令执行语义。
Web 小组件在面板内展示网页,不提供 SSH 命令执行语义。查看原图 ↗

"view": "web" 打开一个内嵌浏览器,固定在某个起始页面。

{
    "youtube": {
        "icon": "brands@youtube",
        "label": "youtube",
        "blockdef": {
            "meta": {
                "view": "web",
                "url": "https://youtube.com",
                "pinnedurl": "https://youtube.com"
            }
        }
    }
}
键说明
view必须是 "web"。
url该小组件打开时显示的页面。省略时使用全局设置 web:defaulturl。
pinnedurl(可选)头部主页按钮返回的页面。省略时使用 web:defaulturl。

系统信息类小组件​

"view": "sysinfo" 打开针对该区块所连接主机的实时指标视图。

{
    "build-monitor": {
        "icon": "fa-solid fa-chart-line",
        "label": "build",
        "blockdef": {
            "meta": {
                "view": "sysinfo",
                "graph:numpoints": 180,
                "sysinfo:type": "CPU + Mem"
            }
        }
    }
}
键说明
view必须是 "sysinfo"。
sysinfo:type默认展示哪种图表。可选值为 CPU、Mem、CPU + Mem、All CPU(每个核心一条线)、Network、Disk、Process、Host,或 All(汇总以上全部指标的总览)。大小写敏感。省略时默认为 All。
graph:numpoints(可选)图表窗口覆盖多少个采样点(大致等于多少秒)。默认为 120。
connection(可选)让该小组件指向某个远程连接,而不是本机。

Git 类小组件​

"view": "gitstatus" 直接针对某个指定文件夹打开 Git 客户端,而不是提示你去选择一个。

{
    "myproject-git": {
        "icon": "fa-solid fa-code-branch",
        "label": "myproject",
        "blockdef": {
            "meta": {
                "view": "gitstatus",
                "git:repopath": "~/code/myproject"
            }
        }
    }
}
键说明
view必须是 "gitstatus"。
git:repopath要打开的本地文件夹。省略时,该小组件第一次打开时会提示你选择一个。

文件与帮助类小组件​

"view": "preview" 直接打开一个指定的文件或目录,而不是从你的主目录开始:

{
    "notes": {
        "icon": "fa-solid fa-note-sticky",
        "label": "notes",
        "blockdef": {
            "meta": {
                "view": "preview",
                "file": "~/notes.md"
            }
        }
    }
}

"view": "help" 会为内嵌的文档站点提供一个配置入口——当前版本默认没有为它提供入口,这就是 添加一个的办法:

{
    "help": {
        "icon": "fa-solid fa-circle-question",
        "label": "帮助",
        "blockdef": {
            "meta": {
                "view": "help"
            }
        }
    }
}

移除或隐藏内置小组件​

五个内置小组件在内部分别叫做 defwidget@terminal、defwidget@files、defwidget@web、 defwidget@sysinfo 和 defwidget@gitstatus。要把其中某一个从栏上移除,用这个确切的键新增一条 配置,并把它设为 null:

{
    "defwidget@web": null
}

如果想保留它在栏上,但修改它的图标、标签或行为,就给同一个键一个正常的小组件对象,而不是 null——你写的条目会完全替换掉那个内置小组件。如果只是想隐藏它但保留你的覆盖配置,给它加上 "display:hidden": true,而不要用 null。