API Reference

预览

脚本接口的一份清单：有什么，以及它来自哪个模块。其余页面解释每样东西为什么是这个样子——这一页是用来查名字的。

权威不在这一页。runtime 会为自己的版本生成 gpui-kit.d.ts，并在应用加载时尽力刷新到源码旁；gpui-shell types <directory> 执行同一次写入，并会明确报告失败。生成文件的头部带有 gpui-shell 版本，也包含该应用注册的 HostModule 。请忽略这个文件而不要提交，并在脚本顶部写上 // @ts-check 让编辑器照着它检查。manifest 声明的 Git 依赖同样不在这一页：它们由同一次刷新链接进 node_modules，名字、签名与文档都来自 package 自身。见依赖。

#模块

每个内建模块都以它所暴露的公开 Rust 层命名，所以一条 import 能说明脚本依赖哪一层。gpui-kit 还包含从 JavaScript 使用 GPUI 所需的 shell 桥接： View、留存实体、调度与共享类型。一个名字只属于一个模块，这里不为了方便做 re-export。

import { View, div } from "gpui-kit";
import { Button, v_flex } from "gpui-base";
import { fps_monitor } from "gpui-fps";

有两个名字从不需要 import，但原因不同。window 是真正的全局：没有谁把它交给你，它本来就在作用域里。cx 恰恰相反——它从来不是全局的，只会作为参数到达：render(cx)、init(props, cx)、每个处理器的第二个参数、cx.spawn body 的形参。标准运行时模块——fs/promises、path、crypto、process、net、websocket 等等——受 Host 授权门控，记录在 Capabilities。

API 形态跟随 Rust 原型：App 上的方法放在 cx，Window 上的方法放在 window 全局对象，关联构造器写成 Type.new(...)，自由函数保持小写。没有直接 GPUI 或 Base 原型的名字，属于实现它的公开层。表中也会列出仅存在于类型系统的名字，但它们不是运行时可调用的值。

#gpui-kit 模块

#元素

PathBuilder.fill() 与 .stroke(width) 返回一个句柄，可链式调用 move_to、line_to、curve_to、cubic_bezier_to、arc_to、add_polygon、close 与 dash_array，最后以 build() 收尾。用 window.paint_path(path, background) 把结果画出来——它是唯一一个通过对象取到的元素构造器，因为它镜像的东西在 Rust 侧就是窗口上的一个方法。

list 和 uniform_list 是 GPUI 自己的惰性列表，参数是 (id, item_count, get_key, render)，即 gpui-base 的 v_virtual_list 去掉 item_sizes 的形状：没有尺寸表，因为 GPUI 自己测量各项。uniform_list 测量一行，其余各行按它排布，render(range, cx) 和虚拟列表一样按区间返回元素数组。list 会测量画出的每一项并记住尺寸，render(index, cx) 为一项返回一个元素，所以高度不等的行或面板不必事先说明有多高。两者都只绘制屏幕内的内容外加折叠线下方的一小段，自己处理滚动，并按名字与 Scrollbar 配对；都不接受 VirtualListScrollHandle。list 的 item_count 变化时，读者停留在视口顶部的那一项上：列表按 get_key 给出的键重新找到这一项并滚回去，所以在上方插入一页更早的条目、或在下方追加一条，都不会挪动正在读的内容。加上 with_follow_mode("tail") 后，list 改为停在末尾，追加条目或最后一项变高时都跟到底，直到读者向上滚动。on_visible_range_change 在一帧结束后报告 list 显示了哪些条目，脚本可以据此在读者接近任一端时加载更多。

字符串本身也是元素，和 GPUI 里 &str 实现 IntoElement 完全一样：.child("hello") 就是写文本的方式，样式来自持有它的那个元素。

#View

子类定义只执行一次的 init?(props, cx)，以及返回一个 Element、Entity 或字符串、在 View 被置为失效时执行的 render(cx)。可选的 update(props) 在父 View 改变嵌套 View 的 props 时执行。

#调度

#焦点

#共享类型

#FocusHandle

由 cx.focus_handle() 创建，用 track_focus(handle) 交给元素，并用 release() 释放。

#gpui-shell 模块

这些是 JavaScript 桥接层自身引入的纯类型概念。它们只用于类型检查；这个模块没有运行时值。

ScopePhase 描述当前 Context 属于哪一种 shell 调用。它和 GPUI 的 DispatchPhase 无关；后者控制事件分发时 capture 与 bubble 的顺序。

#cx 上下文

两种 context 的成员相同，但生命周期不同。render 与事件处理器收到的 Context 只属于那次 Host 调用；把它留到调用之后，包括跨越 await，都会得到 stale-context 错误。下面的 AsyncContext 才是为跨越 await 准备的那一种。

