GPUI Deck

复制配方

这 23 个目录配方是可复用的应用源码,被原生 two-style 示例和 catalogue 示例使用。

这 23 个目录配方是可复用的应用源码,被原生 two-style 示例和 catalogue 示例使用。Button 和 Chart 也提供与其公开控件配套的呈现配方。它们把 GPUI 布局与现有控件组合起来,并把颜色、间距和尺寸保留在 使用方的 Palette 或应用提供的 Styled 值中。

复制到应用中

源码 CLI 会复制一个配方及其传递的配方依赖、浅色/深色 令牌源码、模块声明、许可证和所需资源:

cargo run -p gpui-deck-cli --locked -- list
cargo run -p gpui-deck-cli --locked -- add data-table avatar --to ../my-app/src/ui

在使用方中声明 mod ui;,并使用 ui::recipes::{DataTable, Avatar} 以及 ui::Appearance::Settings.palette() 或 ui::Appearance::Compact.palette()。 请使用安装指南中的 Cargo 依赖。CLI 不会修改 使用方的清单。它在构建时嵌入仓库当前的配方源码; 没有远程注册表或更新服务。

请在应用的清单中保留以下 feature 声明:

[features]
test-support = ["gpui-deck/test-support"]

复制的配方测试由这个使用方 feature 控制。声明它也会让 Rust 知晓 它们的 cfg 值;启用它即可运行现有的 GPUI 测试。

再次运行 add 并传入更多名称,即可扩展同一目录。已有的配方 和调色板修改会被保留。生成的 mod.rs 声明和 recipes/.gpui-deck 记录已安装的集合;如果这些脚手架被编辑过, CLI 会在写入前停止,并说明如何手动添加声明。 存在冲突的新文件同样会被拒绝。复制的源码归应用所有。

更新仓库后,运行 diff 即可比较已安装的文件和当前 CLI 内置的源码。请确保 PATH 中有 Git。 此命令读取已安装的配方清单,显示受管文件的更改和缺失情况。补丁中的 - 表示应用中的行, + 表示 CLI 内置的行。应用文件保持不变。

cargo run -p gpui-deck-cli --locked -- diff --to ../my-app/src/ui

手动复制的步骤:

  1. 把所需文件从 crates/base/examples/recipes复制到 应用的某个模块中,并保留仓库的许可条款。

  2. 声明复制的模块并重新导出类型,参照小巧的 mod.rs。只复制应用 所需的模块,也只列出这些模块。

  3. 把 presentation.rs复制到 应用的 recipes 目录旁边。它包含经过测试的示例所使用的实际 Palette 和两种 外观,不含 Demo 及其行为。 声明它,并在配方的父模块中暴露其令牌:

    mod presentation;
    pub(crate) use presentation::{Appearance, Palette};
    mod recipes;

    在应用视图中选择 Appearance::Settings.palette() 或 Appearance::Compact.palette()。 诸如 use super::super::Palette 之类的配方导入 可直接使用。请修改复制的令牌值以适配应用,或把 Palette 替换为 现有的令牌类型。AspectRatio 不接收调色板;其视觉样式由使用方提供。 Bubble 和 Chart 目前保留各自可复制的样式。

  4. 从该应用模块导入这些类型。它们使用 pub(crate) 可见性, 不会从 gpui_deck 导出。无需额外的依赖。

调色板模块和配方都是应用源码,不在库的导出之内。 CLI 提供本地源码分发;这些视觉令牌不会 安装全局主题提供者。交互行为仍由库负责。

有些配方会组合其他配方模块。请把这些模块及其重新导出 与所需配方一并复制:

配方所需的其他配方模块
DataTableInputGroup、EmptyState 和 Pagination
MessageTypography(Paragraph)
SidebarSheet
TraceTypography(Paragraph)

验证范围

现有的组合测试套件运行与原生示例相同的配方模块。 其命令搜索流程涵盖空状态的恢复,日期选择器 流程涵盖分组月份按钮的遍历和激活。静态形状 和调色板值没有单独的测试套件。现有的字段/预设流程 涵盖缺失名称的恢复、只读输入的禁用附加元素、紧急的 行内语义,以及 Item 保留的预览/编辑行为。日期选择器 流程还会检查普通的日程提示仍然是 Note。现有的 三平台 CI 继续检查真实的使用方组合和原生 编译。Linux 还会额外运行独立的配方测试。Windows 和 macOS 从同一个组合目标中过滤掉 two_styles::recipes:: 测试,保留 真实的应用流程,同时避免重复的仅针对配方的检查。另一个 组合流程涵盖预设表格的排序、过滤/空状态恢复、 分页边界、稳定 ID 的动作,以及保留的选择。没有单独的数据 测试框架,也没有重复的平台专属流程。这些结果并不能 确立原生屏幕阅读器、IME、视觉或性能方面的验证。

现有的预览流程还涵盖具名 Spinner 的渲染、装饰性的 不可聚焦 Skeleton、GPUI 的减弱动效渲染、重置的取消、 恢复百分比填充,以及在其展开内容 关闭时移除指示器。加载类配方不新增测试函数或 CI 任务;动画 调度仍由 GPUI 负责,这里不再设第二个测试控制器。

现有的 Help 流程会检查 Kbd 可读的符号化按键名称以及没有 新增焦点停靠点,同时检查组合的 Breadcrumb 祖先动作。上下文 菜单流程会演练其键帽所显示的现有快捷键。 没有单独的快捷键绑定测试控制器、 调色板套件或针对这些静态按键提示的 CI 任务。原生屏幕阅读器的朗读 和桌面的视觉渲染仍属于单独的验证工作。

