深入解析Airblader/i3项目中的i3bar协议规范

深入解析Airblader/i3项目中的i3bar协议规范

i3 A fork of the i3 window manager with gaps and some other features. :warning: i3-gaps has been merged into i3. 项目地址: https://gitcode.com/gh_mirrors/i31/i3

协议概述

i3bar协议是Airblader/i3窗口管理器状态栏组件与外部程序通信的标准规范。该协议采用JSON格式，为状态信息显示提供了丰富的控制选项，包括颜色、紧急状态、文本截断和交互功能等。

为什么选择JSON格式

协议设计者选择JSON作为基础格式主要基于以下技术考量：

1. 元信息分离：避免了传统状态栏工具（如dzen2、xmobar）使用的内联信号方式，将显示内容与显示属性（如颜色）明确分离
2. 易操作性：每个信息块都有明确标识，便于脚本精确修改特定内容块
3. 兼容性：支持流式处理和逐行处理两种方式，开发者可根据需求选择适合的解析策略
4. 无额外依赖：i3项目本身已依赖JSON解析库，不会增加额外负担

协议结构详解

初始头部信息

协议通信开始时必须发送一个JSON对象作为头部，包含以下字段：

{
    "version": 1,
    "stop_signal": 10,
    "cont_signal": 12,
    "click_events": true
}

• version：协议版本号（必须字段）
• stop_signal：暂停输出信号（默认SIGSTOP）
• cont_signal：继续输出信号（默认SIGCONT）
• click_events：是否启用点击事件监听

状态行数据格式

头部信息后跟随一个无限数组，每个元素代表一个完整的状态行：

[
    [
        {
            "full_text": "网络信息",
            "color": "#00ff00"
        },
        {
            "full_text": "2023-01-01 12:00:00"
        }
    ],
    ...
]

信息块属性详解

每个状态块支持以下配置属性：

核心属性

• full_text：显示的主要文本内容（必需）
• short_text：空间不足时显示的简短文本
• color：文本颜色（十六进制格式，如#00ff00）

样式控制

• background：背景色覆盖
• border：边框色覆盖
• border_*：各方向边框宽度（像素）
• min_width：最小宽度（像素或参考文本）
• align：文本对齐方式（left/center/right）

功能属性

• name/instance：块标识符（用于脚本处理）
• urgent：紧急状态标记
• separator：是否显示分隔线
• separator_block_width：分隔区域宽度
• markup：文本解析方式（none/pango）

点击事件处理

当启用click_events时，i3bar会发送JSON格式的点击事件，包含以下信息：

{
    "name": "块名称",
    "instance": "实例标识",
    "button": 鼠标按钮ID,
    "modifiers": ["修饰键列表"],
    "x": "绝对X坐标",
    "y": "绝对Y坐标",
    "relative_x": "块内相对X坐标",
    "relative_y": "块内相对Y坐标",
    "width": "块宽度",
    "height": "块高度"
}

最佳实践建议

1. 性能优化：对于简单脚本，可以考虑使用逐行处理而非流式JSON解析
2. 自定义数据：所有非协议标准字段应以下划线开头（如_custom_data）
3. 宽度控制：使用min_width配合align实现稳定的布局效果
4. 紧急状态：合理使用urgent标记重要状态变化
5. 多实例处理：为相似类型的不同实例设置不同的instance值

示例配置

以下是一个完整的状态块配置示例：

{
    "full_text": "CPU: 15%",
    "short_text": "15%",
    "color": "#ffff00",
    "background": "#222222",
    "border": "#444444",
    "min_width": "CPU: 100%",
    "align": "center",
    "name": "cpu_usage",
    "urgent": false,
    "separator": true,
    "separator_block_width": 9,
    "markup": "none"
}

通过这套协议规范，开发者可以创建高度可定制、交互性强的状态栏组件，完美融入i3窗口管理器的生态体系。

i3 A fork of the i3 window manager with gaps and some other features. :warning: i3-gaps has been merged into i3. 项目地址: https://gitcode.com/gh_mirrors/i31/i3