karinushka/paneru

## 一款适用于 MacOS 的滑动式平铺窗口管理器。 ## 关于 Paneru 是一款 MacOS 窗口管理器，它将窗口排列在一条无限延伸至右侧的条带上。其核心原则是，打开新窗口**绝不会**导致现有窗口调整大小，从而保持您的布局稳定。 每个显示器都运行着独立的窗口条带，确保窗口始终限制在各自的屏幕内，不会“溢出”到相邻的显示器上。 ## 为什么选择 Paneru？ - **在 MacOS 上体验类似 Niri 的行为：** 受 [Niri] 用户体验的启发，Paneru 旨在为 MacOS 带来类似的可滚动平铺工作流。 - **与 MacOS 工作区协同工作：** 您可以使用现有的工作区，并通过键盘或触控板手势在它们之间进行切换——每个工作区上都有独立的窗口条带。在它们之间拖放窗口同样有效。 - **虚拟工作区（实验性）：** 通过在单个空间内堆叠多个水平条带（行），将您的窗口按任务分组。使用原生的 macOS 工作区进行大类划分（例如，“工作”、“个人”），并在每个上下文中使用虚拟工作区保持井然有序。 - **MacOS 上的焦点跟随鼠标：** 对于希望避免额外点击的人来说非常有用。 - **使用触控板滑动窗口：** 使用触控板进行窗口面板导航是非常自然的操作。 - **原生 macOS 标签页支持：** 诸如 Ghostty 之类的应用程序会使用这些标签页，因此 Paneru 会像管理其他窗口一样在布局条带上管理它们。 - **为大屏幕优化：** 标准的平铺窗口管理器在大屏幕上可能表现不佳，通常会导致要么是巨大的最大化窗口，要么是众多微小且无法使用的窗口。Paneru 通过提供更灵活实用的排列方式解决了这一问题。 - **改善小屏幕的可用性：** 在较小的屏幕（如笔记本电脑）上，传统的平铺可能会使窗口变得太小而无法高效工作，迫使用户不断将其最大化。Paneru 的滑动条带方法旨在提供更好的体验，而无需这种妥协。 ## 灵感来源 其基础架构和窗口管理技术深受另一款优秀的 MacOS 窗口管理器 [Yabai] 的启发。研究其源代码为我们在 MacOS 上管理窗口提供了宝贵的见解，特别是关于未公开文档的功能。 在滑动条带上管理窗口这一创新概念直接受到了 [Niri] 和 [PaperWM.spoon] 的启发。 ## 安装说明 ### 推荐的系统选项 - 就像所有非原生的 MacOS 窗口管理器一样，Paneru 需要辅助功能权限才能移动窗口。运行后，您可能会看到一个请求权限的对话框。否则，请检查“系统设置”中“隐私与安全性 -> 辅助功能”下的设置。 - 检查您的“系统设置”中“显示器具有单独的空间”选项。该选项应被启用——这允许 Paneru 独立管理工作区。 - **多显示器。** Paneru 会将窗口移出屏幕，将它们隐藏在左侧或右侧。如果您有多个显示器，例如在连接到外部显示器时笔记本电脑处于打开状态，您可能会遇到奇怪的现象。问题在于，当 MacOS 发现窗口被移动到离屏幕太远的地方时，会将其重新定位到另一个显示器上——这会使 Paneru 产生混乱！解决方法是更改附加显示器的空间排列方式——不要将其放在主显示器的左侧或右侧，而是将其移至主显示器的上方或下方。 Aerospace 窗口管理器也存在[类似情况](https://nikitabobko.github.io/AeroSpace/guide#proper-monitor-arrangement)。 这里提供了一个选项（`horizontal_mouse_warp`），可以使垂直排列的显示器“感觉”像是水平的。 - **屏幕外的窗口边缘。** 由于 macOS 会强制重新定位完全移出屏幕的窗口，Paneru 会在屏幕边缘保留每个屏幕外窗口的一小条可见边缘。`sliver_width` 和 `sliver_height` 选项控制着这一小条边缘的大小。这是针对 macOS 限制的一种变通方法，而非设计选择。 ### 从 Crates.io 安装 Paneru 使用 Rust 的 `cargo` 构建。它可以直接从 `crates.io` 安装，或者如果您需要最新版本，可以通过从 Github 获取源代码进行安装。 ``` $ cargo install paneru ``` ### 从 Github 安装 ``` $ git clone https://github.com/karinushka/paneru.git $ cd paneru $ cargo build --release $ cargo install --path . ``` 它可以直接从命令行运行，或者作为服务运行。 请注意，您需要为该二进制文件授予辅助功能权限。 ### 使用 Homebrew 安装 如果您正在使用 Homebrew，可以通过以下 formula 进行安装： ``` $ brew install paneru ``` 或者先添加 tap，然后再按名称安装： ``` $ brew tap karinushka/paneru $ brew install paneru ``` ### 使用 Nix 安装 参见 [`nix/README.md`](/nix/README.md)。 ### 配置说明 Paneru 会在以下位置检查配置： - `$HOME/.paneru` - `$HOME/.paneru.toml` - `$XDG_CONFIG_HOME/paneru/paneru.toml` 此外，它还允许通过 `$PANERU_CONFIG` 环境变量覆盖配置路径。 您可以使用以下基本配置作为起点。有关所有可用选项、快捷键绑定和窗口规则的完整指南，请参阅**[配置指南](./CONFIGURATION.md)**。 ``` # 基础 .paneru.toml [options] focus_follows_mouse = true mouse_follows_focus = true [bindings] window_focus_west = "cmd - h" window_focus_east = "cmd - l" window_resize = "alt - r" window_center = "alt - c" quit = "ctrl + alt - q" ``` ### 实时重载 在 Paneru 运行期间，对您的 `~/.paneru` 文件所做的配置更改会被自动重新加载。这对于微调快捷键绑定和其他设置而无需重启应用程序非常有用。 ### 作为服务运行 ``` $ paneru install $ paneru start ``` ### 在前台运行 ``` $ paneru ``` ### 发送命令 Paneru 提供了一个 `send-cmd` 子命令，允许您通过 Unix 套接字（`/tmp/paneru.socket`）从命令行控制正在运行的实例。任何可以绑定到热键的命令也同样可以通过编程方式发送： ``` $ paneru send-cmd [args...] ``` #### 可用命令 | 命令 | 描述 | | -------------------------- | ------------------------------------------------ | | `window focus ` | 将焦点移至指定方向的窗口 | | `window swap ` | 将聚焦的窗口与相邻窗口交换 | | `window center` | 将聚焦的窗口居中显示在屏幕上 | | `window resize` | 在 `preset_column_widths` 中循环切换 | | `window grow` | 增长到下一个预设宽度 | | `window shrink` | 缩小到上一个预设宽度 | | `window fullwidth` | 切换聚焦窗口的全宽模式 | | `window manage` | 切换受管/浮动状态 | | `window equalize` | 在聚焦的堆栈中平均分配高度 | | `window stack` | 将聚焦的窗口堆叠在其左侧邻居之上 | | `window unstack` | 将聚焦的窗口取消堆叠至其独立的列中 | | `window nextdisplay` | 将聚焦的窗口移动到下一个显示器 | | `window nextdisplaysend` | 将窗口移动到下一个显示器，但焦点保持不变 | | `window virtual ` | 切换到上一个/下一个虚拟工作区 | | `window virtualmove ` | 将窗口移动到不同的虚拟工作区 | | `window virtualsend ` | 将窗口发送到虚拟工作区，但焦点保持不变 | | `window snap` | 将聚焦的窗口吸附到可见视口 | | `mouse nextdisplay` | 将鼠标指针瞬移到下一个显示器 | | `printstate` | 将内部 ECS 状态打印到调试日志 | | `quit` | 退出 Paneru | 其中 `` 是以下之一：`west`、`east`、`north`、`south`、`first`、`last`。 #### 示例 ``` # 向右移动焦点一个窗口。 $ paneru send-cmd window focus east # 将当前窗口向左交换。 $ paneru send-cmd window swap west # 一次性居中并调整大小（两次独立调用）。 $ paneru send-cmd window center && paneru send-cmd window resize # 反向循环预设宽度。 $ paneru send-cmd window shrink # 跳转到最左侧的窗口。 $ paneru send-cmd window focus first ``` #### 脚本编写思路 由于 `send-cmd` 通过 Unix 套接字工作，您可以从 shell 脚本、`cron` 任务或其他自动化工具驱动 Paneru： - **启动并排列工作流。** 打开一个应用程序并立即对其进行定位：`open -a Safari && sleep 0.5 && paneru send-cmd window resize`。 - **一键重置布局。** 绑定一个脚本，使焦点移至第一个窗口，调整其大小，然后向东移动并调整下一个窗口的大小——在窗口顺序被打乱后重新创建首选布局。 - **与其他工具集成。** 将来自 [Hammerspoon](https://www.hammerspoon.org) 或 [skhd](https://github.com/koekeishiya/skhd) 等工具的焦点事件通过管道传递给 `paneru send-cmd`，以实现超越单一热键的复合操作。 - **多显示器编排。** 将一个窗口移动到下一个显示器，并立即将鼠标瞬移至该处： paneru send-cmd window nextdisplay && paneru send-cmd mouse nextdisplay ## 未来的改进方向 - 提供更多用于操纵窗口的命令：精细的尺寸调整、触控板缩放等。 - 增强脚本编写能力。例如，使用 Lua 进行配置或实现窗口处理的自动化，例如触发特定窗口或应用程序并对其进行定位。 ## 交流 这里有一个公开的 Matrix 聊天室 [`#paneru:matrix.org`](https://matrix.to/#/%23paneru%3Amatrix.org)。欢迎加入并提出任何问题。 ## 架构概述 有关 Paneru 内部设计、数据流和 ECS 模式的详细高层概览，请参阅**[架构指南](./ARCHITECTURE.md)**。 Paneru 的架构围绕 **Bevy ECS（实体组件系统）** 构建，它将窗口管理器的状态作为实体（显示器、工作区、应用程序和窗口）与组件的集合进行管理。 该系统解耦为三个主要层： 1. **平台层（`src/platform/`）**：通过 `objc2` 和 Core Graphics 直接与 macOS 接口。它运行原生的 Cocoa 事件循环，并将 OS 事件推送到由 Bevy 消费的通道中。 2. **管理层（`src/manager/`）**：定义了与 OS 无关的 trait（`WindowManagerApi`、`WindowApi`），用于抽象窗口操作。针对 macOS 的特定实现（`WindowManagerOS`、`WindowOS`）将这些 trait 桥接到 Accessibility 和 SkyLight API。 3. **ECS 层（`src/ecs/`）**：应用程序的“大脑”。Bevy 系统处理传入的事件、处理输入触发器并管理动画。 ### 仓库结构 - **`main` 分支**：包含稳定的、已发布的代码。 - **`testing` 分支**：用于实验性功能和架构重构。此分支具有波动性，可能会被强制推送。 ## 其他平台的可滚动平铺方案 以下是一些实现了类似工作流的其他项目： - [Niri]：一个可滚动平铺的 Wayland 合成器。 - [PaperWM]：在 GNOME Shell 之上实现的可滚动平铺。 - [karousel]：在 KDE 之上实现的可滚动平铺。 - [papersway]：在 sway/i3 之上实现的可滚动平铺。 - [hyprscroller] 和 [hyprslidr]：在 Hyprland 之上实现的可滚动平铺。 - [PaperWM.spoon]：在 MacOS 之上实现的可滚动平铺。

标签：GUI, MacOS, MacOS窗口管理器, Tiling Window Manager, 可视化界面, 多显示器支持, 屏幕空间管理, 工作区管理, 工作效率, 平铺式窗口管理器, 桌面布局, 桌面环境增强, 滑动窗口管理, 焦点跟随鼠标, 系统工具, 虚拟工作区, 触控板手势, 通知系统