入门 Zed Industries 2026-09-14 17:42:20 · 2 阅读

第150章 Zed 代码库术语表与 GPUI 状态管理详解

本页定义了 Zed 代码库中使用的术语和结构。

这是一份尽力而为的列表，仍在持续完善中。

命名规范

以下是代码库中常见的命名模式。Name 是任何类型名称的占位符，例如 AnyElement 或 LspStore。

AnyName：name 的类型擦除版本。可以类比为 Box<dyn NameTrait>。
NameStore：一种包装类型，抽象了操作是运行在本地还是远程这一细节。

GPUI

状态管理

App：一个持有完整应用状态（包括所有实体）的单例。App 不是 Send，因此它只存在于创建它的线程上（通常是主/UI 线程）。如果你看到 &mut App，说明你正运行在 UI 线程上。
Context：围绕 App 的包装器，为特定的 Entity 提供专门的行为。你可以将其理解为 (&mut App, Entity<V>)。例如，App::spawn 接受 AsyncFnOnce(AsyncApp) -> Ret，而 Context::spawn 接受 AsyncFnOnce(WeakEntity<V>, AsyncApp) -> Ret。
AsyncApp：App 的拥有版本，适用于异步上下文。它同样不是 Send，因此仍在主线程上运行，且如果 App 已终止，操作可能会失败。AsyncApp 的存在是因为 App 通常作为 &mut App 访问，这使得跨越异步边界持有它变得困难。
AppContext：一个抽象了 App、AsyncApp、Context 及其测试变体的 trait。
Task：在后台或前台执行器上运行（或计划运行）的 future。与普通 future 不同，任务无需调用 .await 即可启动。但你仍需 await 它们以读取结果。
Executor：用于生成在前台或后台线程上运行的任务。请尽量将任务放在后台线程上运行。

BackgroundExecutor：一个运行 Task 的线程池。

ForegroundExecutor：运行 Task 的主线程。

Entity：指向由 gpui 管理的结构的强类型引用，实质上是 App::EntityMap 的一个指针/映射键。

WeakEntity：指向可能已不存在的 Entity 的运行时可检查引用，类似于 std::rc::Weak。

Global：单例类型，仅有一个值，存储在 App 中。

Event：可由 Entity 发送给订阅者的数据类型。

Action：代表用户键盘输入的事件，可被监听器处理。示例：{#action file_finder::Toggle}

Observing：对实体变更通知做出响应。

Subscription：用于响应应用状态变化的事件处理器。 1. 处理发出的事件 2. 观察实体的 {new, release, on notify}

UI

View：通过实现 Render 来生成 Element 的 Entity。
Element：可布局并绘制到屏幕上的类型。
element expression：用于构建元素树的表达式，示例：

h_flex()
    .id(text[i])
    .relative()
    .when(selected, |this| {
        this.child(
            div()
                .h_4()
                .absolute()
                等等等

Component：可渲染为 Element 的构建器。
Dispatch tree：TODO
Focus：优先处理按键输入的位置
Focus tree：从当前焦点位置到 UI 根节点的路径。示例 TODO

Zed UI

Window：代表桌面环境中 Zed 窗口的结构体（参见下图）。可以打开多个窗口，该对象主要传递给渲染层使用。
Modal：悬浮于其他 UI 元素之上的 UI 组件。
Picker：一个结构体，表示悬浮在 UI 上方的条目列表（Modal）。你可以选中某个条目并确认，具体行为由 picker 的 delegate 决定。（下图中的 'Modal' 就是一个 picker。）
PickerDelegate：一个 trait，用于为 Picker 定制行为。Picker 将 PickerDelegate 存储在 delegate 字段中。
Center：zed 窗口的中间区域，会被拆分成多个 Pane。在代码库中，它是 Workspace 结构体上的一个字段（见下图）。
Pane：Center 中的一个区域，可以放置各种内容，比如编辑器、multi-buffer 或终端（见下图）。
Panel：实现了 Panel trait 的 Entity。Panel 可以放置在 Dock 中。下图中：ProjectPanel 在左侧 dock，DebugPanel 在底部 dock，AgentPanel 在右侧 dock。而 Editor 没有实现 Panel。
Dock：一种类似于 Pane 的 UI 元素，可以打开和隐藏。最多可同时打开三个 dock：左侧、右侧和底部。dock 中包含的是一个或多个 Panel，而不是 Pane。

Screenshot for the Pane and Dock features

Project：一个或多个 Worktree。
Worktree：表示本地或远程的文件。

Screenshot for the Worktree feature

Multibuffer：一组 Editor 的列表，multi-buffer 可以同时编辑多个文件。当 Zed 中的某个操作返回多个位置时（如搜索或跳转到定义），就会打开 multi-buffer。参见下图中的项目搜索。

Screenshot for the MultiBuffer feature

Editor

Editor：文本编辑器类型。Zed 中大多数可编辑区域（包括单行输入框）都是 Editor。上图中的每个面板都包含一个或多个 Editor 实例。
Workspace：窗口的根节点。
Entry：文件、目录、待创建目录或未加载目录。
Buffer：文件的内存表示，包含语法树、Git 状态和诊断信息等相关数据。
pending selection：鼠标按下并拖动中，但尚未释放的状态。