预计阅读时间：9 分钟

Hyprland 0.56：滚动布局、主窗口策略与 Lua API 同步增强

Hyprland 0.56 已正式发布。这个基于 wlroots 的动态平铺式 Wayland 合成器在本次更新中加入了多项布局能力，并继续扩展 Lua API，同时带来大量修复。对日常用户而言，最值得关注的是滚动布局和主窗口布局的行为可以配置得更细；对插件与自动化工具作者而言，API 扩展则意味着更多运行时状态能够被脚本利用。

滚动布局不只是“横向移动窗口”

本次发布为滚动相关行为新增了 fit_into_view、fit、expand 和 inhibit_scroll 等能力。它们指向同一个问题：当工作区中的窗口数量超过当前视口能够舒适容纳的范围时，合成器应该如何调整尺寸、移动视图，以及决定某个窗口是否参与滚动。

这些选项使滚动布局可以覆盖几种不同的工作方式：

希望当前窗口始终完整可见时，可以关注 fit_into_view。
需要窗口适配可用区域时，可以研究 fit 的行为。
希望特定窗口占用更多空间时，expand 提供了新的控制入口。
不希望某些窗口触发或参与滚动时，可以使用 inhibit_scroll 对行为加以限制。

具体配置位置、参数类型和默认值应以 Hyprland 0.56 随附的配置说明为准。尤其是在从旧版本升级时，不要仅凭选项名称猜测布尔值、调度器参数或窗口规则语法。

关闭主窗口后的焦点更可预测

主窗口布局新增了 focus_master_on_close。它处理的是一个很常见、也很影响操作节奏的细节：关闭当前窗口后，焦点是否回到主窗口。

在终端、编辑器和文档窗口并排工作的场景中，这项策略尤其有用。例如，主窗口固定为编辑器，临时终端和预览窗口位于栈区。关闭临时窗口后立即聚焦主窗口，可以减少一次方向键操作，也能避免焦点落到另一个短期窗口上。

是否启用它取决于实际工作流：

主窗口长期承载核心任务时，聚焦主窗口通常更自然。
经常连续处理多个栈区窗口时，保留邻近窗口焦点可能更高效。
多显示器环境还需要检查焦点切换是否符合跨工作区预期。

可以这样实践：先验证版本，再小范围调整配置

下面的脚本可以直接运行。它会检查当前 Hyprland 版本、备份用户配置，并搜索本次发布涉及的配置关键词。脚本不会自动写入未经确认的配置值，适合在升级后做第一轮核对。

#!/usr/bin/env bash
set -euo pipefail

CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/hypr/hyprland.conf"
BACKUP="${CONFIG}.bak-$(date +%Y%m%d-%H%M%S)"

echo "== Hyprland version =="
hyprctl version

if [[ ! -f "$CONFIG" ]]; then
  echo "Config not found: $CONFIG" >&2
  exit 1
fi

cp -- "$CONFIG" "$BACKUP"
echo "Backup created: $BACKUP"

echo "== Existing related settings =="
grep -nE 'fit_into_view|fit|expand|inhibit_scroll|focus_master_on_close' "$CONFIG" || true

echo "Review the Hyprland 0.56 configuration reference before adding values."
echo "After editing, reload with: hyprctl reload"

保存为 check-hyprland-056.sh 后执行：

chmod +x check-hyprland-056.sh
./check-hyprland-056.sh

确认本机 0.56 文档中的配置层级和取值后，可以按下面的思路改造配置。这里的段落位置是示意，重点是逐项启用并观察行为，不应把未确认的值一次性投入主配置：

# 示例思路：请按照 Hyprland 0.56 本机文档确认所属配置段和取值类型。
# 滚动布局：逐项评估 fit_into_view、fit、expand、inhibit_scroll。
# 主窗口布局：评估 focus_master_on_close 是否符合你的焦点习惯。

每次只修改一个选项，然后重新加载并观察日志：

hyprctl reload
hyprctl activeworkspace
hyprctl activewindow

如果会话出现异常，可立即恢复备份：

CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/hypr/hyprland.conf"
cp -- "$(ls -1t "${CONFIG}".bak-* | head -n 1)" "$CONFIG"
hyprctl reload

Lua API 扩展对自动化意味着什么

0.56 还扩展了 Lua API，摘要中明确提到了 change_id、工作区 API，以及名称以 get_load... 开头的新接口。由于现有信息没有给出完整函数签名、返回值和生命周期约束，不宜据此编造可执行调用代码。

从工程角度看，这类 API 扩展通常会影响三类组件：

根据工作区状态执行动作的自动化脚本。
需要追踪对象标识变化的插件。
查询已加载组件或运行时状态的诊断工具。

升级插件前应检查 API 是否仅新增能力，还是同时改变了对象标识、错误处理或事件顺序。Lua 脚本还应对接口缺失和空返回值做防御性处理，避免脚本错误拖累整个桌面会话。

可以采用下面的兼容性模式改造脚本。代码是通用 Lua 示例，其中 hypr_api 需要替换为插件实际注入的 API 对象：

-- 假设插件把 Hyprland API 暴露为全局对象 hypr_api。
-- 函数名和参数必须按 0.56 的正式 API 文档替换。
local function call_if_available(api, method, ...)
  if type(api) ~= "table" or type(api[method]) ~= "function" then
    return nil, "API method unavailable: " .. method
  end

  local ok, result = pcall(api[method], ...)
  if not ok then
    return nil, result
  end
  return result, nil
end

local result, err = call_if_available(hypr_api, "get_loaded_plugins")
if err then
  io.stderr:write(err .. "\n")
else
  print("API call completed")
end

这里的关键不是假设 get_loaded_plugins 一定是最终名称，而是先检测方法是否存在，再用 pcall 隔离运行时错误。这样同一份脚本更容易同时兼容升级前后的环境。

升级时应控制变量

Hyprland 属于桌面会话的核心组件，布局、插件和脚本通常同时参与焦点管理。升级 0.56 时，建议先备份配置，在无关键任务的会话中验证，并暂时停用尚未声明兼容的新旧插件。

一个稳妥的检查顺序是：确认 hyprctl version，执行一次无改动启动，检查现有窗口规则，再逐项启用滚动布局能力和 focus_master_on_close。Lua 插件则应单独验证接口存在性、错误处理与重新加载行为。新功能能够改善操作流，但只有在配置语义和插件兼容性都明确后，才适合成为日常桌面默认设置。

Hyprland 0.56 发布：滚动布局、主窗口策略与 Lua API 同步增强