Zellij 主题设置与 YAML 配置迁移

Zellij 提供了丰富的主题系统，从内置的数十种配色方案到完全自定义的颜色配置。同时，Zellij 经历了从 YAML 到 KDL 的配置格式迁移。本文将介绍主题设置方法、明暗主题切换、CLI 配置选项，以及从旧版 YAML 配置迁移到 KDL 格式的完整指南。

一、内置主题

Zellij 内置了大量流行配色方案，你只需在 config.kdl 中指定主题名称即可启用：

// ~/.config/zellij/config.kdl
theme "dracula"

以下是 Zellij 内置的主要主题列表：

主题名称	风格
default	Zellij 默认配色
dracula	经典暗色主题，紫色调
solarized-dark	Solarized 暗色版本
solarized-light	Solarized 亮色版本
gruvbox / gruvbox-dark	暖色调复古暗色主题
nord	北欧风冷色调暗色主题
catppuccin-latte	Catppuccin 亮色版本
catppuccin-frappe	Catppuccin 中间色调
catppuccin-macchiato	Catppuccin 较深色调
catppuccin-mocha	Catppuccin 最深暗色版本
tokyo-night / tokyo-night-dark	Tokyo Night 暗色主题
tokyo-night-light	Tokyo Night 亮色版本
tokyo-night-storm	Tokyo Night 风暴变体
everforest	森林绿自然色调暗色主题
one-dark	One Dark 配色方案
rose-pine	Rose Pine 主版本
rose-pine-dawn	Rose Pine 晨曦亮色版本
rose-pine-moon	Rose Pine 月光变体

以上只是部分主题，Zellij 还包含更多配色方案。你可以在 Zellij 官方仓库的 themes 目录中查看完整列表。

二、自定义主题

如果内置主题不能满足你的需求，Zellij 允许你创建完全自定义的配色方案。

在配置文件中定义

在 config.kdl 的 themes 块中定义自定义主题：

// ~/.config/zellij/config.kdl
themes {
    my-theme {
        fg "#c0caf5"
        bg "#1a1b26"
        black "#15161e"
        red "#f7768e"
        green "#9ece6a"
        yellow "#e0af68"
        blue "#7aa2f7"
        magenta "#bb9af7"
        cyan "#7dcfff"
        white "#a9b1d6"
        orange "#ff9e64"
    }
}

theme "my-theme"

UI 组件颜色

除了基本的 16 色外，你还可以自定义 Zellij UI 组件的颜色：

themes {
    my-theme {
        // ...基本颜色...

        // UI 组件颜色
        text_unselected "#c0caf5"
        ribbon_selected "#1a1b26" "bold"
        ribbon_unselected "#565f89"
        tab_active_background "#1a1b26"
        tab_inactive_background "#15161e"
    }
}

可自定义的 UI 组件包括标签栏、状态栏、面板边框等几乎所有可见元素的颜色。

主题文件目录

除了在主配置文件中定义主题，你还可以将主题保存为独立的文件，放在主题目录中：

~/.config/zellij/themes/my-theme.kdl

每个主题文件就是一个 themes 块中的主题定义内容。这种方式便于管理和分享主题。

三、明暗主题切换

Zellij 支持根据系统偏好自动切换明暗主题，也支持手动切换。

配置自动切换

在 config.kdl 中分别指定暗色和亮色主题：

theme_dark "dracula"
theme_light "solarized-light"

当使用 theme_dark 和 theme_light 时，不要同时使用 theme 选项，否则会冲突。

运行时手动切换

Zellij 提供了三个操作来在运行时切换主题：

操作	说明
SetDarkTheme	切换到暗色主题
SetLightTheme	切换到亮色主题
ToggleTheme	在明暗主题之间切换

你可以将这些操作绑定到快捷键上：

keybinds {
    shared {
        bind "F12" { ToggleTheme; }
    }
}

这样按 F12 就可以在暗色和亮色主题之间快速切换，非常方便。

四、CLI 配置

除了配置文件，许多 Zellij 选项也可以通过命令行参数设置，这在临时调试或脚本场景中非常有用：

# 指定主题
zellij options --theme dracula

# 指定默认 shell
zellij options --default-shell /bin/fish

# 启用/禁用鼠标模式
zellij options --mouse-mode true

# 设置默认布局
zellij options --default-layout compact

# 设置默认模式
zellij options --default-mode locked

# 禁用会话序列化
zellij options --session-serialization false

生成 Shell 补全

Zellij 可以为常见的 Shell 生成自动补全脚本，提升命令行使用体验：

# Bash
zellij setup --generate-completion bash > ~/.local/share/bash-completion/completions/zellij

# Zsh
zellij setup --generate-completion zsh > ~/.zfunc/_zellij

# Fish
zellij setup --generate-completion fish > ~/.config/fish/completions/zellij.fish

生成后重新加载 shell 配置即可使用 Tab 键自动补全 Zellij 的命令和选项。

五、从 YAML 迁移到 KDL

Zellij 早期版本使用 YAML 作为配置格式，后来迁移到了 KDL。如果你有旧版的 YAML 配置，需要进行迁移。

自动迁移

Zellij 提供了自动迁移命令，可以将 YAML 配置直接转换为 KDL 格式：

zellij setup --migrate-config < /path/to/old-config.yaml

该命令会读取 YAML 配置并输出等效的 KDL 配置到标准输出。你可以将输出重定向到新配置文件：

zellij setup --migrate-config < ~/.config/zellij/old-config.yaml > ~/.config/zellij/config.kdl

手动迁移

如果自动迁移不完全满足需求，你也可以手动转换。以下是两种格式的对比：

特性	YAML 格式	KDL 格式
注释	# 注释	// 注释
键值对	key: value	key "value"
布尔值	mouse_mode: true	mouse_mode true
嵌套块	缩进层级	name { ... }
列表项	- item	多行同名节点或数组参数

布局迁移示例

布局文件的迁移遵循相同的格式转换规则。以下是对比示例：

旧版 YAML 布局：

# layout.yaml
session_name: dev
tabs:
  - name: editor
    panes:
      - vim
      - npm run watch
  - name: server
    panes:
      - npm run dev

新版 KDL 布局：

// layout.kdl
layout {
    tab name="editor" {
        pane {
            command "vim"
        }
        pane {
            command "npm"
            args "run" "watch"
        }
    }
    tab name="server" {
        pane {
            command "npm"
            args "run" "dev"
        }
    }
}

KDL 格式虽然比 YAML 稍显冗长，但它的结构更加明确，避免了 YAML 的缩进敏感性问题，且对嵌套层级有更清晰的表达。迁移完成后，建议使用 zellij setup --check 验证新配置文件的语法是否正确。