其中好几个都指名了它所镜像的 GPUI 方法：open_url 是 App::open_url，open_path 是 App::open_with_system，read_from_clipboard 与 write_to_clipboard 是 App::read_from_clipboard 与 App::write_to_clipboard，focus_handle 是 App::focus_handle（GPUI 没有 FocusHandle::new，这里同样没有），new 是 AppContext::new，spawn 是 App::spawn。

#AsyncContext

AsyncContext 继承 Context，不增加任何成员。区别在生命周期，不在接口：普通的 Context 只为一次 Host 调用发言，一旦那次调用返回就明确报错；而 AsyncContext 不指名任何一次调用——用到它时才解析当时正在执行的那一次，只有在一次都没有时才拒绝。它对应 GPUI 的 AsyncApp。

有三处会交出一个：init、cx.spawn 的 body，以及 cx.timer 的回调。这三处的职责正是「安排或延续比启动它的那次调用活得更久的工作」。

#window 全局对象

这个全局对象的类型是 gpui-kit 导出的 Window。调用处不需要 import，也没有谁把它交给你。每次调用都读取当前正在跑的那次 Host 调用，不在任何调用中时抛异常，所以没有句柄要持有，也没有东西会过期。浮层属于窗口，而不属于打开它的那个 View——这就是这些方法在这里、而不在 Context 上的原因。

上面这些度量——从 rem_size() 一直到 is_maximized()——在 render 中都是合法的：一个要按窗口尺寸决定自身大小的 View，只能在绘制它的那一趟里问。而所有改变窗口的调用在 render 中都会被拒绝，理由和 cx.notify() 一样：一帧去改自己正在绘制的窗口，就是这一帧在和自己较劲。

open_dialog、open_sheet 与 open_sheet_at 接受的是一个返回元素的函数，而不是元素：dialog 活得比打开它的那次调用久，每次重绘时这个函数都会再执行一次。除了两个 has_active_* 查询与 paint_path，这里的一切在 render 中都不合法。见 Overlays。

#存储

Web Storage API，原样照搬。两个 store 同时也是裸的全局变量——localStorage.getItem(k) 与 window.localStorage.getItem(k) 是同一次调用——因为在浏览器里也是如此。

值是字符串，所以有结构的东西照 web 上的写法走 JSON.stringify 与 JSON.parse。flush() 是唯一多出来的成员：浏览器不需要它，因为它的存储从头到尾都是同步的。localStorage 受 capability 管辖，Host 没授权时抛异常；sessionStorage 不受管辖，因为它持有的东西从不离开进程。见 Capabilities。

#gpui-base 模块

这里的组件拥有行为、焦点，以及屏幕阅读器听到的内容，而自身几乎什么都不画。画面归脚本所有，用样式接口写出来。每个名字都链接到它在 gpui-base 文档里的页面，那里描述了它完整的 Rust 接口与行为。

#布局

#控件

slider 的四个部件接受同一个 SliderState，而且四个都不能少——没有 SliderIndicator 的 slider 根本拖不动。

#文本编辑

没有专门的数字状态类型：给 InputState 设上 set_step、set_min 与 set_max，它就成了数字状态。

#容器与浮层

在这些之上动手之前，有两处缺口值得先知道：打开的 Select 或 Combobox 列表的方向键导航要你自己接（零件都在，见下），而 Enter 与 Escape 到不了 DatePicker。两者都写在各自类型的声明里，也就是它们真正咬人的地方。

#表格与列表

两种虚拟列表都接受 (id, item_count, item_sizes, get_key, render)。render(range, cx) 是这套接口里唯一由 Host 在一帧进行中调用的回调，所以在它内部注册处理器、创建留存状态与调用 cx.notify() 都会被拒绝。

#Dock

area 上的方法是 add_panel(view, options)、remove_panel(id)、panels()、dump()、load(state)、has_dock、is_dock_open、toggle_dock、remove_dock、dock_size、set_dock_size、set_dock_collapsible、is_locked、set_locked、is_zoomed、zoom_out、on("layout_changed", handler) 与 release()。

每一次编辑都在发起它的那次调用返回之后按调用顺序应用——面板的主体来自 cx.new(Class)，那时它自己还在构造中——所以 panels() 与 dump() 读到的是本轮编辑之前的布局。见 Dock 与面板。

#留存句柄

每一个都只创建一次——在 init 或事件处理器里，绝不在 render 里——并且每一个都有 release(): boolean，返回它当时是否还活着。释放之后再用会抛异常。

on(...) 是替换该事件的处理器，而不是再加一个，返回值表示之前是否已经有一个。

#InputState

来自 InputState.new(options?)，其中 options 是 { placeholder?: string, value?: string }。

