YASB(Yet Another Status Bar)完全指南:Windows 高度可配置状态栏的安装、配置与深度定制
YASB(Yet Another Status Bar)完全指南:Windows 高度可配置状态栏的安装、配置与深度定制
YASB(Yet Another Status Bar)是一个用 Python 编写、面向 Windows 的高度可配置状态栏:它默认只占用屏幕顶部一条薄薄的区域,却可以通过 YAML 配置与 CSS 样式把系统监控、媒体控制、窗口管理器集成、AI 用量查询等数十种能力编排成你专属的桌面信息中枢。本篇指南以仓库 README.md 为核心骨架,完整覆盖四种安装方式、首次运行的 Setup Wizard、config.yaml 与 styles.css 的配置体系、yasbc 命令行工具,并结合仓库源码(src/main.py、src/core/config.py、pyproject.toml 等)讲透其底层机制——读完你既可以照抄安装步骤快速跑起来,也可以自己动手写出高度个性化、可热重载的状态栏。
YASB 是什么:项目概览
- 定位:面向 Windows 桌面(Windows 10 / 11)的状态栏应用。你可以把它理解为 Windows 版的 Polybar/Waybar——桌面窗口管理器之上的一块信息条,但它本身不依赖任何窗口管理器,作为普通状态栏即可工作。
- 技术栈:Python 编写,基于 PyQt6 构建界面,使用 Pydantic 做配置校验,通过 qasync 把 Qt 事件循环与 asyncio 融合(见 pyproject.toml 的依赖清单:
pyqt6==6.10.2、pydantic==2.13.5、pywin32、qasync、watchdog、winrt.*系列 WinRT 绑定等)。项目要求 Python >= 3.14。 - 配置方式:一份 config.yaml(YAML)决定「显示什么、放哪里」,一份 styles.css(CSS)决定「长什么样」。默认开启热重载,修改配置或样式后状态栏会自动刷新。
- 扩展生态:内置 58 个官方 Widget(详见后文完整清单),支持社区主题一键安装、全局热键、多显示器/多状态栏编排。
从源码结构看(src/),应用被清晰地拆分为入口(src/main.py)、配置加载与校验(src/core/config.py、src/core/validation/)、状态栏窗口(src/core/bar.py、src/core/bar_manager.py)、Widget 体系(src/core/widgets/)、托盘与 CLI 控制(src/core/tray.py、src/cli.py)等模块,这让 YASB 同时具备「开箱即用」与「可读源码二次开发」的双重属性。
安装 YASB
系统要求与字体准备
- 操作系统:Windows 10 或 Windows 11。
- 字体:默认主题使用 Segoe Fluent Icons 字体,Windows 11 已内置;Windows 10 用户需要手动下载安装该字体。
- 自定义主题:推荐安装 Nerd Fonts(带大量图标字形),官方推荐 JetBrainsMono Propo 字体。若使用 Setup Wizard 安装,可在向导内完成字体的下载与安装。
方式一:下载 MSI 安装包(稳定版与预览版)
- 前往项目 Releases 页面,展开 Assets 下载区。
- 选择与你的系统架构匹配的安装程序(x64 或 ARM64)。
- 大多数设备选择 x64 的 per-user(仅当前用户)安装包即可;需要全机安装时选择 machine-wide 版本。
稳定版下载 yasb-{version}-{architecture}.msi;预览版(latest development build)下载 yasb-preview-{architecture}.msi,二者安装流程一致(详见 docs/Installation.md)。
方式二:通过包管理器(仅稳定版)
WinGet(默认按当前安装范围更新):
winget install --id AmN.yasb # 用户级安装(默认)
winget install --scope machine AmN.yasb # 全机级安装
Scoop:
scoop bucket add extras
scoop install extras/yasb
Chocolatey:
choco install yasb
注意:通过包管理器更新 YASB 时,会遵循当前的安装范围(scope),不会在更新过程中悄悄改变安装方式。
方式三:使用 Python 直接运行(开发/体验)
- 安装 Python(>= 3.14)。
- 安装应用及其依赖:
pip install .—— 常规安装;pip install -e .[dev]—— 开发模式安装(含 lint/type-check 工具链:ruff、pyright、pytest 等);pip install -e .[dev,packaging]—— 打包开发安装(额外包含 cx-freeze)。
- 启动应用:
python src/main.py。
入口 src/main.py 展示了启动流程:先初始化日志与 CLI 管道、加载 .env、设置字体引擎,然后通过命名互斥体(single_instance_lock)保证同一时间只运行一个 YASB 实例,接着判断是否首次运行并弹出 Setup Wizard,最后在 qasync 事件循环中启动状态栏、文件监听、托盘图标与自动更新服务。
方式四:从源码构建 MSI 安装器
git clone https://gitcode.com/gh_mirrors/yas/yasb
cd yasb
pip install -e .[packaging]
cd src
python build.py build
python build.py bdist_msi
设置开机自启
两种方式任选其一:
- 系统托盘菜单(推荐):右下角托盘找到 YASB 图标 → 右键 → 切换 Enable Autostart。
- 命令行 CLI:
- 启用:
yasbc enable-autostart;停用:yasbc disable-autostart - 若遇到开机启动延迟,或希望以管理员权限运行:
yasbc enable-autostart --task(通过 Windows 任务计划程序启动,需管理员权限)。
- 启用:
首次运行:Setup Wizard
首次启动(或清空配置后)会自动弹出交互式 Setup Wizard,帮助你无需手动改文件、装字体即可把状态栏跑起来。向导会处理三件事:
- 字体安装:检测并引导安装 JetBrains Mono Nerd Font(状态栏图标字形)与 Segoe Fluent Icons(Windows 风格系统图标;Windows 10 用户可通过向导安装)。
- 窗口管理器集成:选择使用的平铺窗口管理器(GlazeWM 或 Komorebi),向导会预配置工作区指示器与布局;不用则选 None,把 YASB 当作普通 Windows 状态栏。向导对应的预设可见于 src/core/setup/widgets_config.py(例如 Komorebi 会预置
komorebi_workspaces,GlazeWM 会预置glazewm_workspaces,基础布局会预置 home/clock/volume/notifications/power_menu)。 - 布局与位置:选择默认 Widget(如 CPU、内存、活动窗口、时钟、音量、快捷启动等),并决定使用悬浮条(floating bar)还是全宽任务栏风格,以及屏幕位置(顶部/底部)。
完成后向导会在配置目录生成默认的 config.yaml 与 styles.css 并启动状态栏。若想重新走一遍向导,删除这两个文件,或直接运行 yasbc reset。
配置详解
配置文件位置与加载机制
YASB 使用两份文件:config.yaml(配置)与 styles.css(样式)。默认目录为:
C:/Users/{username}/.config/yasb/
若设置了环境变量 YASB_CONFIG_HOME,则使用该变量指定的目录(见 src/settings.py 中 DEFAULT_CONFIG_DIRECTORY 的定义)。
配置加载与校验逻辑集中在 src/core/config.py:YAML 经 safe_load 解析后,先递归展开环境变量占位符(parse_env),再交给 Pydantic 模型 YasbConfig 校验与归一化;样式则通过 CSSProcessor 处理。任何校验错误都会记录到日志并弹出提示对话框,而不会用非法配置把应用搞挂——这正是 Pydantic 校验层(src/core/validation/)的价值。
环境变量支持与 .env 文件
YASB 支持从 .env 文件加载环境变量,便于把 API Key、Token 等敏感信息放在 config.yaml 之外:
- 文件位置:
C:/Users/{username}/.config/yasb/.env(或YASB_CONFIG_HOME指定目录)。 - 引用方式:在
config.yaml中将值写为$env:变量名,例如api_key: "$env:YASB_WEATHER_API_KEY"。 - 加载时机:启动时自动加载(src/env.py 使用
dotenv),且配置解析时的parse_env会递归地把 YAML 字符串中的$env:...替换为实际环境变量值。
YASB_WEATHER_API_KEY=your_api_key_here
YASB_GITHUB_TOKEN=your_github_token_here
YASB_WEATHER_LOCATION=your_location_here
# 部分 Qt 渲染设置
QT_SCREEN_SCALE_FACTORS="1.25;1"
QT_SCALE_FACTOR_ROUNDING_POLICY="PassThrough"
字体引擎(Font Engine)
通过 .env 或系统环境变量设置 YASB_FONT_ENGINE 可切换文本渲染引擎(默认 gdi),有效值:
| 值 | 说明 |
|---|---|
native |
使用 DirectWrite 字体渲染引擎 |
gdi |
使用 GDI 字体渲染引擎(默认) |
freetype |
使用 FreeType 字体渲染引擎 |
源码层面(src/env.py 的 set_font_engine)会把该值映射为 Qt 平台参数 QT_QPA_PLATFORM=windows:fontengine={engine}。不同引擎的字形渲染效果不同,且字体名称可能因引擎而异:例如 GDI 下的 font-family: 'JetBrainsMono NFP' 在 DirectWrite 下可能要写成 'JetBrainsMono Nerd Font Propo'。
根配置(Root Configuration)
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
watch_stylesheet |
boolean | true |
样式文件变更时自动重载状态栏 |
watch_config |
boolean | true |
配置文件变更时自动重载状态栏 |
debug |
boolean | false |
开启调试模式,输出更详细的日志 |
update_check |
boolean | true |
自动检查更新(仅安装版生效) |
show_systray |
boolean | true |
显示/隐藏托盘图标 |
system_colors |
boolean | false |
自动从 Windows 主题色生成 CSS 变量 |
tooltip |
object | 见下文 | 全局 Tooltip 配置 |
komorebi |
object | 见下文 | Komorebi 托盘菜单配置 |
glazewm |
object | 见下文 | GlazeWM 托盘菜单配置 |
日志与调试:在根配置设置 debug: true 可输出详细日志;终端运行 yasbc log 实时查看日志流;日志文件为配置目录下的 yasb.log。
Tooltip 配置
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
offset |
integer | 5 |
Tooltip 与悬停元素/状态栏的像素间距 |
blur_effect |
object | 见下 | 全局 Tooltip 模糊配置 |
blur_effect 子项:enabled(默认 false)、dark_mode(默认 false)、round_corners(默认 false,仅 Windows 11 生效)、round_corners_type(normal/small,仅 Windows 11 生效)、border_color(None/"system"/十六进制色值,仅 Windows 11 生效)。
tooltip:
offset: 5
blur_effect:
enabled: true
dark_mode: false
round_corners: true
round_corners_type: "small"
border_color: "None"
状态栏(Bars)配置
状态栏通过 bars 根键下的子节点定义,每一条 bar 是一组独立的窗口与 Widget 编排:
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enabled |
boolean | true |
是否启用该状态栏 |
screens |
list | ['*'] |
状态栏显示在哪些屏幕:['*'] 所有未分配屏幕、['**'] 所有屏幕(含已分配)、或具体屏幕名(如 ['DELL P2419H (1)'])、['primary'] 仅主屏 |
class_name |
string | "yasb-bar" |
状态栏的 CSS 类名 |
style |
string | "bar" |
视觉样式:"bar" 或 "adaptive" |
style_adaptive_exclude |
list | [] |
adaptive 样式下不参与绘制「岛屿」表面的 Widget |
context_menu |
boolean | true |
是否启用右键上下文菜单 |
alignment |
object | position: "top", align: "center" |
位置(top/bottom)与对齐(left/center/right) |
blur_effect |
object | enabled: false |
状态栏模糊/亚克力效果 |
window_flags |
object | 见下 | 窗口行为标志 |
dimensions |
object | {width: "100%", height: 36} |
宽高。宽度支持数字(像素)、百分比字符串("100%"、"50%")或 "auto"(随内容自适应) |
padding |
object | {top: 4, left: 0, bottom: 4, right: 0} |
内边距 |
animation |
object | {enabled: true, duration: 500} |
显隐动画,duration 单位为毫秒 |
widgets |
list | left[], center[], right[] |
启用的 Widget 及其所在分区 |
layouts |
object | 见下 | 每个分区(left/center/right)的布局参数 |
建议:
width: "auto"不适合持续更新数据的 Widget(如 CPU、内存、时钟),否则状态栏会不断自适应宽度,可能引起闪烁与性能问题。
Bar Style:bar 与 adaptive
"bar":默认样式,状态栏是一个由.yasb-bar的background-color填充的实心矩形。"adaptive":状态栏表面跟随内容。外缘绘制一条贯穿全宽的细「轨道(rail)」,每个 Widget 分组(left/center/right)以自己的「岛屿(island)」悬挂在轨道下,组与组之间透明,露出壁纸;最外侧岛屿紧贴状态栏边缘。岛屿可在样式表中关闭,得到普通的全宽条,可选仅圆滑外侧两角。
bars:
primary-bar:
style: "adaptive"
style_adaptive_exclude: ["systray", "weather"]
style_adaptive_exclude 中的名字来自你的 widgets 段;被排除的 Widget 照常绘制,只是其下方的岛屿表面被移除(中间的 Widget 会把一个岛屿切成两段)。Grouper 内的子 Widget 不能单独命名,排除整个 Grouper 才会移除整组表面。
注意:岛屿之间需要空隙才能切出形状,因此开启岛屿时需要状态栏足够宽;
dimensions.width: "auto"或 Widget 铺满全宽的 bar 无论如何都会按普通矩形绘制。
动画配置:enabled(默认 true)、duration(毫秒,默认 500)、type("slide" 从屏幕边缘滑入 / "fade" 淡入淡出)。
Blur Effect 配置:enabled(默认 false)、acrylic(Windows 10 亚克力模糊,默认 false)、dark_mode(默认 false)、round_corners/round_corners_type/border_color(均仅 Windows 11 生效,圆角类型 normal/small,边框色可为 None/"system"/十六进制色)。
Window Flags 配置:
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
always_on_top |
boolean | false |
状态栏是否始终置顶 |
windows_app_bar |
boolean | true |
是否注册为 Windows App Bar(系统会为它预留屏幕空间) |
hide_on_fullscreen |
boolean | false |
全屏窗口出现时隐藏状态栏 |
hide_on_maximized |
boolean | false |
状态栏所在屏幕上有窗口最大化时自动隐藏(仅 windows_app_bar: false 时生效) |
auto_hide |
boolean | false |
闲置时自动隐藏 |
Layouts 配置:每个分区可设置 alignment(left/center/right,默认随分区而定)与 stretch(Widget 是否拉伸填满可用空间,默认 true):
layouts:
left:
alignment: "left"
stretch: true
center:
alignment: "center"
stretch: true
right:
alignment: "right"
stretch: true
多状态栏示例:不同屏幕可以配不同的 bar。屏幕名可用 yasbc monitor-information 查询。
bars:
status-bar:
screens: ['DELL P2419H (1)'] # 仅显示器 1
widgets:
left: ["clock"]
center: ["cpu"]
right: ["memory"]
status-bar-2:
screens: ['DELL P2419H (2)'] # 仅显示器 2
widgets:
left: ["active_window"]
center: ["media"]
right: ["volume","power_menu"]
status-bar-3:
screens: ['*'] # 所有未分配屏幕
widgets:
center: ["weather"]
global-taskbar:
screens: ['**'] # 所有屏幕(含已分配)
widgets:
left: ["taskbar"]
屏幕分配规则小结:['*'] 显示在所有未分配屏幕(未显式分配给其他 bar 的屏幕);['**'] 显示在所有屏幕(包括已分配给其他 bar 的);['屏幕名'] 仅显示在指定屏幕。
托盘菜单联动:Komorebi / GlazeWM
| Komorebi 选项 | 默认值 |
|---|---|
start_command |
"komorebic start --whkd" |
stop_command |
"komorebic stop --whkd" |
reload_command |
"komorebic reload-configuration" |
| GlazeWM 选项 | 默认值 |
|---|---|
start_command |
"glazewm.exe start" |
stop_command |
"glazewm.exe command wm-exit" |
reload_command |
"glazewm.exe command wm-exit && glazewm.exe start" |
样式定制:styles.css
样式文件同样位于配置目录,格式为 CSS,但需要注意:YASB 基于 Qt 框架并使用自定义 CSS 引擎(qt-css-engine),因此样式行为与标准 CSS3 存在差异(docs/Styling.md)。
主题与社区样式
如果你不想从零写 CSS,可以使用内置的 Themes Manager(yasb_themes.exe) 浏览、预览并一键安装社区主题:
- 启动方式:托盘图标右键 → Get Themes;或直接运行安装目录下的
yasb_themes.exe。 - 功能:按名称搜索过滤、阅读主题 README(自定义特性/快捷键/可选 Widget 配置)、悬停预览图放大查看、一键安装(自动备份现有配置文件)。
主要选择器
| 选择器 | 作用对象 |
|---|---|
.yasb-bar |
状态栏主窗口 |
.container-left / .container-center / .container-right |
三个 Widget 分组容器 |
.widget |
所有 Widget 的通用样式 |
.clock-widget、.media-widget 等 |
具体某个 Widget |
.widget-container |
单个图标/文本的外层容器 |
.icon |
图标 |
.label |
文本 |
.context-menu |
右键上下文菜单 |
.tooltip |
Tooltip |
示例——圆角时钟 Widget:
.clock-widget {
border-top-left-radius: 18px;
border-bottom-left-radius: 18px;
}
示例——给 Widget 容器上底色(可配合 .media-widget .widget-container 等组合选择器使用):
.clock-widget .widget-container {
background-color: #1e1e1e;
border-radius: 10px;
}
Adaptive Bar 的专属属性
当 bar 配置为 style: "adaptive" 时,会额外获得 .adaptive 类并使用 -qproperty- 前缀的专有属性绘制形状:
.yasb-bar.adaptive {
background-color: rgba(20, 20, 22, 0.94);
-qproperty-railheight: 4;
-qproperty-islandradius: 16;
-qproperty-grouppadding: 8;
}
| 属性 | 默认值 | 说明 |
|---|---|---|
-qproperty-railheight |
4 |
状态栏外缘轨道的高度 |
-qproperty-islandradius |
16 |
轨道与岛屿之间的圆角半径,上限为 (height - railheight) / 2 |
-qproperty-grouppadding |
8 |
分组内容四周的留白,会放大岛屿(移动 Widget 请用 .container-left 等的 padding) |
-qproperty-islands |
true |
设为 false 得到实心全宽条;此时 rail/islandradius/grouppadding/style_adaptive_exclude 均无作用,但 edgeradius 仍有效 |
-qproperty-edgeradius |
0 |
圆滑外侧两角(0 为关闭) |
-qproperty-borderwidth |
0 |
沿形状内缘绘制边框的宽度(CSS border 无法贴合此形状) |
-qproperty-bordercolor |
transparent | 上述边框颜色,支持任意 CSS 颜色含 rgba() |
注意:属性名是
-qproperty-前缀(带前导短横线,便于编辑器识别为厂商前缀),YASB 会在样式进入 Qt 前去掉该横线。属性名小写,且只在adaptive样式下生效。Qt 只在 widget 抛光时读取一次qproperty,删除某行不会恢复旧值(需重启或显式设回默认值)。
为形状描边(CSS border 无法跟随岛屿形状,需用专有属性):
.yasb-bar.adaptive {
border: none;
-qproperty-borderwidth: 1;
-qproperty-bordercolor: #ffffff;
}
圆滑屏幕边缘(让桌面下方呈现圆角屏角效果):
.yasb-bar.adaptive {
-qproperty-edgeradius: 14;
}
edgeradius需要 bar 真正延伸到屏幕边缘(即dimensions.width铺满屏幕)才生效;其绘制超出 bar 窗口本身,角落小区域会吞掉点击桌面的事件。
动画与伪类
YASB 的 CSS 引擎支持 transition 过渡(语法同 CSS transitions):
.glazewm-workspaces .ws-btn {
background: transparent;
transition: background 200ms ease-in-out;
}
.glazewm-workspaces .ws-btn:hover {
background: gray;
}
可动画化的伪类::hover、:focus、:active(窗口焦点伪类,非 CSS 语义)、:pressed(等价 CSS :active)、:checked、:clicked(点击时播放完整动画)。支持 opacity、box-shadow、text-shadow、cursor(不可动画)等额外属性,以及 linear-gradient()/radial-gradient()/conic-gradient() 颜色函数(不可动画)。限制:动画无法作用于子控件(如 ::item、::chunk)。可用 transition: all 200ms 50ms ease-out 添加延迟,支持 ease-in-out、cubic-bezier(...)、steps(...) 等缓动函数。
跟随系统主题(明/暗)
当系统处于深色模式时,YASB 会给根元素添加 .dark 类,据此编写明暗双主题:
.yasb-bar { background-color: #1e1e1e; }
.dark.yasb-bar { background-color: #1e1e1e; }
.yasb-bar .label { color: #000000; }
.dark.yasb-bar .label { color: #ffffff; }
系统颜色变量
在根配置开启 system_colors: true 后,YASB 会从 Windows 主题色自动生成 yasb_colors.css,在 styles.css 顶部导入即可使用动态变量:
@import "yasb_colors.css";
.yasb-bar {
background-color: var(--yasb-background);
}
.clock-widget {
border-color: rgba(var(--yasb-accent-rgb), 0.5);
color: var(--yasb-accent-light2);
}
可用变量(每个变量同时提供 var(--name) 与 var(--name-rgb) 两种形态):--yasb-accent、--yasb-accent-dark1~3、--yasb-accent-light1~3、--yasb-background、--yasb-foreground。这也是 src/main.py 中 config.system_colors 分支启动 SystemColorsService 所对应的能力。
上下文菜单与 Tooltip 样式
.context-menu,
.context-menu .menu-checkbox {
background-color: #202020;
border: none;
padding: 4px 0px;
font-family: 'Segoe UI';
font-size: 12px;
color: #FFFFFF;
}
.tooltip {
background-color: #18191a;
border: 1px solid #36383a;
border-radius: 4px;
color: #a6adc8;
padding: 6px 12px;
font-size: 13px;
font-family: 'Segoe UI';
font-weight: 600;
}
Widget 生态:58 个官方模块全览
YASB 最大的卖点在于 Widget 生态。所有 Widget 的详细配置(options、callbacks、数据格式)都收录在 docs/widgets/ 目录,每条文档对应一个 (Widget)-名称.md 文件。以下为完整清单(来源:README.md 的官方列表):
系统监控类:CPU-CPU.md)(CPU 使用率与信息)、GPU-GPU.md)(利用率/温度/显存)、Memory-Memory.md)(内存使用)、Disk-Disk.md)(磁盘占用)、Traffic-Traffic.md)(网络流量)、Battery-Battery.md)(电池状态)、Brightness-Brightness.md)(亮度显示与调节)、Volume-Volume.md)(音量显示与控制)、Microphone-Microphone.md)(麦克风状态)、Libre Hardware Monitor-Libre-HW-Monitor.md)(连接 Libre Hardware Monitor 获取传感器数据)、Server Monitor-Server-Monitor.md)(服务器状态监控)。
媒体与娱乐:Media-Media.md)(媒体控制与信息)、Media Lite-Media-Lite.md)(竖版极简专辑风媒体)、Audio Visualizer-Audio-Visualizer.md)(默认输出设备的原生音频可视化,WASAPI loopback)、Cava-Cava.md)(基于 Cava 的音频可视化)。
桌面工具:Clock-Clock.md)(时间日期,格式可定制)、Active Windows Title-Active-Windows-Title.md)(当前活动窗口标题)、Control Center-Control-Center.md)(快捷设置控制中心:快捷操作、滑杆、媒体控制)、Taskbar-Taskbar.md)(应用启动任务栏)、Window Controls-Window-Controls.md)(最小化/最大化/关闭聚焦窗口)、Window Switcher-Window-Switcher.md)(轻量应用切换器)、Launchpad-Launchpad.md)(快捷访问应用)、Quick Launch-Quick-Launch.md)(支持众多插件的强力快捷启动器)、Home-Home.md)(可定制的首页菜单)、Grouper-Grouper.md)(把多个 Widget 组合进一个容器)、Applications-Applications.md)(预定义应用列表)、Power Menu-Power-Menu.md)(电源选项菜单)、Power Plan-Power-Plan.md)(电源计划显示与切换)、Recycle Bin-Recycle-Bin.md)(回收站状态)、Update Checker-Update-Check.md)(Windows Update / Winget 更新检查)、Dnd-Dnd.md)(监测与切换 Windows 专注助手/免打扰)、Notifications-Notifications.md)(Windows 通知数量)、Notes-Notes.md)(笔记增删查)、Todo-Todo.md)(任务清单)、Pomodoro-Pomodoro.md)(番茄钟)、Wallpapers-Wallpapers.md)(壁纸管理)、Systray-Systray.md)(系统托盘图标)、Weather-Weather.md)(天气)、Open Meteo-Open-Meteo.md)(Open Meteo API 天气)、Language-Language.md)(输入法语言切换)、WiFi-WiFi.md)(WiFi 状态与可用网络)、Bluetooth-Bluetooth.md)(蓝牙状态与连接设备)。
窗口管理器集成:GlazeWM Binding Mode-GlazeWM-Binding-Mode.md)、GlazeWM Tiling Direction-GlazeWM-Tiling-Direction.md)、GlazeWM Workspaces-GlazeWM-Workspaces.md)、Komorebi Control-Komorebi-Control.md)、Komorebi Layout-Komorebi-Layout.md)、Komorebi Stack-Komorebi-Stack.md)、Komorebi Workspaces-Komorebi-Workspaces.md)、WHKD-Whkd.md)(WHKD 热键绑定模式)、Windows-Desktops-Windows-Desktops.md)(Windows 虚拟桌面)。
开发者 / AI / 专项:Claude Usage-Claude-Usage.md)(Claude 订阅用量)、Copilot-Copilot.md)(GitHub Copilot 用量与统计菜单)、Github-Github.md)(GitHub 通知)、VSCode-VSCode.md)(VS Code 最近打开目录)、OBS-Obs.md)(OBS Studio 直播信息)、Glucose Monitor-Glucose-Monitor.md)(Nightscout CGM 血糖监测)、Custom-Custom.md)(自定义 Widget)。
Widget 的通用配置结构
从 src/core/widgets/base.py 可以看出所有 Widget 共享一套基座:每个 Widget 通过 type 字段指向 core.widgets.{module}.{Class}(如 yasb.clock.ClockWidget),并由 src/core/utils/widget_builder.py 的 WidgetBuilder 动态导入模块、读取其 validation_schema(Pydantic 模型)校验 options 后实例化。典型结构:
widgets:
clock:
type: "yasb.clock.ClockWidget"
options:
label: "{%H:%M}"
label_alt: "{%a, %d %b %H:%M}"
callbacks:
on_left: "toggle_calendar"
on_middle: "toggle_label"
on_right: "context_menu"
鼠标左/中/右键分别触发 on_left/on_middle/on_right 回调,on_timer 可做定时刷新;回调由 base.py 的 _handle_mouse_events → _run_callback 分发到 callbacks 字典,未注册的回调名会安全降级为 default。
全局热键(Keybindings)
YASB 支持为任意 Widget 注册全局快捷键(基于 Windows 原生 RegisterHotKey,零第三方依赖;详见 docs/Keybindings.md):
clock:
type: "yasb.clock.ClockWidget"
options:
label: "{%H:%M}"
keybindings:
- keys: "win+c"
action: "toggle_calendar"
- keys: "ctrl+shift+t"
action: "toggle_label"
keys 支持 win/alt/ctrl/shift 修饰键(RegisterHotKey 不区分左右修饰键)、f1~f24、字母与数字、方向键及常用特殊键;screen(可选)可指定 "active"(聚焦窗口所在屏幕,默认)、"cursor" 或 "primary"。热键与 Widget 实例一一绑定、按屏幕感知触发,未定义热键时不启动任何监听,零开销。
命令行工具:yasbc
yasbc 是与运行中的 YASB 交互的 CLI 客户端(通过命名管道 \\.\pipe\yasb_pipe_cli 通信,见 src/cli.py)。用法:yasbc [command] [options]。
命令一览:
| 命令 | 说明 |
|---|---|
start |
启动状态栏 |
stop |
停止状态栏 |
reload |
重载状态栏配置 |
enable-autostart / disable-autostart |
启用/停用开机自启(--task 走任务计划程序,需管理员权限) |
enable-crash-dumps / disable-crash-dumps |
启用/停用崩溃转储(需管理员权限,转储写入配置目录 dumps 文件夹,保留最近 5 份) |
hide-bar / show-bar / toggle-bar |
隐藏/显示/切换状态栏,支持 --screen <屏幕名> 指定屏幕 |
monitor-information |
显示已连接显示器信息 |
update |
按当前更新通道更新到最新版 |
set-channel |
切换更新通道(stable / preview) |
migrate-config |
扫描并修复配置中的废弃选项(改动前自动备份 config.yaml.bak) |
log |
实时流式查看日志(debug: true 可获得详细日志;Ctrl+C 退出) |
reset |
恢复默认配置文件并清空缓存 |
config-dir |
在资源管理器中打开配置目录 |
help |
显示帮助 |
选项:-h, --help;-v, --version(显示 YASB 与 CLI 版本);-c, --config(打印配置目录绝对路径);-s, --silent(抑制 start/stop/reload 的正常状态输出)。
常用组合:
yasbc enable-autostart --task # 任务计划程序方式自启(管理员)
yasbc log # 实时日志
yasbc reset # 重置配置并再次打开 Setup Wizard
yasbc set-channel preview # 切换到预览版更新通道
yasbc migrate-config # 迁移旧配置
常见问题与排障(FAQ 速查)
- 图标显示异常/方块:通常是字体缺失。重跑 Setup Wizard(删除配置文件或
yasbc reset)自动安装 JetBrains Mono Nerd Font 与 Segoe Fluent Icons;Windows 10 需额外安装 Segoe Fluent Icons;装完字体后重启 YASB。 - 模糊效果不生效:检查系统「透明效果」是否开启、
blur_effect.enabled是否置为true、GPU 驱动与桌面合成(composition)是否正常。 - 更新后崩溃:查看更新说明的破坏性变更,对照最新示例配置检查
config.yaml,更新前备份配置。 - 想换位置/大小:修改
bars下对应 bar 的alignment.position(top/bottom)与dimensions的宽高。 - 高 CPU 占用:多为
update_interval设置过低或实时 Widget 过多。 - 启动慢:可改用
yasbc enable-autostart --task注册为任务计划程序,并排查启动项冲突。 - CSS 不生效:YASB 基于 Qt 自定义 CSS 引擎,仅支持基础 CSS 属性、无高级 CSS3 特性;检查语法后重启。
更多内容见 docs/FAQ.md。
进一步阅读与源码学习路线
如果你希望深入源码理解这套体系,建议按以下顺序阅读:
- src/main.py:应用入口。单实例互斥锁、首次运行判断(
is_first_run)、Setup Wizard 触发、qasync 事件循环、配置加载、BarManager 初始化、文件监听(watchdog)、系统颜色服务、托盘与自动更新。 - src/core/config.py:配置/样式的读取、
$env:环境变量递归展开、Pydantic 校验与错误提示。 - src/core/validation/bar.py:bar 配置的 Pydantic 模型,可对照本文各配置表的默认值(如
BarWindowFlags、BarDimensions的宽度合法性校验)。 - src/core/widgets/base.py 与 src/core/utils/widget_builder.py:Widget 基类、回调分发、热键处理与动态构建流程。
- src/core/setup/widgets_config.py:Setup Wizard 默认布局与窗口管理器预设。
- 官方文档目录 docs/:Home.md、Installation.md、Configuration.md、Styling.md、CLI.md、Keybindings.md、FAQ.md 以及
docs/widgets/下每个 Widget 的专项文档。
总而言之:YASB 的价值不在于「又一个状态栏」,而在于把配置化、热重载、可编程回调、多屏编排、社区主题组合成了⼀套完整的桌面定制工作流。从本文的安装起步,到 config.yaml 的精细调参,再到 styles.css 的主题再造与 yasbc 的自动化管理,你可以把它从一块默认的顶部信息条,逐步改造成真正属于自己的 Windows 桌面控制中枢。

