plugins.md

插件系统

Piri 支持插件系统，允许你扩展功能。插件在守护进程模式下自动运行。

可用插件

Scratchpads

强大的窗口管理功能，允许你快速显示和隐藏常用应用程序的窗口。支持跨工作区和跨显示器功能。

主要特性：

• 快速显示/隐藏常用应用程序
• 跨工作区和跨显示器支持
• 可自定义出现方向和大小

Empty 插件

在切换到特定空工作区时执行命令。用于自动化工作流程，例如在空工作区中自动启动应用程序。

主要特性：

• 在空工作区上自动执行命令
• 基于工作区的配置
• 类似于 Hyprland 的 on-created-empty 工作区规则

Mark 插件

为窗口设置命名标记，通过 piri mark … 绑定当前焦点窗口或跳回已标记窗口。绑定仅存于守护进程内存，无需在配置中为每个标记单独建表。

主要特性：

• toggle / add / delete 三种操作
• 适合与 Niri spawn 或启动器组合使用

Sticky 插件

将一个浮动窗口固定为“跟随窗口”，在焦点工作区切换时自动跟随。适合常驻小工具窗口。

主要特性：

• add / delete 两个命令
• --cross 控制是否跨显示器跟随
• 仅支持 floating 窗口

Window Rule 插件

根据窗口的 app_id 或 title 自动将窗口移动到指定的工作区。用于自动化窗口管理和组织应用程序。

主要特性：

• 自动将窗口分配到工作区
• 通过 app_id 或 title 匹配（支持正则表达式）
• 类似于 Hyprland 的窗口规则

Autofill 插件

在窗口关闭或布局改变时，自动将最后一列窗口对齐到最右侧位置。有助于保持整洁有序的窗口布局。

主要特性：

• 纯事件驱动，实时对齐
• 零配置，开箱即用
• 聚焦保持 - 保持用户聚焦的窗口
• 工作区感知操作

通用配置说明

窗口匹配机制

多个插件（如 window_rule、singleton、scratchpads）使用统一的窗口匹配机制，支持通过正则表达式匹配窗口的 app_id 和 title。

关键特性：

• 支持完整的正则表达式语法
• 可以匹配 app_id 或 title，或两者组合（OR 逻辑）
• 特殊字符需要转义（如 . 需要写成 \\.）

详细说明: 关于窗口匹配机制的完整文档，请参阅 窗口匹配机制文档

Workspace 标识符

多个插件支持通过工作区名称或索引来指定目标工作区：

• name: 工作区名称，如 "main", "work", "dev"
• idx: 工作区索引（1-based），如 "1", "2"

匹配顺序：name 优先，然后 idx。插件自动识别类型并支持跨类型匹配。

插件控制

你可以在配置文件中控制哪些插件启用或禁用：

[piri.plugins]
scratchpads = true
empty = true
window_rule = true
workspace_rule = true
singleton = true
window_order = true
swallow = true
mark = true
sticky = true

默认行为：

• 如果未明确指定，插件默认禁用（false）
• 必须显式将对应项设为 true 来启用插件
• window_rule 插件例外：如果配置了窗口规则，默认启用（除非显式设置为 false）