YASB(Yet Another Status Bar)完全指南:Windows 高度可配置状态栏的安装、配置与深度定制

原创2026-10-11 21:39:332,255 阅读
文章标签:桌面应用UI组件可观测性

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 深色主题运行效果:状态栏整合时钟、系统监控、音量等模块

YASB 浅色主题运行效果:同一套配置在不同主题下的视觉呈现

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 安装包(稳定版与预览版)

  1. 前往项目 Releases 页面,展开 Assets 下载区。
  2. 选择与你的系统架构匹配的安装程序(x64 或 ARM64)。
  3. 大多数设备选择 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

设置开机自启

两种方式任选其一:

  1. 系统托盘菜单(推荐):右下角托盘找到 YASB 图标 → 右键 → 切换 Enable Autostart。
  2. 命令行 CLI:
    • 启用:yasbc enable-autostart;停用:yasbc disable-autostart
    • 若遇到开机启动延迟,或希望以管理员权限运行:yasbc enable-autostart --task(通过 Windows 任务计划程序启动,需管理员权限)。

首次运行:Setup Wizard

首次启动(或清空配置后)会自动弹出交互式 Setup Wizard,帮助你无需手动改文件、装字体即可把状态栏跑起来。向导会处理三件事:

  1. 字体安装:检测并引导安装 JetBrains Mono Nerd Font(状态栏图标字形)与 Segoe Fluent Icons(Windows 风格系统图标;Windows 10 用户可通过向导安装)。
  2. 窗口管理器集成:选择使用的平铺窗口管理器(GlazeWM 或 Komorebi),向导会预配置工作区指示器与布局;不用则选 None,把 YASB 当作普通 Windows 状态栏。向导对应的预设可见于 src/core/setup/widgets_config.py(例如 Komorebi 会预置 komorebi_workspaces,GlazeWM 会预置 glazewm_workspaces,基础布局会预置 home/clock/volume/notifications/power_menu)。
  3. 布局与位置:选择默认 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。

进一步阅读与源码学习路线

如果你希望深入源码理解这套体系,建议按以下顺序阅读:

  1. src/main.py:应用入口。单实例互斥锁、首次运行判断(is_first_run)、Setup Wizard 触发、qasync 事件循环、配置加载、BarManager 初始化、文件监听(watchdog)、系统颜色服务、托盘与自动更新。
  2. src/core/config.py:配置/样式的读取、$env: 环境变量递归展开、Pydantic 校验与错误提示。
  3. src/core/validation/bar.py:bar 配置的 Pydantic 模型,可对照本文各配置表的默认值(如 BarWindowFlags、BarDimensions 的宽度合法性校验)。
  4. src/core/widgets/base.py 与 src/core/utils/widget_builder.py:Widget 基类、回调分发、热键处理与动态构建流程。
  5. src/core/setup/widgets_config.py:Setup Wizard 默认布局与窗口管理器预设。
  6. 官方文档目录 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 桌面控制中枢。

登录后查看全文
yasb