#TextareaState

来自 TextareaState.new(options?)，其中 options 是 { placeholder?: string, value?: string, rows?: number }。

#SliderState

来自 SliderState.new(options?)，其中 options 是 { min?, max?, step?, scale?: "linear" | "logarithmic", value?: SliderValue }。默认是 0..100、步长 1、从 min 起。"logarithmic" 需要 min 大于零。

#OtpState

来自 OtpState.new(length, options?)，其中 options 是 { value?: string, masked?: boolean }。长度在创建时就固定了。

#VirtualListScrollHandle

来自 VirtualListScrollHandle.new()，用 track_scroll(handle) 交给列表。

#日历

CalendarState 存在的理由是 month_days()——哪些日期落在哪一周、相邻月份的日子补在哪里、这个月需要几行。格子由脚本自己画。

const grid = this.calendar.month_days()[0];
v_flex().children(
  grid.map((week) =>
    h_flex().children(
      week.map((day) =>
        Button.new(day)
          .selected(day === this.calendar.value())
          .on_click((_, cx) => {
            this.calendar.set_value(day);
            cx.notify();
          })
          .child(String(Number(day.slice(8)))),
      ),
    ),
  ),
);

base 的 Calendar 元素没有绑定，这是个决定而不是遗漏：它遍历同一份网格，每个格子调用一次渲染回调——一帧最多四十二次跨语言调用，而且发生在 GPUI 的 layout 过程里，为的是一批本身不带任何行为的格子。在这里读到网格自己画，是同样的活，少了那四十二次穿越。

日期一律是 "YYYY-MM-DD"：按文本排序即是按时间排序，new Date(s) 能直接读——需要星期名或本地化月份名时用它。

#主题

读主题用 cx.theme()。set_theme 留在 gpui-base，因为主题属于这一层；但修改仍然要求当前存在一次 Host 调用，只能从事件处理器或 task 调用，不能在 render 或 layout 中调用。

#其他类型

#组合模式

其中五个组件不是一个元素，而是一种搭法，上面的表格说不出这件事。下面每段都是能跑起来的最小写法，并且都经过运行时校验。

受控控件。 Checkbox、Switch、Radio 与 Toggle 自身不持有状态：值由你读进去、再写回来。它们什么都不画，所以勾选标记是一个子元素。

Checkbox.new("done")
  .checked(this.checked)
  .on_change((checked, cx) => {
    this.checked = checked;
    cx.notify();
  })
  .child(this.checked ? "done" : "not done");

Progress 负责报读，进度条是你的。 root 带的是 role 和屏幕阅读器要念的 0..=100，它自己什么都不画。

Progress.new("upload")
  .value(62)
  .child(
    ProgressTrack.new()
      .w(200)
      .h(6)
      .bg(cx.theme().colors.muted)
      .child(ProgressIndicator.new().w(124).h(6).bg(cx.theme().colors.primary)),
  );

滑块是四个部件，四个都不能少——没有 SliderIndicator 的滑块根本拖不动，因为每一个指针位置都是相对它的盒子测量的。四个部件收的是同一份状态。

Slider.new(this.volume).child(
  SliderTrack.new(this.volume)
    .w(200)
    .h(16)
    .child(SliderIndicator.new(this.volume).h(4).bg(cx.theme().colors.primary))
    .child(
      SliderThumb.new(this.volume).w(12).h(12).bg(cx.theme().colors.background),
    ),
);

Select 管键盘，Popup 管那块面。 root 持有 combobox 的语义与展开状态；列表是放在它里面的一个 Popup。它需要两个 focus handle——一个给触发元素，一个给内容——没有第一个，屏幕上就没有任何东西持有键盘。

Select.new("mode")
  .accessibility_label("Mode")
  .open(this.open)
  .track_focus(this.trigger)
  .content_focus_handle(this.list)
  .on_open_change((open, cx) => {
    this.open = open;
    cx.notify();
  })
  .child(
    Popup.new("mode-list", trigger)
      .anchor("bottom_left")
      .when(this.open, (el) => el.content(list)),
  );

展开后用方向键移动高亮这件事要你自己写：base 期待里面的东西用自己的按键绑定来跑高亮，而它不会替你跑。零件都在——把 on_key_down 放在键盘被移过去的那个 content 元素上，自己移动高亮；或者在自己的 key_context 下把 ↑ / ↓ 绑到 action。开箱状态是：指针可用，Escape 关闭，Enter 与 ↓ 展开，高亮不动。

虚拟列表和它的滚动条按名字配对。 列表自己不画滚动条，而且配对在运行前不做任何校验，所以两半都要写。

