自定义小组件
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:hidden | true 隐藏菜单/工具按钮/启动器条目。 |
icon | 图标名称,见下文。 |
svg | 兼容旧版的字段,当前添加面板菜单不使用。 |
color | 自定义工具按钮图标颜色。 |
label | 显示名称。 |
description | 说明/工具提示。 |
magnified | (可选)true 表示打开时直接处于放大状态。默认为 false。 |
blockdef | 必填。{ "meta": { ... } }——点击图标时创建的区块。其中 meta.view 决定小组件类型,meta 里其余的字段取决于这个类型(见下文)。 |
图标
建议填写 Font Awesome 名称(如 star、brands@github)或应用识别的图标名称。菜单/标签栏映射到应用图形,无法识别时按视图类型回退;启动器使用 Font Awesome 图标。color 为自定义工具按钮着色;label 是显示名称,description 可提供工具提示。
终端与命令类小组件

"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"——必填,没有默认值。 |
cmd | controller 为 "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
}
}
}
}
网页类小组件

"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。