wezterm.mux.get_workspace_names() 用法详解：在 Rust 终端模拟器中枚举全部工作区

wezterm.mux.get_workspace_names() 用法详解：在 Rust 终端模拟器中枚举全部工作区

【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm

wezterm.mux.get_workspace_names()是 wezterm 提供的 Lua API，用于从多路复用层（mux）获取当前已知的全部工作区（workspace）名称列表。本文以 docs/config/lua/wezterm.mux/get_workspace_names.md 为主干，结合仓库源码（lua-api-crates/mux/src/lib.rs 与 mux/src/lib.rs）讲解其用法、底层实现、返回值特性，以及与工作区相关的配套 API 组合示例。读完本文，你将掌握枚举工作区、判断工作区是否存在、配合切换与重命名实现完整工作区管理的能力。

函数签名与版本要求

wezterm.mux.get_workspace_names()

该函数自20220624-141144-bd1b7c5d版本起可用（原文档以{{since('20220624-141144-bd1b7c5d')}}标注，该版本即 2022 年 6 月 24 日发布的 wezterm 20220624 nightly）。

返回值：一个 Lua table（数组），其中包含 mux 已知的所有工作区名称。返回的顺序不保证稳定，请勿依赖其排列顺序——底层实现会对名称做排序与去重，详见下文"底层实现"小节。

无参数：调用时不需要也不接受任何参数。

该函数属于 wezterm.mux 模块。在使用前需要先引入模块：

local wezterm = require 'wezterm' local mux = wezterm.mux -- 获取全部工作区名称 local workspaces = mux.get_workspace_names() for _, name in ipairs(workspaces) do print(name) end

工作区（Workspace）概念回顾

要理解这个函数，首先需要知道 wezterm 的"工作区"是什么。根据 docs/recipes/workspaces.md 的说明：每个 MuxWindow 都与一个工作区相关联，而工作区本质上只是一个标签（label）。GUI 只会聚焦显示"当前激活工作区"中的窗口；当你把窗口生成到不同命名的工作区时，它们不会立即显示，直到你切换到对应工作区。

get_workspace_names()返回的正是 mux 已知的全部工作区名称集合，即"所有已知窗口所属工作区名的去重列表"。它是编写工作区管理脚本的基础数据来源。

底层实现：源码级的准确解释

该 Lua 函数在仓库中的注册位置是 lua-api-crates/mux/src/lib.rs：

mux_mod.set( "get_workspace_names", lua.create_function(|_, _: ()| { let mux = get_mux()?; Ok(mux.iter_workspaces()) })?, );

可以看出，它不接收任何 Lua 参数，直接调用Mux::iter_workspaces()并把结果以Vec<String>形式返回给 Lua（Lua 侧表现为 table）。

iter_workspaces()的实现位于 mux/src/lib.rs 的Mux结构体上：

/// Returns a list of the unique workspace names known to the mux. /// This is taken from all known windows. pub fn iter_workspaces(&self) -> Vec<String> { let mut names: Vec<String> = self .windows .read() .values() .map(|w| w.get_workspace().to_string()) .collect(); names.sort(); names.dedup(); names }

从中可以确认以下几点实现事实：

1. 数据来源是 mux 已知的全部窗口：返回的名字来自self.windows中每个窗口的get_workspace()值，而不是来自独立的"工作区注册表"。也就是说，工作区名称是窗口属性的投影。
2. 自动排序：结果会先sort()排序。
3. 自动去重：多个窗口同属一个工作区时，只会出现一次。
4. 因为数据来自windows，一个没有任何窗口的工作区名称不会出现在列表中——在只读场景下可借此判断"某名称是否真的是已存在的工作区"。

与它配套、同文件中的其他相关方法还包括generate_workspace_name()（基于可用名字生成一个全新的唯一工作区名）与active_workspace()（返回当前身份的有效激活工作区名），它们共同支撑了 wezterm 的工作区管理。

返回值特性与使用要点

• 返回 Lua 数组（从 1 开始的连续索引），用ipairs遍历即可。
• 名称已排序去重，因此可用于生成下拉菜单、做workspace ~= nil的存在性判断。
• 空工作区场景下返回空表{}。
• 该函数只是"读取"操作，不产生副作用，可安全地在配置求值的任何时机调用。

与 set_active_workspace 配合的存在性判断

set_active_workspace 在请求的工作区不存在时会抛出错误，因此常见的防御式写法是先枚举再切换：

local mux = wezterm.mux function switch_to(name) local found = false for _, ws in ipairs(mux.get_workspace_names()) do if ws == name then found = true break end end if found then mux.set_active_workspace(name) else print('workspace not found: ' .. name) end end

值得注意的是，set_active_workspace在底层（lua-api-crates/mux/src/lib.rs）同样先调用iter_workspaces()做包含性检查，不存在的名字会返回 Lua error：

let workspaces = mux.iter_workspaces(); if workspaces.contains(&workspace) { Ok(mux.set_active_workspace(&workspace)) } else { Err(mlua::Error::external(format!( "{:?} is not an existing workspace", workspace ))) }

这印证了"枚举结果可用来判断工作区是否存在"的用法是可靠的。

实战示例：完整的 Lua 工作区管理器

将get_workspace_names()与同模块的 get_active_workspace、set_active_workspace、rename_workspace 组合，可以编写出完整的工作区管理工具：

local wezterm = require 'wezterm' local mux = wezterm.mux -- 打印当前所有工作区，并标记激活项 local names = mux.get_workspace_names() local active = mux.get_active_workspace() for _, name in ipairs(names) do if name == active then print('* ' .. name) else print(' ' .. name) end end -- 重命名当前工作区（rename_workspace 自 20230408-112425-69ae8472 起可用） -- mux.rename_workspace(mux.get_active_workspace(), 'my-new-name')

工作区名也可以在启动时用事件预定义布局（详见 gui-startup 与 mux-startup 事件），随后即可用get_workspace_names()枚举出这些预定义的名字。需要留意的是，wezterm.mux 模块说明 提醒：应避免在配置文件的文件作用域内调用会产生新 split/tab/window 的 mux 函数（配置文件可能在多种上下文中被多次求值）；get_workspace_names()是只读查询，不受此限制，但创建窗口类的调用请放进gui-startup/mux-startup事件中。

常见问题

Q1：返回的顺序为什么和创建顺序不同？因为底层实现会先排序再去重（mux/src/lib.rs 的iter_workspaces），所以返回顺序是字典序而非创建序。

Q2：为什么某个"工作区"没出现在列表里？只有当至少一个窗口归属于该工作区名称时，它才会出现在列表中。仅存在于配置文件中、尚未被任何窗口使用的工作区名不会出现。

Q3：能直接判断某个名字是否是有效工作区吗？可以。遍历返回的 table 判断包含关系即可；这与set_active_workspace内部的存在性检查逻辑一致。

总结

wezterm.mux.get_workspace_names()是一个简单但高频使用的只读 API：它以 mux 层全部窗口的工作区归属为数据源，返回去重、排序后的工作区名称数组，是"枚举—判断—切换—重命名"这一整套工作区管理流程的起点。无论是编写启动时的工作区布局脚本、动态切换工作区，还是实现自定义的 launcher，它都是必不可少的基础查询接口。

【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm