桌面应用【免费下载链接】polybarA fast and easy-to-use status bar项目地址https://gitcode.com/gh_mirrors/po/polybar点击查看免费下载Actions动作是 polybar 用于触发模块特定行为的一套机制——无论是点击音量模块时静音/取消静音还是通过 IPC 消息远程切换工作区底层都是动作字符串在起作用。本文以 doc/user/actions.rst 为核心骨架结合仓库源码系统讲解动作字符串的格式规范、四种触发途径、全部内置模块的可用动作以及 3.5.0 版本以来旧动作名的迁移方案。什么是 ActionsActions 用来触发模块中的特定行为。例如当你点击音量模块pulseaudio或alsa时polybar 内部会向该模块发送一个动作告诉它静音/取消静音。这些动作不仅用于内部事件用户还可以通过进程间通信IPC将动作发送给 polybar从而远程触发模块行为。IPC 的完整说明见 doc/user/ipc.rst。从源码上看动作的分发链路非常清晰controller.cpp 中的process_inputdata处理所有输入命令凡是#开头的命令一律视为动作字符串经actions_util::parse_action_string解析后交给forward_action分发forward_action会遍历所有模块把动作投递给所有名字匹配的模块controller.cpp。动作字符串格式一个动作字符串遵循如下格式#NAME.ACTION[.DATA]NAME目标模块的名字注意是名字不是类型ACTION该模块中动作的名称DATA附加到动作上的可选数据例如指定要打开菜单的哪一级基础示例date 模块的 toggle以 date 模块 为例它支持toggle动作用于在常规时间格式与替代时间格式date/time与date-alt/time-alt之间切换。假设你配置了如下 date 模块[module/mydate] type internal/date ...那么切换日期格式的动作字符串为#mydate.toggle注意这里使用的是模块名字mydate而不是类型internal/date。在源码中actions.cpp 的get_action_string负责构造动作字符串# module_name . action若存在 data 则再追加. data。对应的解析函数parse_action_stringactions.cpp会按.分割出模块名、动作名和数据并校验模块名不得为空动作名不得为空等约束——这正是格式规范在实现层面的落点。带数据的示例menu 模块的 open以 menu 模块为例假设配置如下[module/powermenu] type custom/menu menu-0-0 Poweroff menu-0-0-exec poweroff menu-0-1 Suspend menu-0-1-exec systemctl suspend打开某个菜单级别的动作名是open要打开第 0 级menu-0动作字符串需要附加级别数据#powermenu.open.0触发动作的四种方式大多数模块默认已经通过点击/滚轮事件使用动作字符串但在某些场景下你可能需要手动向 polybar 发送动作字符串。1. 在 bar 配置中绑定点击事件任何可以指定点击/滚动时执行命令的位置都可以换成动作字符串。例如在 bar 段中可以指定点击 bar 空白处无其他点击动作的区域时触发的命令[bar/mybar] ... click-left #mydate.toggle ...这样点击 bar 任意空白处就会触发mydate模块的toggle动作。2. 在%{A}格式标签中使用%{A}格式化标签详见 格式化标签 相关文档同样支持动作字符串用法与普通命令一致%{A1:firefox:}%{A3:#mydate.toggle:}Opens firefox on left-click and toggles the date on right-click %{A}%{A}上面的例子中左键点击打开 firefox右键点击切换日期格式。3. 通过 IPC 消息触发polybar 的进程间通信IPC机制也可以触发动作使用polybar-msg工具polybar-msg action #mydate.toggle注意动作字符串两边的引号是必需的否则 shell 会把#当作注释起始符忽略该行剩余内容。关于 IPC 的更完整用法如 hook、send 等参见 doc/user/ipc.rst。4. 模块内部点击/滚动从源码结构看模块自身的点击与滚动事件也是通过动作字符串实现的模块在构造函数中通过m_router-register_action(...)注册动作回调见 base.inl 中所有模块注册module_toggle/module_show/module_hide的示例渲染时再由 action_router.cpp 的invoke根据动作名查找并执行对应回调。点击事件经 builder.cpp 的action()方法编码为动作字符串写入输出形成点击 → 动作字符串 → 路由 → 回调的完整闭环。可用动作总览以下模块提供动作其中大部分已被模块默认用于点击和滚轮事件。所有模块通用module_前缀以下动作对所有模块可用均以module_为前缀动作说明module_show显示模块。隐藏时模块仍在后台运行只是不绘制。初始状态可由hidden配置项控制3.6.0 新增module_hide隐藏模块。模块仍在后台运行只是不绘制。初始状态可由hidden配置项控制3.6.0 新增module_toggle切换模块的可见性3.6.0 新增源码佐证在 base.inl 中每个模块构造时都会注册这三个动作base.hpp 定义了对应的常量EVENT_MODULE_TOGGLE/EVENT_MODULE_SHOW/EVENT_MODULE_HIDE实现逻辑见 base.inl——set_visible决定模块是否被绘制而模块自身的运行循环并不停止。hidden配置项在 base.inl 中读取m_visible(!m_conf.get(m_name, hidden, false))。internal/date动作说明toggle在date/time与date-alt/time-alt之间切换日期时间格式源码中该动作在 date.cpp 注册。internal/alsa动作说明inc/dec按配置项interval的百分比数值增加/减小音量。这样调整的音量永远不会超过 100%。若开启了unmute-on-scroll调用此动作时还会同时取消静音toggle在静音与非静音之间切换源码中这些动作在 alsa.cpp 注册且仅在m_handle_events为 true 时注册即handle-events配置项控制动作是否可用。internal/pulseaudio动作说明inc/dec按配置项interval的百分比数值增加/减小音量。若use-ui-max设为true音量最高可达约 153%否则最高 100%。若开启了unmute-on-scroll调用此动作时还会同时取消静音toggle在静音与非静音之间切换internal/xbacklight动作说明inc/dec每次增加/减小屏幕亮度 5 个百分点internal/backlight动作说明inc/dec每次增加/减小屏幕亮度 5 个百分点源码中 backlight 的动作注册见 backlight.cpp。internal/xkeyboard动作说明switch循环切换已配置的键盘布局internal/mpd动作说明play开始播放当前歌曲pause暂停当前歌曲stop停止播放prev开始播放上一首歌曲next开始播放下一首歌曲repeat切换重复模式single切换单曲模式random切换随机模式consume切换消费模式seek带数据在当前歌曲内跳转seek的数据必须形如[-]N其中N是 0 到 100 之间的数字若使用或-则从当前位置向前/向后跳转N%相对于歌曲总长度否则跳转到当前歌曲的N%位置。源码中 MPD 的全部动作在 mpd.cpp 一次性注册其中seek通过register_action_with_data注册。internal/xworkspaces动作说明focus带数据切换到指定工作区。数据是应选中的工作区索引next切换到下一个工作区。行为受pin-workspaces设置影响prev切换到上一个工作区。行为受pin-workspaces设置影响internal/bspwm动作说明focus带数据切换到指定工作区。数据形如NM其中N是显示器索引M是该显示器上的工作区索引。两个索引均从 0 开始对应它们在bspc subscribe report输出中的位置next切换到下一个工作区。行为受pin-workspaces设置影响prev切换到上一个工作区。行为受pin-workspaces设置影响源码中 bspwm 的focus通过register_action_with_data注册next/prev通过register_action注册bspwm.cpp。internal/i3动作说明focus带数据切换到指定工作区。数据是在 i3 配置中定义的工作区名称next切换到下一个工作区。行为受pin-workspaces设置影响prev切换到上一个工作区。行为受pin-workspaces设置影响源码中 i3 的动作注册方式与 bspwm 相同i3.cpp。custom/menu动作说明open带数据打开指定菜单级别。数据是单个数字指定要打开哪一级菜单close关闭菜单exec带数据执行指定菜单元素处的命令。数据形如N-M动作将执行menu-N-M-exec中的命令菜单模块的底层结构见 menu.cpp模块按menu-level-index的命名规则逐级解析菜单树每个菜单项通过menu-level-index-exec指定要执行的命令默认动作是close见 menu.cpp。三个动作在 menu.cpp 注册。custom/ipc3.6.0 新增。这类模块专门用于通过 IPC 交互动作说明send带数据用传入动作的数据替换模块内容hook带数据触发指定 hook。数据是待触发 hook 的 0 基索引next切换到下一个 hook显示最后一个 hook 后循环回第一个prev切换到上一个 hook显示第一个 hook 后循环回最后一个reset将模块重置为启动状态要么为空要么按照initial设置源码中 ipc 模块注册了全部五个动作ipc.cpp其中send和hook带数据。已弃用的动作名称弃用于 3.5.0 版本。在早期版本 3.5.0中动作字符串只包含模块类型信息。这意味着当 bar 中包含多个同类型模块时这些模块的动作有时会被同类型的其他模块错误处理。自 3.5.0 起这个问题不再发生。但这也意味着 polybar 模块识别的动作名称发生了变化。如果你在配置或脚本中显式使用了任何旧版 polybar 动作名称建议尽快修改因为它们可能在未来的某个版本停止工作。目前 polybar 仍支持旧动作名称会将其转换为对应的新动作名称并打印警告以帮助你定位配置中的旧动作名称。从源码看这一兼容逻辑实现在 controller.cpp 的try_forward_legacy_action中它维护了一张legacy_actions映射表如volup → alsa 模块的 EVENT_INC、mpdseek → mpd 模块的 EVENT_SEEK将旧名称以前缀匹配方式命中后自动转换为#模块名.新动作名[.数据]并投递给第一个匹配类型的模块同时打印警告日志。源码注释中的TODO Remove when deprecated action names are removed表明这段兼容代码未来会被移除。如果你使用 menu 模块很可能会用到旧的menu-open-1或menu-close之类的动作名称i3wm-wsnext、i3wm-wsprev、bspwm-desknext、bspwm-deskprev等切换 i3/bspwm 工作区的动作也可能出现在你的配置中。迁移步骤更新配置使用新动作名称相当直接对照下表为每个动作名称找到对应的新动作名称按上文动作字符串格式一节所述构造完整的动作字符串参考下文menu 模块迁移示例完成典型 menu 模块的迁移。完整对照表如下模块类型旧动作名新动作名internal/datedatetoggletoggleinternal/alsavolupincvoldowndecvolmutetoggleinternal/pulseaudiopa_volupincpa_voldowndecpa_volmutetoggleinternal/xbacklightxbacklightincxbacklight-decinternal/backlightbacklightincbacklight-decinternal/xkeyboardxkeyboard/switchswitchinternal/mpdmpdplayplaympdpausepausempdstopstopmpdprevprevmpdnextnextmpdrepeatrepeatmpdsinglesinglempdrandomrandommpdconsumeconsumempdseekNseek.Ninternal/xworkspacesxworkspaces-focusNfocus.Nxworkspaces-nextnextxworkspaces-prevprevinternal/bspwmbspwm-deskfocusNfocus.Nbspwm-desknextnextbspwm-deskprevprevinternal/i3i3wm-wsfocus-Nfocus.Ni3-wsnextnexti3-wsprevprevcustom/menumenu-open-Nopen.Nmenu-closeclose注意部分旧动作名称以N为后缀表示该动作带有额外数据由N表示。在新动作名称中这些数据以完全相同的方式出现在句点之后。menu 模块迁移示例menu 模块是唯一一个必须显式使用动作才能正常工作的模块。因此几乎每个人都需要更新他们的 menu 模块以使用新的动作格式。下面是一个 menu 模块示例[module/apps] type custom/menu label-open Apps menu-0-0 Browsers menu-0-0-exec menu-open-1 menu-0-1 Multimedia menu-0-1-exec menu-open-2 menu-1-0 Firefox menu-1-0-exec firefox menu-1-1 Chromium menu-1-1-exec chromium menu-2-0 Gimp menu-2-0-exec gimp menu-2-1 Scrot menu-2-1-exec scrot该模块使用了两个旧动作menu-open-1和menu-open-2。它们是带数据的动作数据指定应打开菜单的哪一级。对照迁移表menu-open-N的新动作名是open.N其中.N是附加在动作上的数据。结合模块名得到动作字符串#apps.open.1和#apps.open.2。由于你的 menu 模块很可能使用不同的名字实际动作字符串一般不会使用apps而是你自己的模块名。迁移后的配置[module/apps] type custom/menu label-open Apps menu-0-0 Browsers menu-0-0-exec #apps.open.1 menu-0-1 Multimedia menu-0-1-exec #apps.open.2 menu-1-0 Firefox menu-1-0-exec firefox menu-1-1 Chromium menu-1-1-exec chromium menu-2-0 Gimp menu-2-0-exec gimp menu-2-1 Scrot menu-2-1-exec scrot延伸阅读IPC 完整使用指南doc/user/ipc.rst各模块的配置选项与格式标签doc/user/modules/index.rst 与 doc/user/modules/defs.rst动作路由器的实现细节src/utils/action_router.cpp 与 include/utils/action_router.hpp动作字符串的构造与解析src/utils/actions.cpp 与 include/utils/actions.hpp动作分发的入口src/components/controller.cpp通过理解动作字符串的格式与分发机制你可以把 bar 的点击、滚轮、%{A}标签与 IPC 消息统一在同一套动作语言之下进而用polybar-msg编写自己的远程控制脚本或构造出多层嵌套的自定义菜单。赞分享桌面应用【免费下载链接】polybarA fast and easy-to-use status bar项目地址https://gitcode.com/gh_mirrors/po/polybar点击查看免费下载相关推荐Starship 配置完全指南starship.toml 语法、格式字符串与内置模块详解Starship 配置完全指南starship.toml 语法、格式字符串与内置模块详解 本指南以 starship 官方配置文档为核心系统讲解从创建 ~/CLI开发工具Polybar 动作系统详解模块交互与控制指南Polybar 动作系统详解模块交互与控制指南 Polybar 作为一款轻量级状态栏工具其强大的动作系统Actions为用户提供了丰富的模块交互方式。本桌面应用EarlyBird部署方案对比本地安装、容器化部署与云原生架构EarlyBird部署方案对比本地安装、容器化部署与云原生架构 EarlyBird作为一款强大的敏感数据检测工具能够扫描源代码仓库中的明文密码违规、个人身份创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考