媒体类配方在同一个组合目标中新增了两个针对性的回归测试。 Avatar 演练缺失、等待中、失败、已加载和已清除的图像源, 同时检查其原生名称、对焦点无影响以及固定的几何尺寸;已加载路径 会解码内置的 SVG。AspectRatio 演练两种容器宽度、超大 内容,以及超出边框的指针裁剪。现有的预设流程检查 保留的选择会驱动预览的图稿、边框比例和会话 名称,同时保留现有的触发器和关闭行为。这些检查 并不能确立远程图像传输、原生屏幕阅读器朗读、桌面 视觉渲染或性能测量。

Sheet 的覆盖范围包括边缘放置、正常和狭窄的视口宽度、 固定的页眉/页脚几何尺寸、主体滚动、后代元素的焦点显示,以及 带保留表单状态的关闭与重新打开。这些检查还会演练 共享 Dialog 的背景滚轮处理,以防止下层内容滚动, 并在狭窄窗口中打开 Select,检查子弹出层的水平边界。 嵌套模态的检查涵盖顶层对话框中的焦点约束和滚轮隔离、 在 Sheet 保持打开的情况下关闭它,以及 经由 Sheet 返回其原始触发器。这些是在现有 GPUI 测试上下文中进行的布局和 交互检查;其范围并不能 确立原生屏幕阅读器、平台 IME 或桌面视觉方面的验证。

Typography 的检查涵盖独立于视觉大小的原生标题级别、 完整的无障碍名称、Paragraph 和 Code 角色,以及不存在文本 焦点停靠点。布局覆盖使用长文本和代码,在两种外观下 分别以正常和狭窄宽度测试。Help 使用方保留其现有的层级、 祖先动作和键盘遍历。该组合目标还会 以 1.5 MiB 的测试线程栈运行,以检查示例的渲染栈回归。 这些是原生元数据、布局和模拟输入的检查;屏幕阅读器 朗读、平台 IME 行为和桌面视觉结果需要单独 验证。

Sidebar 在 Settings 使用方现有的组合流程中演练; 没有单独的候选夹具。这些流程检查显式激活、 禁用的条目、当前小节语义、保留的值、普通的焦点 遍历,以及堆叠的窄窗口布局。Compact 的 TabList 行为 仍由其真实的使用方流程覆盖。Button 的原生元数据约定 负责当前页检查,而 TabsState 的核心回归测试负责对焦点无影响的 程序化选择和变更事件。

Code Block 的覆盖范围检查空内容和多行内容、Unicode、完整的代码 名称、保留的行尾,以及通过 GPUI 测试剪贴板进行的精确全文复制。 布局检查涵盖两种外观、狭窄宽度、长行 和长正文。使用方流程验证复制出的 JSON 中的当前设置、 键盘进入与遍历、代码滚动的两端,以及与父级 Sheet 滚动范围的隔离。剪贴板断言只在测试平台中运行, 不会演练用户桌面的剪贴板服务。组合目标也 保留 1.5 MiB 栈检查;原生剪贴板集成、屏幕阅读器 朗读、IME 和桌面视觉观察仍属于单独的验证工作。

Marker 的覆盖范围检查单个有意义的标签、装饰性分隔符的省略, 以及焦点正常越过该标记的遍历。布局检查演练较长的韩文和 英文标签、狭窄宽度以及两种外观。Schedule 检查会区分 当前选中的日期与被移动或取消的日历光标,保留 现有的键盘流程,并在选择变化 或清除时更新边界。这些是元数据、布局和模拟输入的检查;原生 屏幕阅读器朗读、IME、DPI 和桌面视觉观察仍属于单独的 验证工作。

Message 的针对性配方检查涵盖 Comment/Label/Paragraph 层级、 每段提供的文本其无障碍名称只出现一次、显式换行、较长的 韩文和英文内容,以及两种外观下的窄宽度换行。 Button 自身的测试涵盖激活和禁用行为。Schedule 使用方 检查共享的备注值、本地编辑元数据、空状态的转换、 Edit note 的焦点,以及现有 Sheet 的滚动和关闭。这些是无头的 元数据、布局和输入 检查;原生屏幕阅读器朗读和桌面视觉验证仍然 是单独的工作。

Attachment 的针对性配方检查涵盖完整文件名作为名称,以及合并的 元数据描述且不重复子级语义、较长的韩文和英文文件名、 窄宽度换行以及两种外观。所提供的动作保留 Button 经 独立测试的激活和禁用行为。Help 使用方检查 字节数是否跟随当前的 UTF-8 JSON、Inspect JSON 是否到达 现有的代码焦点目标,以及 CodeBlock 是否保持其完整的复制和滚动行为。剪贴板断言 仍限于 GPUI 的测试剪贴板;这些检查并不能确立原生文件访问、屏幕阅读器朗读 和桌面视觉观察。

Trace 的针对性配方检查涵盖摘要命名、展开后的元数据、具名的 Region 和 Paragraph 层级、关闭后内容的移除,以及较长的摘要和 详情在两种外观的窄宽度下换行。Collapsible 的核心测试 负责激活、禁用触发器的行为以及关闭时的焦点返回;所提供的 动作使用现有的 Button 约定。Help 使用方检查当前表单 值、 展开状态的保留、Close details 动作,以及外围 Sheet 的滚动 和焦点。组合目标保留其 1.5 MiB 栈检查。这些测试 演练原生元数据、布局和模拟输入;桌面渲染、 屏幕阅读器朗读、IME 和性能仍需要单独验证。