企业官网建设流程全解析

niri 手势配置详解：拖放边缘滚动与热角（gestures 配置段）实战指南

【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri

导读

gestures是 niri 滚动平铺 Wayland 合成器中的全局手势配置段，负责调节两类核心手势的行为：拖放（DnD）时的边缘触发滚动/工作区切换，以及用于呼出 Overview 的屏幕热角（hot corners）。本文以官方配置文档为主体，结合niri-config解析实现与合成器源码中的手势状态机，完整讲解每个配置项的默认值、取值范围与底层生效逻辑，并给出可直接复制使用的 KDL 配置示例，帮助你精确调校 niri 的鼠标/触摸屏交互手感。

gestures 配置段速览

gestures配置段自 niri25.02版本引入，整体结构如下（默认值与官方文档一致）：

gestures { dnd-edge-view-scroll { trigger-width 30 delay-ms 100 max-speed 1500 } dnd-edge-workspace-switch { trigger-height 50 delay-ms 100 max-speed 1500 } hot-corners { // off top-left // top-right // bottom-left // bottom-right } }

从源码结构看，该段落在配置解析层由 niri-config/src/gestures.rs 中的GesturesPart描述：三个子块均为可选（Option），并通过MergeWith与全局默认值合并，因此你只需写出想覆盖的键，未写出的部分沿用默认值。其中dnd-edge-view-scroll的默认trigger-width: 30.取自 GTK 4 的对应取值（源码注释原文："Taken from GTK 4."）。

关于 niri 全部内置手势（鼠标、触摸板、触摸屏、数位板上的交互式移动/缩放、工作区滑动等）的总览，可查阅 docs/wiki/Gestures.md；下文聚焦gestures配置段可以调校的三个部分。

dnd-edge-view-scroll：拖放时边缘滚动平铺视图

引入版本：25.02

拖拽过程中（例如从文件管理器拖文件、或以交互式移动方式拖动窗口瞄准平铺布局）把鼠标光标顶到显示器边缘，平铺视图会随之横向滚动。该手势同样适用于触摸屏，触摸/指针设备通用。

配置项

• trigger-width：靠近显示器边缘的触发区域宽度，单位逻辑像素（logical pixels）。鼠标进入该区域即开始产生滚动意图，默认30。
• delay-ms：开始滚动前的延迟，单位毫秒，默认100。其作用是避免跨显示器拖拽时误触发滚动——短暂停留在边缘但很快离开不会启动滚动。
• max-speed：最大滚动速度，单位逻辑像素/秒，默认1500。滚动速度随光标从trigger-width边界移向显示器最边缘而线性增大：光标越贴近边缘，滚动越快。

实战示例：加大触发区与最大速度

gestures { // Increase the trigger area and maximum speed. dnd-edge-view-scroll { trigger-width 100 max-speed 3000 } }

多显示器用户通常需要更大的trigger-width以便从容跨越屏幕边界；大分辨率下也可相应提高max-speed以缩短长距离滚动时间。

源码级原理

合成器端的手势实现在 src/layout/scrolling.rs 的dnd_scroll_gesture_scroll()（L3129-L3201），工作区层面的归一化计算位于 src/layout/workspace.rs：

1. 归一化：光标在工作区内的横向位置x被 clamp 到[0, width]，trigger_width被 clamp 到width / 2以内；随后把"进入触发区的深度"除以trigger_width，得到[0, 1]的归一化强度，再乘以传入的speed。这正对应文档所述的"速度线性递增"。
2. 延迟生效：dnd_scroll_gesture_begin()（L3076-L3099）启动手势后，记录dnd_nonzero_start_time；只有当now - nonzero_start >= delay_ms（Duration::from_millis(u64::from(config.delay_ms))）时滚动才真正开始推进（L3150-L3157）。
3. 速度应用与边界钳制：实际增量按delta * time_delta * max_speed折算（L3159-L3161），最终视图偏移会被钳制在当前列布局的左右边界内（考虑 gaps 与活动列位置），防止拖出可见范围。

dnd-edge-workspace-switch：Overview 中拖放时切换工作区

引入版本：25.05

在Overview（总览视图）中拖拽时，把鼠标顶到显示器上边缘或下边缘，工作区会向上/向下滚动切换。同样适用于触摸屏。

配置项

• trigger-height：靠近显示器边缘的触发区域高度，单位逻辑像素，默认50。
• delay-ms：开始滚动前的延迟（毫秒），默认100，作用同样是避免跨显示器拖拽误触发。
• max-speed：最大滚动速度，默认1500，其中1500 对应每秒一个屏幕高度。速度同样随光标从trigger-width（此处指触发区边界）移向最边缘而线性增大。

实战示例

gestures { // Increase the trigger area and maximum speed. dnd-edge-workspace-switch { trigger-height 100 max-speed 3000 } }

源码级原理

该手势在 src/layout/monitor.rs 的dnd_scroll_gesture_scroll()中实现，与视图滚动共享同一套归一化思路，但有两个关键差异：

• 横向受限：滚动只在与工作区条（workspace strip）对应的横向范围内生效，x超出[0, width]（width = view_size.w * overview_zoom）即返回零增量。源码注释明确说明这是"为避免使用热角后或横向滚动时产生意外触发"（L1963-L1966）。
• 工作区感知：纵向位置y相对**工作区（working area）**计算（L1968-L1970），这样 layer-shell 的 dock/面板等组件不会妨碍边缘触发；trigger_height同样被 clamp 到height / 2以内。

hot-corners：热角呼出 Overview

引入版本：25.05（可自定义具体角落：25.11）

把鼠标放到显示器最左上角即可切换（开/关）Overview，拖拽过程中同样有效。

基础用法：整体开关

off关闭所有热角：

// Disable the hot corners. gestures { hot-corners { off } }

选择具体角落（25.11+）

按名称启用指定热角：top-left、top-right、bottom-left、bottom-right。若未显式写出任何角落，默认启用top-left（见下文源码佐证）。例如启用右上与右下：

// Enable the top-right and bottom-right hot corners. gestures { hot-corners { top-right bottom-right } }

按输出（per-output）覆盖热角

热角还可以在输出（output）配置中逐显示器定制，见 docs/wiki/Configuration:-Outputs.md#hot-corners。未在某个输出上定制时，回退使用gestures段的全局热角设置。典型场景：主显示器用热角，副显示器禁用：

// Enable the bottom-left and bottom-right hot corners on HDMI-A-1. output "HDMI-A-1" { hot-corners { bottom-left bottom-right } } // Disable the hot corners on DP-2. output "DP-2" { hot-corners { off } }

源码级原理

热角判定集中在 src/niri.rs 的is_inside_hot_corner()，其逻辑精确印证了文档的每一条说明：

1. 优先级：先查当前输出名对应的output配置里是否写了hot-corners，有则使用，否则回退到全局config.gestures.hot_corners（L3093-L3098）。
2. off短路：hot_corners.off为真时直接返回false（L3100-L3102）。
3. 1×1 逻辑像素命中：对右上、左下、右下三个角落分别用Rectangle::new(corner, Size::new(1., 1.)).contains(pos)判定——即光标必须落在该角落最边缘的 1×1 逻辑像素内（L3109-L3121）。
4. 默认 top-left：对左上角，判定条件是top_left为真，或四个角落均未显式启用（L3123-L3129），这正实现了文档所说的"未显式设置时默认启用 top-left"。

此外，热角位置还被用于is_sticky_obscured_under()（L3177），即指针处于热角区域时会被视为遮挡顶层内容，从而保证 Overview 切换不会被表层界面拦截。

配置生效与注意事项

• 配置合并语义：gestures段的子块与全局默认值按MergeWith逐字段合并，且支持通过include机制分片覆盖（相关合并工具见 niri-config/src/utils/merge_with.rs）。因此增量写法（只改一个键）是安全的。
• 取值范围：从 niri-config/src/gestures.rs 的解析类型可见，trigger-width/trigger-height接受FloatOrInt<0, 65535>（0～65535，可为小数），max-speed接受FloatOrInt<0, 1_000_000>，delay-ms为u16（0～65535 毫秒）。极端小值（如trigger-width 0）会被源码中的 sanity check 直接归零处理（src/layout/workspace.rs），不会产生异常滚动。
• 判定基准：视图滚动与工作区切换的触发区均相对**工作区（working area）**计算，层叠的面板（layer-shell dock 等）不影响边缘触发；而热角基于输出几何（output geometry）计算。
• 触摸屏：两类 DnD 边缘滚动均适用于触摸屏；交互式移动窗口时，横向拖动平铺窗口会优先滚动视图而非移动窗口（详见 docs/wiki/Gestures.md）。

修改配置后需重载配置（niri 支持运行时niri msg action reload-config或发送 SIGHUP 重载，具体以 docs/wiki/Configuration:-Introduction.md 为准）即可让新的手势参数生效，无需重启合成器。

【免费下载链接】niriA scrollable-tiling Wayland compositor.项目地址: https://gitcode.com/GitHub_Trending/ni/niri