YASB CPU 组件完全指南：配置、直方图与弹窗监控的源码级解析

发布时间：2026/10/12 5:31:22

桌面应用【免费下载链接】yasbA highly configurable Windows status bar written in Python.项目地址https://gitcode.com/gh_mirrors/yas/yasb点击查看免费下载YASBYet Another Status Bar是一款使用 Python 编写的高可配置 Windows 状态栏其 CPU 组件yasb.cpu.CpuWidget用于实时跟踪处理器频率与使用率支持每核使用率直方图、基于阈值变化的警告配色、圆形/线性进度条以及点击后弹出的含性能曲线与详细数据的监控弹窗。阅读本文后你将掌握 CPU 组件的全部配置项、占位符语法、弹窗与样式定制方法并理解其基于 Windows PDH 性能计数器的底层数据链路与线程模型。本文以 CPU 组件文档-CPU.md) 为主体结合组件源码、校验模型、PDH 数据采集实现等仓库证据展开。一、功能概述CPU 组件在状态栏中呈现为一小段文本标签并在后台持续更新以下信息处理器总使用率与当前频率标签文案可通过占位符完全自定义每核使用率直方图使用一组图标如▁▂▃▄▅▆▇█按百分比映射显示可直观观察多个核心的负载分布阈值警告配色依据cpu_thresholds配置low/medium/high为标签自动附加status-low、status-medium、status-high、status-critical状态类配合 CSS 即可实现负载低时绿色、高负载时红色的变色效果可选进度条支持circular圆形、linear_horizontal水平线性、linear_vertical垂直线性三种形态可配置渐变颜色与平滑动画点击弹窗menu右键/左键绑定toggle_menu后会弹出带CPU Usage标题的详情面板内含随时间滚动的利用率曲线图GraphWidget以及 Usage、Frequency、Cores、Max frequency 等实时统计项弹窗支持模糊背景、圆角、置顶pin与拖拽。二、快速接入把 CPU 组件放进状态栏CPU 组件是widgets配置节中的一个条目通过type: yasb.cpu.CpuWidget注册该字符串正是组件注册表依据类模块名生成的注册键。基础接入方式如下bars: status-bar: widgets: left: [clock] center: [cpu] # 引用下方定义的 cpu 组件 right: [volume, power_menu] widgets: cpu: type: yasb.cpu.CpuWidget options: label: span\uf4bc/span {info[percent][total]}% label_alt: span\uf437/span {info[freq][current]} MHz update_interval: 2000关于bars/widgets的完整配置结构可参考 docs/Configuration.md。仓库为 CPU 组件提供了开箱即用的默认预设见 src/core/setup/widgets_config.py其中默认启用了弹窗、居中对齐弹窗、左键点击打开菜单、右键切换标签如果希望快速上手也可以基于该预设再行微调。另外注意docs/Configuration.md 提示对于 CPU、内存、时钟这类高频更新组件不建议将 bar 宽度设为auto否则会导致状态栏频繁重排而产生闪烁或性能问题。三、配置项总览下表完整列出 CPU 组件支持的全部配置项、类型、默认值与含义默认值以当前仓库的校验模型与文档为准OptionTypeDefaultDescriptionlabelstring\uf200 {info[histograms][cpu_percent]}主标签格式。label_altstring文档表格为span\uf437/span {info[histograms][cpu_percent]}仓库校验模型中实际为\uf200 CPU: {info[percent][total]}% \| freq: {info[freq][current]:.2f} Mhz备用标签格式。class_namestring追加到组件上的自定义 CSS 类名。update_intervalinteger1000更新间隔毫秒最小 1000最大 60000。histogram_iconslist[\u2581,\u2581,\u2582,\u2583,\u2584,\u2585,\u2586,\u2587,\u2588]9 项直方图图标序列长度固定为 9。histogram_num_columnsinteger10直方图列数范围 0–128。callbacksdict{on_left: toggle_label, on_middle: do_nothing, on_right: do_nothing}各鼠标按键回调。cpu_thresholdsdict{low: 25, medium: 50, high: 90}CPU 使用率分级阈值0–100。progress_bardict见下文详细说明进度条设置。hide_decimalboolfalse是否隐藏数值小数位。menudict见下文详细说明弹窗图形与统计设置。说明label_alt在文档表格与校验模型中的默认值略有出入实际生效默认值以仓库中 cpu.py 校验模型定义为准本文后续示例均基于可运行的校验模型。四、配置项详解1. 标签格式label与label_altlabel与label_alt是支持占位符替换的格式字符串可混用span.../span包裹的图标与文本。组件内部会使用正则re.split((span.*?.*?/span))将格式串拆分为图标段与文本段图标段渲染为带.icon类的独立 QLabel文本段渲染为带.label类的 QLabel见 cpu.py。这意味着图标与文本的 CSS 可以分别定制。常用的占位符组合仅显示总使用率{info[percent][total]}%显示使用率与当前频率CPU: {info[percent][total]}% | {info[freq][current]} MHz显示直方图{info[histograms][cpu_percent]}备用标签如切换显示频率{info[freq][current]} MHz通过callbacks绑定toggle_label后单击可在主标签与备用标签间切换_toggle_label实现于 cpu.py。2. 更新间隔update_interval单位为毫秒校验模型限制范围为1000–60000见 cpu.py 校验模型。文档中最小 1000ms与源码ge1000完全一致。设置 20002 秒可降低 PDH 查询频率与 CPU 占用适合不需要秒级响应的场景。3. 阈值配色cpu_thresholds字典包含low、medium、high三个 0–100 的整数阈值。组件每次更新标签时都会调用_get_cpu_threshold()cpu.py按以下逻辑计算状态percent low→status-lowlow percent medium→status-mediummedium percent high→status-highpercent high→status-critical状态类会被写入标签 QLabel 的class属性并触发样式刷新因此可在 CSS 中按status-low/medium/high/critical分别着色。注意阈值是使用率百分比的阈值不是频率阈值。4. 直方图histogram_icons与histogram_num_columnshistogram_icons是一组长度固定为 9的图标校验模型min_length9, max_length9默认值从 0% 到 100% 依次为▁▁▂▃▄▅▆▇█。组件维护两个定长环形缓冲deque(maxlenhistogram_num_columns)分别保存频率与使用率历史每次更新时通过_get_histogram_bar()cpu.py将数值线性映射到图标下标bar_index int((num - num_min) / (num_max - num_min) * (len(histogram_icons) - 1)) bar_index min(max(bar_index, 0), len(histogram_icons) - 1)即数值越小越靠图标序列前部越高越靠近满格█。直方图同时驱动三个占位符输出cpu_freq频率直方图、cpu_percent总使用率直方图、cores每核使用率直方图。histogram_num_columns决定显示多少列即历史采样点数量范围 0–128默认 10。5. 进度条progress_barprogress_bar为嵌套字典完整字段如下含校验范围见 cpu.py 校验模型字段类型默认值说明enabledboolfalse是否启用进度条。progress_typestringcircular可选circular、linear_horizontal、linear_vertical。positionstringleft进度条相对标签的位置left或right。sizeinteger18进度条长度圆形时为直径范围 1–200。thicknessinteger3进度条粗细范围 1–100。radiusinteger0线性进度条的圆角半径范围 0–100。colorstring / list#00C800进度条颜色可传单个颜色或列表如[#57948a, #ff0000]形成渐变。background_colorstring#3C3C3C进度条轨道背景色。animationbooltrue数值变化时是否平滑动画过渡。实现细节进度条由build_progress_widget()utilities.py构建为ProgressBarProgressWidget组合ProgressWidget带.progress-container类便于 CSS 布局。ProgressBar的绘制逻辑位于 progress_bar.py圆形形态通过drawArc绘制 360° 底环与按value/100*360计算弧度的进度环线性形态按rect.width() * value/100水平或从底部向上的高度垂直裁剪绘制并支持radius圆角。启用animation时使用QPropertyAnimation400msOutCubic缓动平滑过渡且绝对值变化小于 0.9 时不会触发重绘见set_value避免无谓动画。每次数据更新时组件调用progress_widget.set_value(data.percent)将总使用率同步到进度条cpu.py。6. 鼠标回调callbackscallbacks支持on_left、on_middle、on_right三个键值为回调名。CPU 组件内部注册了以下回调cpu.pytoggle_label在主标签与备用标签间切换toggle_menu打开/关闭详情弹窗do_nothing无操作所有组件通用的内置回调exec执行命令BaseWidget内置回调。鼠标事件分发由 BaseWidget 统一处理左/中/右键分别触发callback_left/callback_middle/callback_right。此外callbacks还支持带参数的命令形式如exec cmd.exe /c ...参数解析见_run_callbackbase.py。7. 详情弹窗menumenu为嵌套字典控制点击后弹出的 CPU 详情面板。完整字段如下见 cpu.py 校验模型字段类型默认值说明enabledboolfalse是否启用弹窗。blurbooltrue弹窗背景是否应用模糊亚克力/毛玻璃效果。round_cornersbooltrue是否圆角。round_corners_typestringnormal圆角类型normal或small。border_colorstringSystem弹窗边框颜色默认跟随系统。alignmentstringright水平对齐left、center、right。directionstringdown展开方向up向上或down向下。offset_topinteger6距组件的垂直偏移像素。offset_leftinteger0距组件的水平偏移像素。show_graphbooltrue是否显示使用率历史曲线。show_graph_gridboolfalse是否在曲线下绘制方形网格。graph_history_sizeinteger60曲线保留的数据点数量范围 10–180。pin_iconstring\ue718未置顶时钉住按钮显示的图标。unpin_iconstring\ue77a置顶后钉住按钮显示的图标。弹窗由build_stat_popup()stat_popup.py构建包含头部标题bCPU/b Usage与置顶pin按钮、可选的GraphWidget曲线区并插入 Utilization 图标题见 cpu.py、以及两行四格统计卡片Usage / Frequency / Cores (P / L) / Max frequency。弹窗基于PinnablePopupstat_popup.py实现默认无边框、置顶、点击外部自动隐藏点击钉住按钮后可保持打开并拖动。弹窗打开期间后台线程每帧数据都会实时刷新曲线与统计数值_update_popupcpu.py。五、可用占位符Placeholders组件渲染标签时构造了一个cpu_info字典cpu.py所有占位符均通过 Python 字符串.format()语法{info[key]}访问可用键如下核心信息{info[cores][physical]}- 物理核心数{info[cores][total]}- 总核心数含超线程逻辑核心频率信息{info[freq][current]}- 当前 CPU 频率MHz包含睿频与 Windows 任务管理器一致{info[freq][max]}- 基准/标称频率MHz{info[freq][min]}- 最小频率MHz使用率{info[percent][total]}- 总使用率0-100{info[percent][core]}- 每核使用率列表直方图{info[histograms][cpu_freq]}- 频率直方图按配置的图标序列渲染{info[histograms][cpu_percent]}- 使用率直方图{info[histograms][cores]}- 每核使用率直方图提示占位符值在启用hide_decimal: true时会被取整round()如{info[freq][current]}显示为整数 MHz。另外直方图占位符拼接了历史缓冲区中全部列的内容因此默认 10 列对应 10 个图标字符。六、完整示例配置以下配置综合了官方文档示例与仓库预设widgets_config.py可直接复制使用cpu: type: yasb.cpu.CpuWidget options: label: span\uf4bc/span {info[percent][total]}% label_alt: span\uf437/span {info[freq][current]} MHz update_interval: 2000 hide_decimal: true cpu_thresholds: low: 25 medium: 50 high: 90 histogram_icons: - \u2581 # 0% - \u2581 # 10% - \u2582 # 20% - \u2583 # 30% - \u2584 # 40% - \u2585 # 50% - \u2586 # 60% - \u2587 # 70% - \u2588 # 80% histogram_num_columns: 8 callbacks: on_left: toggle_menu # 左键打开详情弹窗 on_right: toggle_label # 右键切换标签 on_middle: do_nothing progress_bar: enabled: true progress_type: circular position: left size: 18 thickness: 3 color: #00C800 background_color: #3C3C3C animation: true menu: enabled: true blur: true round_corners: true round_corners_type: normal border_color: System alignment: center direction: down offset_top: 6 offset_left: 0 show_graph: true show_graph_grid: true graph_history_size: 60 pin_icon: \ue718 unpin_icon: \ue77a配置说明type必须是yasb.cpu.CpuWidget这是组件注册表 registry.py 中的注册键示例直方图使用 9 个图标与校验模型的长度约束一致注释标明了每个图标对应的使用率区间callbacks将左键绑定为打开弹窗、右键绑定为切换标签与仓库默认预设相反可按习惯调整progress_bar启用了圆形进度环颜色可通过列表实现渐变如color: [#57948a, #ff0000]弹窗graph_history_size取值必须在 10–180 之间否则配置校验失败。配置校验由 Pydantic 模型CpuConfig完成cpu.py 校验模型模型开启extraforbidbase_model.py即写入未列出的字段会直接报错同时支持历史弃用字段的自动迁移。七、源码级原理数据从 PDH 到标签的完整链路1. 数据采集Windows PDH 性能计数器CPU 组件不依赖psutil而是直接通过 WindowsPerformance Data HelperPDHAPI获取实时指标实现位于 cpu_api.py。初始化时_init_querycpu_api.py会通过GetSystemInfo获取逻辑核心数通过GetLogicalProcessorInformationEx统计物理核心数并缓存打开 PDH 查询句柄PdhOpenQueryW按 Windows 版本选择计数器路径从源码可见Windows 11 24H2 及以上build ≥ 26100使用\Processor Information(_Total)\% Processor Time更早的 Windows 10 / Win11 版本使用\% Processor Utility见_WIN11_24H2_BUILD 26100常量与分支逻辑并带有向后兼容的 fallback注册总使用率、\% Processor Performance用于推算当前频率、每核使用率等多条计数器通过Processor Frequency计数器缓存基准频率。每次采样时get_datacpu_api.py调用PdhCollectQueryData收集数据读取各计数器格式化值总使用率被裁剪到 0–100 并保留 1 位小数当前频率由基准频率乘以性能百分比推算current_freq base_freq * perf_pct / 100这也是文档中current 包含睿频、与任务管理器一致的实现来源。2. 后台线程CpuWorker 单例为避免在 UI 线程中阻塞式采集数据组件使用CpuWorkerQThread 单例cpu_api.py在后台循环采样每次采集后用time.perf_counter()精确扣除耗时再按update_interval休眠剩余时间最后通过data_ready信号将CpuData快照投递回主线程。多个 CPU 组件实例共享同一个 worker 与 PDH 查询句柄CpuWidget维护类级_instances列表首个实例启动 worker后续实例复用cpu.py_on_data_ready类方法遍历所有存活实例刷新标签与弹窗cpu.py。worker 在应用退出aboutToQuit时通过事件stop()平滑停止。3. 渲染与状态刷新主线程收到数据后执行_update_labelcpu.py将当前频率与使用率追加进两个直方图环形缓冲按hide_decimal决定是否取整所有数值组装cpu_info占位符字典含三个直方图字符串解析标签格式串按status-{threshold}更新 QLabel 的 class 并刷新样式若启用进度条则同步数值。4. 弹窗与曲线弹窗曲线由GraphWidgetstat_popup.py自绘以 0–100 为纵轴将历史数据归一化为坐标点用三次贝塞尔样条张力 0.2平滑连线并绘制上深下浅的渐变填充区show_graph_grid开启时按 16px 单元格绘制方形网格网格颜色取自隐藏的*-grid样式代理的 CSScolor。曲线与统计标签的实时刷新由_update_popup完成cpu.py。八、样式定制组件结构对应的 CSS 选择器如下默认样式见 widgets_styles.py.cpu-widget {} .cpu-widget .widget-container {} .cpu-widget .widget-container .label {} .cpu-widget .widget-container .label.alt {} .cpu-widget .widget-container .icon {} /* 基于 cpu_thresholds 的状态类 */ .cpu-widget .widget-container .label.status-low {} .cpu-widget .widget-container .label.status-medium {} .cpu-widget .widget-container .label.status-high {} .cpu-widget .widget-container .label.status-critical {} /* 图标状态类 */ .cpu-widget .widget-container .icon.status-low {} .cpu-widget .widget-container .icon.status-medium {} .cpu-widget .widget-container .icon.status-high {} .cpu-widget .widget-container .icon.status-critical {} /* 进度条启用时 */ .cpu-widget .progress-container {} /* 自定义类名 */ .cpu-widget.your-class-name {} .cpu-widget.your-class-name .label {}弹窗样式弹窗根类为.cpu-popup在build_stat_popup中通过popup_class_namecpu-popup设置内部结构为.header、.graph-container、.cpu-graph、.cpu-graph-grid、.graph-title、.stats、.stat-item、.stat-label、.stat-value等。一个可直接使用的弹窗样式示例.cpu-popup { background-color: rgba(28, 28, 28, 0.7); min-width: 400px; } .cpu-popup .header { background: transparent; padding: 12px 16px; } .cpu-popup .header .text { font-size: 16px; font-family: Segoe UI; color: rgb(255, 255, 255); } .cpu-popup .header .pin-btn { font-size: 14px; background: transparent; font-family: Segoe Fluent Icons; border: none; padding: 6px; color: rgba(255, 255, 255, 0.6); } .cpu-popup .header .pin-btn:hover { color: rgba(255, 255, 255, 0.6); } .cpu-popup .header .pin-btn.pinned { color: #ffffff; } /* 曲线区 */ .cpu-popup .graph-container { background: transparent; min-height: 64px; } .cpu-popup .cpu-graph { color: #0f6bff; /* 曲线线条/填充颜色 */ } .cpu-popup .cpu-graph-grid { color: rgba(255, 255, 255, 0.05); /* 网格线颜色 */ } .cpu-popup .graph-title { font-size: 12px; color: rgba(255, 255, 255, 0.5); font-family: Segoe UI; padding: 0px 0px 4px 14px; } /* 统计卡片 */ .cpu-popup .stats { background: transparent; padding: 16px; } .cpu-popup .stats .stat-item { background-color: rgba(255, 255, 255, 0.03); border: 1px solid rgba(255, 255, 255, 0.04); border-radius: 8px; padding: 8px 12px; margin: 8px; } .cpu-popup .stats .stat-label { font-size: 13px; color: rgba(255, 255, 255, 0.65); font-family: Segoe UI; font-weight: 400; padding: 6px 4px 2px 4px; } .cpu-popup .stats .stat-value { font-size: 20px; font-weight: 700; color: #ffffff; font-family: Segoe UI; padding: 0 4px 12px 4px; }完整标签样式示例.cpu-widget { padding: 0 8px; } .cpu-widget .widget-container .label { font-size: 13px; color: #cdd6f4; } .cpu-widget .widget-container .icon { font-size: 14px; color: #89b4fa; } /* 阈值状态配色 */ .cpu-widget .widget-container .label.status-low { color: #a6e3a1; /* 绿 */ } .cpu-widget .widget-container .label.status-medium { color: #f9e2af; /* 黄 */ } .cpu-widget .widget-container .label.status-high { color: #fab387; /* 橙 */ } .cpu-widget .widget-container .label.status-critical { color: #f38ba8; /* 红 */ } /* 进度条布局调整 */ .cpu-widget .progress-container { margin-right: 6px; }仓库默认主题中也内置了.cpu-widget:hover高亮、.cpu-popup使用--yasb-popup-bg等 CSS 变量可通过主题系统覆盖参考 docs/Styling.md 与组件文档首页-Home.md) 中提到的系统色板。九、常见问题与注意事项PDH 计数器损坏CPU 组件依赖 Windows PDH API 获取实时指标。若 PDH 计数器损坏/被污染组件会返回安全默认值而非崩溃总使用率与频率显示 0、核心数回退到逻辑核心数。日志中会记录Failed to add CPU percent counter ... PDH counters may be corrupted之类的告警cpu_api.py。修复方式以管理员身份运行lodctr /r重建性能计数器或重建系统性能计数库后重启状态栏。更新间隔与性能update_interval下限为 1000ms过小的值会导致 PDH 查询过于频繁并放大 UI 刷新开销同时多个 CPU 组件实例共享一个后台 worker不会重复开线程。若状态栏存在多个高频组件还需注意bar宽度不要设为auto见 docs/Configuration.md。配置校验失败histogram_icons长度必须恰好为 9update_interval必须在 1000–60000 之间graph_history_size必须在 10–180 之间progress_bar.size与thickness分别限制在 1–200 与 1–100写入任何未在文档表格中列出的字段都会因extraforbid报错。十、延伸阅读状态栏整体结构、bars/widgets装配docs/Configuration.md全局样式与 CSS 变量系统docs/Styling.md组件与状态栏交互弹窗、进度条通用实现src/core/utils/utilities.py、src/core/utils/stat_popup.py同架构的姊妹组件使用相同弹窗/进度条体系docs/widgets/(Widget)-Memory.md-Memory.md)组件基类与回调/定时机制src/core/widgets/base.py赞分享桌面应用【免费下载链接】yasbA highly configurable Windows status bar written in Python.项目地址https://gitcode.com/gh_mirrors/yas/yasb点击查看免费下载相关推荐YASB 蓝牙组件BluetoothWidget完全指南配置、弹窗菜单与连接断开原理YASB 蓝牙组件BluetoothWidget完全指南配置、弹窗菜单与连接断开原理本指南面向使用 YASB一款高度可配置的 Windows 状态栏桌面应用ToolJet Modal 弹窗组件完全指南属性、事件、CSA 控制与源码实现ToolJet Modal 弹窗组件完全指南属性、事件、CSA 控制与源码实现本文以 ToolJet 官方文档 Modal https://link.git低代码后端前端AI 应用MCP 服务Vant Dialog 弹窗组件完全指南函数式调用、组件用法与源码级原理剖析Vant Dialog 弹窗组件完全指南函数式调用、组件用法与源码级原理剖析 Dialog 是 Vant 移动端 UI 库中负责在页面之上弹出模态框的核心组件前端UI组件上一篇QMK 固件中的 AKB VeroHHKB 配列机械键盘的构建、刷写与配置指南下一篇深入解析 Rerun 的 LineStrip3D 组件3D 折线的数据模型、Arrow 编码与可视化实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考