v_flex()
  .relative()
  .h(200)
  .child(
    v_virtual_list(
      "rows",
      rows.length,
      28,
      (index) => rows[index].id,
      (range) =>
        rows.slice(range.start, range.end).map((row) => div().child(row.name)),
    ).size_full(),
  )
  .child(Scrollbar.vertical("rows").absolute().inset_0());

嵌套 View 创建一次，然后作为子元素挂上。 cx.new 属于 init 或事件处理器；实体在任何接受子元素的位置都能当子元素。

init(props, cx) {
  this.chart = cx.new(PriceChart, { symbol });
}
render() {
  return v_flex().child(this.chart);
}

#gpui-fps 模块

它的父元素必须设置 relative()。HUD 自己拥有完整外观；普通样式与子元素对它不起作用。

#元素方法

所有元素共享同一个 prototype，所以下面每个方法在任何元素上都能通过类型检查——某个方法实际适合哪个组件，类型并不表达。交给一个不承接它的组件的行为 builder 会被写进日志，而不是被悄悄丢掉。

元素 builder 方法都返回同一个元素，所以一条链就是一个表达式。map 是例外：与 GPUI 的 FluentBuilder.map 一样，它原样返回回调的结果。元素被用作子元素时即被消费，并且属于构建它的那一趟渲染。

#组合

#插槽

插槽不是子元素：元素被组件消费，渲染在组件决定的位置。

#事件

#Actions 与键绑定

一个 action 是比按键高一层的东西。cx.bind_keys 说哪个组合键在什么上下文里意味着 "save"，元素上的 on_action("save", ...) 说 "save" 做什么；菜单项或工具栏按钮用 window.dispatch_action("save") 派发同一个名字，就能走到同一个处理器，而两边都不必知道对方存在。

init(_props, cx) {
  cx.bind_keys([{ keystroke: "cmd-s", action: "save", context: "Editor" }]);
}

render(_cx) {
  return div()
    .key_context("Editor")
    .track_focus(this.handle)
    .on_action("save", (event, cx) => this.save(cx));
}

context 是一个匹配元素 key_context(...) 的谓词表达式，所以同一个组合键可以在列表里是一个意思、在编辑器里是另一个意思。同一个元素上注册多个 on_action 是可以的，彼此独立；一个它们都没认领的 action 会继续往外层元素传。

上面这组——on_key_down、on_key_up、四个指针事件、on_action 与 key_context——接线在 div、h_flex、v_flex、Button、Link、Checkbox、Switch、Radio、Toggle、Tabs 与 Tab 上。写在其余组件上的处理器会被记录下来但永远到不了 GPUI，日志里会说明——把它包一层，写在外层元素上。

接线了不等于收得到。按键沿焦点路径传递，所以一个不接受脚本焦点句柄的组件——比如 Tab——听得到按下、永远听不到按键，无论两者接线得多好。

#控件状态

#无障碍

#焦点与键盘

#滚动与面板

#锚定浮层

#Dock 命令

dock 的 chrome 画出来的元素做什么。缓存的 chrome 描述没有脚本事件处理器的生命周期，所以其中不能注册事件处理器——取而代之的是不携带任何脚本值的命令，由 base 完成实际动作。每一个的第一个参数都是它所在 handler 拿到的那个对象；它们只能挂在 div、h_flex 或 v_flex 上。

#Dock chrome

四个 handler，全都可选，且只能挂在 dock_area(...) 上。每一个都会先在 GPUI 的 layout pass 内部被调用，拿到的是 base 已经解析好的状态；描述会缓存到该状态或 handler 改变为止。

#动效

property 取 "opacity"、"width"、"height"、"left"、"top" 之一，每一帧都不会进入 JavaScript。

#样式模板

每一个都接受一个函数，函数收到一个游离的元素用来收集样式；返回值会被忽略，所以写成一条链或写成块状函数体都可以。

#样式方法

元素上其余的一切都是样式。它们分成两族，而且从不重叠：

• 带参数的方法，手工绑定：size、padding、margin、position、flex、border、radius 与 paint 各族。每个方法接受哪种长度类型跟随它的 Rust 签名，所以 .p("auto") 是类型错误，理由与它在运行时抛异常完全相同。
• 无参方法，从 GPUI 的反射表生成：flex_col、items_center、gap_2、rounded_md、text_sm、size_full、truncate 以及这一族的其余成员。生成的声明就是当前构建所用 GPUI 版本的完整清单。

两者都记录在 Styling 里，还有长度与颜色的语法，以及调色板定义的 token。

#HostModule

Host 在 Rust 侧注册的模块，按名字 import，和其它模块没有区别：

import { quotes } from "market";

它不属于任何内建模块。生成的类型声明里每个注册过的模块各有一段 declare module，所以模块名和每一个导出名都会被检查。见 HostModule。