GPUI Kit 实战指南用 Rust GPUI 构建跨平台桌面应用的 6 个关键决策与避坑手册【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kitGPUI Kit 是一个基于 GPUI 的 Rust GUI 组件库目标是用 Rust 构建高性能、跨平台的桌面应用你只需要依赖一个 crate就能拿到带主题的 60 多个 UI 组件、无样式的底层行为层、测试支持与多平台后端。本文不重复 API 词典而是站在你要做选择的立场讲清楚每个核心概念在什么场景下该怎么选以及哪些做法会直接把项目拖进维护泥潭。阅读前提本文是规范性指南。must表示生命周期、正确性或生态层面的硬约束违反会导致 bug 或破坏调用方should表示默认架构选择偏离时必须能说出具体理由。文中所有结论均可在仓库源码中找到对应实现签名如有出入以当前源码与 website/docs/ 下的官方文档为准。为什么大型 Rust GUI 项目会越写越乱先回答为什么多数 Rust GUI 项目腐烂的起点不是代码质量而是按文件类型组织目录——所有屏幕放views/所有数据放models/所有弹框放modals/。这种组织方式按实现角色归档却让一个能力的代码散落在整个仓库里想改重命名工作区这个功能你得跨三个目录翻找想删掉某个功能你不敢动因为说不清哪些文件属于它。GPUI Kit 的应对思路是把 crate 边界当工程边界一个能力feature就是一个 crate它的模型、视图、命令、对话框收敛在同一个公共边界之后。GPUI Kit 自身就是范例——看 crates/ 目录base是可复用行为与几何component是带主题的通用 UIassets是图标shell/story/kit各有独立职责。依赖方向恒定向下高层拥有领域含义与编排低层拥有可复用表现must不要让可复用组件依赖某个应用屏幕也不要把gpui-base挂到组件层的主题上。具体到你自己的应用一个特性值得独立成 crate 的信号它有自己的状态与生命周期、有稳定的公共接缝、或实现量大到值得单独编译测试should为每个能力建 crate但不要为每个屏幕或每个辅助函数建 crate——粒度太细会把 Cargo 构建变成碎玻璃两个特性要通信时走显式的命令Action、事件或小型共享服务而不是让视图 A import 视图 B 的内部只有当一个能力已有清晰名字、且存在多个真实所有者时才抽sharedcrate。这样做的收益是移除变得诚实一个无法在不翻遍全局目录的情况下摘掉的功能其实从未被真正隔离过。一张图看懂GPUI Kit 的 5 层架构与依赖方向把 GPUI Kit 的应用栈想象成一条只能向下依赖的链。从你的main.rs往下看依次是层位置负责什么不负责什么app shell你的main.rs/ 入口 crate组合窗口与特性 crate几乎不含特性逻辑feature crate你的workspace/、search/等一个能力的全部模型、视图、命令、对话框不依赖 shell不伸手进兄弟特性app component你的shared/重复出现、有领域含义的模式不含只服务单屏的一次性逻辑gpui-componentcrates/component/src/带主题的通用 UIButton、Table、Dock不选品牌色、不替你做产品决策gpui-basecrates/base/src/无产品表现的可复用行为焦点陷阱、虚拟化、resize 运算不含任何产品视觉语言入口门面在 crates/kit/src/lib.rs应用只依赖gpui-kituse gpui_kit::*;拿到的就是 GPUI 本体gpui_kit::component、gpui_kit::base、gpui_kit::assets、gpui_kit::platform按名访问各层。理解这条链之后Base 层有一条最持久的规则Base 拥有可复用行为及其所需几何表现层拥有产品的视觉语言。无头不等于一个空div——弹层碰撞检测、键盘导航、虚拟化这些逻辑必须有内部结构反过来Basemust不得选择品牌色、字体、密度或组件变体。判断一个 API 放哪层时问一句换个皮肤、换个产品这段逻辑还成立吗成立就下沉不成立就留在表现层。核心决策树这个场景下到底选什么值类元素还是实体这是第一道分叉。GPUI 是保留状态加声明式渲染实体跨帧存活render返回的只是当前帧的元素描述。两种单元各有明确适用场景场景选择判断依据输入全部由调用方传入帧与帧之间无需记忆RenderOnce/IntoElementButton、Checkbox、Badge这类控件的默认形态需要焦点、订阅、异步工作、历史、测量或跨帧行为EntityTRenderInput、Select、Combobox、Table等有状态系统一段纯视觉装饰空态提示、徽标排列RenderOnce值为它建实体会平白增加生命周期协调成本实体的正确存法是存在拥有它的视图字段里而不是在render里每帧重建。crates/component/src/input/ 等模块里的有状态组件都持有Entity...Statenew时创建一次之后帧间复用。状态该归谁把每份状态放进能保持它正确的最小所有者这张表可以贴墙上状态种类归属领域状态项目列表、文档内容模型或特性视图瞬态视图状态展开与否、当前页渲染它的那个视图可复用行为状态光标、选中范围组件自己的EntityState极小的元素局部状态GPUI 键控元素状态共享应用级服务GPUI globals选择、开关这类普通控件should用受控值值从所有者传入回调只上报请求的变更所有者更新后cx.notify()再渲染一次。crates/component/src/checkbox.rs 的on_change文档写得很直白——这是受控值owner 必须写入请求值并 notify 才会生效。回调绝不能在组件内部偷偷存一份影子状态否则副本早晚与受控值漂移。配套的 must 清单变更会影响渲染就 notify语义事件用cx.emit不要因为读了一下值就 notify更不要在render里无条件通知——那会排下一帧渲染形成永久重绘循环。多个字段构成一个不变量时一起更新、只通知一次。稳定身份怎么给ElementId是行为的一部分它给元素稳定身份并为元素局部状态、焦点、动画提供键。判断标准行、标签页、树节点、重复控件 → 用稳定的领域 ID同一控件在多个地方重复 → 用所属对象给子 ID 加命名空间如(delete-project, project.id)这类组合翻译后的标签文本、可重排列表的下标 →绝不要拿它们派生身份重排或换语言会瞬间打乱所有状态归属render里每帧生成新鲜随机 ID → 状态永远累积不起来因为身份每帧都在换。同一规则适用于 overlay token、滚动句柄与持久化 ID两个各保留行为的行为体共享同一个键就会互相覆盖状态。布局与滚动谁拥有几何两个高频坑判断表如下症状原因修复一行全高列的头部被裁出窗口顶部h_flex在交叉轴居中子项列取内容高度而非行高给行加items_stretch()或给列加h_full()弹性子项里的长内容把容器撑爆flex 项默认拒绝围绕内容收缩对弹性子项加min_w_0()/min_h_0()测量是弹层、虚拟化、编辑器的深层工具不是布局手段只有普通布局表达不了关系时才在 prepaint 观察 bounds且测量数据要视为帧级/修订级作用域——排版、rem 尺寸或内容变了它就过期。每个可滚动区域must只有一个所有者把Scrollable挂在拥有整个面板视口的元素上内容 inset 放进滚动所有者内部而不是用带 padding 的容器包住它。端到端走查一个最小例子里每一行落在哪一层 以 examples/hello_world/src/main.rs 为蓝本把它拆开看每一步的归属。视图本体是一个值类渲染器每行都在声明这一帧长什么样impl Render for Example { fn render(mut self, _: mut Window, _: mut ContextSelf) - impl IntoElement { div() .v_flex() .gap_2() .child(Hello, World!) .child(Button::new(ok).primary().label(Lets Go!)) } }它对应决策树的第一档输入全是字面量、无需跨帧记忆所以Example没有字段、不建实体Button也是值类组件。接下来是入口它演示了启动期的两条 must 规则gpui_kit::application().run(move |cx| { gpui_kit::init(cx); gpui_kit::open_window(WindowOptions::default(), cx, |_, cx| cx.new(|_| Example)) .expect(Failed to open window); });gpui_kit::init(cx)must只调用一次——它按启用特性初始化gpui-component进而初始化gpui-base见 crates/kit/src/lib.rs 中init的文档。gpui_kit::open_window会自动用 BaseRoot包住你的视图窗口级的 overlay、通知、菜单设施由此生效不要为一个窗口里的每个页面再造独立 root绕过它静态截图看不出问题overlay 嵌套和焦点快速切换时会立刻暴露。如果这个按钮将来要读写状态走查的下一步就是加受控回调。对照 crates/component/src/checkbox.rs 的真实签名new收impl IntoElementId回调签名为Fn(bool, mut Window, mut App)Checkbox::new(show-hidden) .checked(self.show_hidden) // 受控当前值由所有者驱动 .label(Show hidden files) .on_change(|checked, _, _| { // 回调只上报意图所有者写入新值后 cx.notify() 触发重渲染 })注意方向值流是所有者 → 组件事件流是组件 → 所有者两条流不闭合回组件内部状态反馈循环就此断掉。最后看缩放链路。Root的渲染实现里有这样一行crates/component/src/root.rswindow.set_rem_size(cx.theme().font_size)。这意味着主题基础字体同时是应用 rem 设计尺度的锚点不只是正文字号。想全局改缩放正规做法是改锚点再同步 Base 投影Theme::global_mut(cx).font_size px(18.); Theme::sync_base(cx); window.refresh();sync_base会重建 Base 主题并写回全局crates/component/src/theme/mod.rs直接改主题公共字段后不调用它滚动条和 resize 手柄会拿着旧样式继续画。应用其余 UI 一律用相对辅助方法text_sm()、gap_2()、p_3()让文字、间距、控件随锚点一起缩放must不在应用代码里写裸 hex、rgb/rgba或裸px(...)例外仅限文档化的物理边界、运行时测量或 token 定义本身。约定速查表命名、所有权与 API 设计 ⚡这张表合并了词汇表与所有权规则评审前对着扫一遍。词汇是 API 的一部分——同一个概念在生态里必须用同一个词命名前先搜索 GPUI、gpui-base与组件层的既有术语。概念命名模式示例值类渲染控件名词Button、Tab保留行为模型ControlStateTableState、InputState命令式共享引用ControlHandleDialogHandle语义通知ControlEventSelectEvent可插拔数据/行为所有者RoleDelegate/RoleProviderTableDelegate布尔 readeris_形容词/has_名词不新增can_is_closable优于can_close通用非布尔替换 builderwith_fieldwith_item_ix就地变更mut selfset_fieldset_items回调注册on_事件或意图on_change、on_open_change精确领域词是硬规则混用会被评审打回selected是持久成员资格focused是键盘目标hovered是指针存在三者不可互换index是坐标id是稳定身份可重排数据must不按键值持久化 index。API 设计侧的要点私有字段是行为状态的默认公共字段只留给刻意的配置/序列化场景且每个含公共字段的公共 structmust标#[non_exhaustive]并提供构造器或 builder布尔 builder 用字段名disabled(bool)对应 reader 用is_disabled()流畅 builder 省略set_前缀消费并返回Self。on_click只留给真正的点击契约受控语义原语should用on_change(next_value, ...)——crates/component/src/checkbox.rs 里on_click已文档化为on_change的别名新代码直接选on_change更不容易误用。常见错误 vs 正确做法 错误做法正确做法一个实体装下全应用互不相关的状态按最小所有者拆给模型、视图、组件对可重排行用随机或下标做ElementId用稳定领域 ID必要时加对象命名空间应用代码里写死 hex 颜色与圆角从cx.theme().semantic_tokens()读语义角色见 crates/base/src/theme_tokens.rscolors/radius/spacing/typography/shadow 五个尺度刻意不含组件名在语义组件已提供键盘与焦点契约的地方手搓可点击div先用标准组件表达不了就改进其显式 API每次 render 都cx.notify()只在连贯状态变更结束后通知最窄的拥有实体两个 div 各自包一层滚动每个可滚动区域一个所有者滚动目标轴显式路由对可逆低风险操作弹确认框直接执行破坏性操作才确认测试只调内部方法用#[gpui_kit::test]走无头窗口演练指针、键盘与焦点结果回来就写入当前状态给异步结果附修订号/身份过期工作直接丢弃测试分层与上面同源在能证明行为的最低层测试——纯逻辑测试状态转移与几何GPUI 上下文测试实体与事件交互契约激活、受控变更、禁用、事件次序用 crates/kit/src/lib.rs 暴露的gpui_kit::test模块在无头窗口里驱动完整工作流留给示例冒烟测试。可确定性复现的 bug先补回归测试再修。提交前的自查清单 ✅状态与副作用的所有者能一句话说清render里没有无条件通知或重建实体RenderOnce与EntityT的选型有理由重复元素使用稳定领域 ID应用代码无裸 hex/rgb/裸px(...)自定义 spacing/elevation 尺度有明确存储方不指望写进全局主题后被semantic_tokens()读回键盘动作、焦点陷阱、overlay 开合与禁用态协同正常key_context与on_action挂在同一聚焦区域loading / empty / error / 取消路径在 UI 中都有表达错误不是只进日志大数据集走虚拟化组件键盘选择与滚动在模型坐标中进行新增公共 API 保持依赖方向向下、字段私有或#[non_exhaustive]测试在合适层证明了行为格式化与 Clippy 通过需要设计层面的取舍间距、层级、交互态、界面文案先读 website/docs/design-guides.md更完整的工程规范见 skills/gpui-kit/references/coding-guides.md组件级 API 细节以 website/component/ 下的各组件页与当前源码为准。记住本文只有一条主线先问谁拥有这份状态/这段行为再决定代码落在哪一层、用什么名字——其余所有规则都是这句话的推论。【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
GPUI Kit 实战指南：用 Rust + GPUI 构建跨平台桌面应用的 6 个关键决策与避坑手册
GPUI Kit 实战指南用 Rust GPUI 构建跨平台桌面应用的 6 个关键决策与避坑手册【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kitGPUI Kit 是一个基于 GPUI 的 Rust GUI 组件库目标是用 Rust 构建高性能、跨平台的桌面应用你只需要依赖一个 crate就能拿到带主题的 60 多个 UI 组件、无样式的底层行为层、测试支持与多平台后端。本文不重复 API 词典而是站在你要做选择的立场讲清楚每个核心概念在什么场景下该怎么选以及哪些做法会直接把项目拖进维护泥潭。阅读前提本文是规范性指南。must表示生命周期、正确性或生态层面的硬约束违反会导致 bug 或破坏调用方should表示默认架构选择偏离时必须能说出具体理由。文中所有结论均可在仓库源码中找到对应实现签名如有出入以当前源码与 website/docs/ 下的官方文档为准。为什么大型 Rust GUI 项目会越写越乱先回答为什么多数 Rust GUI 项目腐烂的起点不是代码质量而是按文件类型组织目录——所有屏幕放views/所有数据放models/所有弹框放modals/。这种组织方式按实现角色归档却让一个能力的代码散落在整个仓库里想改重命名工作区这个功能你得跨三个目录翻找想删掉某个功能你不敢动因为说不清哪些文件属于它。GPUI Kit 的应对思路是把 crate 边界当工程边界一个能力feature就是一个 crate它的模型、视图、命令、对话框收敛在同一个公共边界之后。GPUI Kit 自身就是范例——看 crates/ 目录base是可复用行为与几何component是带主题的通用 UIassets是图标shell/story/kit各有独立职责。依赖方向恒定向下高层拥有领域含义与编排低层拥有可复用表现must不要让可复用组件依赖某个应用屏幕也不要把gpui-base挂到组件层的主题上。具体到你自己的应用一个特性值得独立成 crate 的信号它有自己的状态与生命周期、有稳定的公共接缝、或实现量大到值得单独编译测试should为每个能力建 crate但不要为每个屏幕或每个辅助函数建 crate——粒度太细会把 Cargo 构建变成碎玻璃两个特性要通信时走显式的命令Action、事件或小型共享服务而不是让视图 A import 视图 B 的内部只有当一个能力已有清晰名字、且存在多个真实所有者时才抽sharedcrate。这样做的收益是移除变得诚实一个无法在不翻遍全局目录的情况下摘掉的功能其实从未被真正隔离过。一张图看懂GPUI Kit 的 5 层架构与依赖方向把 GPUI Kit 的应用栈想象成一条只能向下依赖的链。从你的main.rs往下看依次是层位置负责什么不负责什么app shell你的main.rs/ 入口 crate组合窗口与特性 crate几乎不含特性逻辑feature crate你的workspace/、search/等一个能力的全部模型、视图、命令、对话框不依赖 shell不伸手进兄弟特性app component你的shared/重复出现、有领域含义的模式不含只服务单屏的一次性逻辑gpui-componentcrates/component/src/带主题的通用 UIButton、Table、Dock不选品牌色、不替你做产品决策gpui-basecrates/base/src/无产品表现的可复用行为焦点陷阱、虚拟化、resize 运算不含任何产品视觉语言入口门面在 crates/kit/src/lib.rs应用只依赖gpui-kituse gpui_kit::*;拿到的就是 GPUI 本体gpui_kit::component、gpui_kit::base、gpui_kit::assets、gpui_kit::platform按名访问各层。理解这条链之后Base 层有一条最持久的规则Base 拥有可复用行为及其所需几何表现层拥有产品的视觉语言。无头不等于一个空div——弹层碰撞检测、键盘导航、虚拟化这些逻辑必须有内部结构反过来Basemust不得选择品牌色、字体、密度或组件变体。判断一个 API 放哪层时问一句换个皮肤、换个产品这段逻辑还成立吗成立就下沉不成立就留在表现层。核心决策树这个场景下到底选什么值类元素还是实体这是第一道分叉。GPUI 是保留状态加声明式渲染实体跨帧存活render返回的只是当前帧的元素描述。两种单元各有明确适用场景场景选择判断依据输入全部由调用方传入帧与帧之间无需记忆RenderOnce/IntoElementButton、Checkbox、Badge这类控件的默认形态需要焦点、订阅、异步工作、历史、测量或跨帧行为EntityTRenderInput、Select、Combobox、Table等有状态系统一段纯视觉装饰空态提示、徽标排列RenderOnce值为它建实体会平白增加生命周期协调成本实体的正确存法是存在拥有它的视图字段里而不是在render里每帧重建。crates/component/src/input/ 等模块里的有状态组件都持有Entity...Statenew时创建一次之后帧间复用。状态该归谁把每份状态放进能保持它正确的最小所有者这张表可以贴墙上状态种类归属领域状态项目列表、文档内容模型或特性视图瞬态视图状态展开与否、当前页渲染它的那个视图可复用行为状态光标、选中范围组件自己的EntityState极小的元素局部状态GPUI 键控元素状态共享应用级服务GPUI globals选择、开关这类普通控件should用受控值值从所有者传入回调只上报请求的变更所有者更新后cx.notify()再渲染一次。crates/component/src/checkbox.rs 的on_change文档写得很直白——这是受控值owner 必须写入请求值并 notify 才会生效。回调绝不能在组件内部偷偷存一份影子状态否则副本早晚与受控值漂移。配套的 must 清单变更会影响渲染就 notify语义事件用cx.emit不要因为读了一下值就 notify更不要在render里无条件通知——那会排下一帧渲染形成永久重绘循环。多个字段构成一个不变量时一起更新、只通知一次。稳定身份怎么给ElementId是行为的一部分它给元素稳定身份并为元素局部状态、焦点、动画提供键。判断标准行、标签页、树节点、重复控件 → 用稳定的领域 ID同一控件在多个地方重复 → 用所属对象给子 ID 加命名空间如(delete-project, project.id)这类组合翻译后的标签文本、可重排列表的下标 →绝不要拿它们派生身份重排或换语言会瞬间打乱所有状态归属render里每帧生成新鲜随机 ID → 状态永远累积不起来因为身份每帧都在换。同一规则适用于 overlay token、滚动句柄与持久化 ID两个各保留行为的行为体共享同一个键就会互相覆盖状态。布局与滚动谁拥有几何两个高频坑判断表如下症状原因修复一行全高列的头部被裁出窗口顶部h_flex在交叉轴居中子项列取内容高度而非行高给行加items_stretch()或给列加h_full()弹性子项里的长内容把容器撑爆flex 项默认拒绝围绕内容收缩对弹性子项加min_w_0()/min_h_0()测量是弹层、虚拟化、编辑器的深层工具不是布局手段只有普通布局表达不了关系时才在 prepaint 观察 bounds且测量数据要视为帧级/修订级作用域——排版、rem 尺寸或内容变了它就过期。每个可滚动区域must只有一个所有者把Scrollable挂在拥有整个面板视口的元素上内容 inset 放进滚动所有者内部而不是用带 padding 的容器包住它。端到端走查一个最小例子里每一行落在哪一层 以 examples/hello_world/src/main.rs 为蓝本把它拆开看每一步的归属。视图本体是一个值类渲染器每行都在声明这一帧长什么样impl Render for Example { fn render(mut self, _: mut Window, _: mut ContextSelf) - impl IntoElement { div() .v_flex() .gap_2() .child(Hello, World!) .child(Button::new(ok).primary().label(Lets Go!)) } }它对应决策树的第一档输入全是字面量、无需跨帧记忆所以Example没有字段、不建实体Button也是值类组件。接下来是入口它演示了启动期的两条 must 规则gpui_kit::application().run(move |cx| { gpui_kit::init(cx); gpui_kit::open_window(WindowOptions::default(), cx, |_, cx| cx.new(|_| Example)) .expect(Failed to open window); });gpui_kit::init(cx)must只调用一次——它按启用特性初始化gpui-component进而初始化gpui-base见 crates/kit/src/lib.rs 中init的文档。gpui_kit::open_window会自动用 BaseRoot包住你的视图窗口级的 overlay、通知、菜单设施由此生效不要为一个窗口里的每个页面再造独立 root绕过它静态截图看不出问题overlay 嵌套和焦点快速切换时会立刻暴露。如果这个按钮将来要读写状态走查的下一步就是加受控回调。对照 crates/component/src/checkbox.rs 的真实签名new收impl IntoElementId回调签名为Fn(bool, mut Window, mut App)Checkbox::new(show-hidden) .checked(self.show_hidden) // 受控当前值由所有者驱动 .label(Show hidden files) .on_change(|checked, _, _| { // 回调只上报意图所有者写入新值后 cx.notify() 触发重渲染 })注意方向值流是所有者 → 组件事件流是组件 → 所有者两条流不闭合回组件内部状态反馈循环就此断掉。最后看缩放链路。Root的渲染实现里有这样一行crates/component/src/root.rswindow.set_rem_size(cx.theme().font_size)。这意味着主题基础字体同时是应用 rem 设计尺度的锚点不只是正文字号。想全局改缩放正规做法是改锚点再同步 Base 投影Theme::global_mut(cx).font_size px(18.); Theme::sync_base(cx); window.refresh();sync_base会重建 Base 主题并写回全局crates/component/src/theme/mod.rs直接改主题公共字段后不调用它滚动条和 resize 手柄会拿着旧样式继续画。应用其余 UI 一律用相对辅助方法text_sm()、gap_2()、p_3()让文字、间距、控件随锚点一起缩放must不在应用代码里写裸 hex、rgb/rgba或裸px(...)例外仅限文档化的物理边界、运行时测量或 token 定义本身。约定速查表命名、所有权与 API 设计 ⚡这张表合并了词汇表与所有权规则评审前对着扫一遍。词汇是 API 的一部分——同一个概念在生态里必须用同一个词命名前先搜索 GPUI、gpui-base与组件层的既有术语。概念命名模式示例值类渲染控件名词Button、Tab保留行为模型ControlStateTableState、InputState命令式共享引用ControlHandleDialogHandle语义通知ControlEventSelectEvent可插拔数据/行为所有者RoleDelegate/RoleProviderTableDelegate布尔 readeris_形容词/has_名词不新增can_is_closable优于can_close通用非布尔替换 builderwith_fieldwith_item_ix就地变更mut selfset_fieldset_items回调注册on_事件或意图on_change、on_open_change精确领域词是硬规则混用会被评审打回selected是持久成员资格focused是键盘目标hovered是指针存在三者不可互换index是坐标id是稳定身份可重排数据must不按键值持久化 index。API 设计侧的要点私有字段是行为状态的默认公共字段只留给刻意的配置/序列化场景且每个含公共字段的公共 structmust标#[non_exhaustive]并提供构造器或 builder布尔 builder 用字段名disabled(bool)对应 reader 用is_disabled()流畅 builder 省略set_前缀消费并返回Self。on_click只留给真正的点击契约受控语义原语should用on_change(next_value, ...)——crates/component/src/checkbox.rs 里on_click已文档化为on_change的别名新代码直接选on_change更不容易误用。常见错误 vs 正确做法 错误做法正确做法一个实体装下全应用互不相关的状态按最小所有者拆给模型、视图、组件对可重排行用随机或下标做ElementId用稳定领域 ID必要时加对象命名空间应用代码里写死 hex 颜色与圆角从cx.theme().semantic_tokens()读语义角色见 crates/base/src/theme_tokens.rscolors/radius/spacing/typography/shadow 五个尺度刻意不含组件名在语义组件已提供键盘与焦点契约的地方手搓可点击div先用标准组件表达不了就改进其显式 API每次 render 都cx.notify()只在连贯状态变更结束后通知最窄的拥有实体两个 div 各自包一层滚动每个可滚动区域一个所有者滚动目标轴显式路由对可逆低风险操作弹确认框直接执行破坏性操作才确认测试只调内部方法用#[gpui_kit::test]走无头窗口演练指针、键盘与焦点结果回来就写入当前状态给异步结果附修订号/身份过期工作直接丢弃测试分层与上面同源在能证明行为的最低层测试——纯逻辑测试状态转移与几何GPUI 上下文测试实体与事件交互契约激活、受控变更、禁用、事件次序用 crates/kit/src/lib.rs 暴露的gpui_kit::test模块在无头窗口里驱动完整工作流留给示例冒烟测试。可确定性复现的 bug先补回归测试再修。提交前的自查清单 ✅状态与副作用的所有者能一句话说清render里没有无条件通知或重建实体RenderOnce与EntityT的选型有理由重复元素使用稳定领域 ID应用代码无裸 hex/rgb/裸px(...)自定义 spacing/elevation 尺度有明确存储方不指望写进全局主题后被semantic_tokens()读回键盘动作、焦点陷阱、overlay 开合与禁用态协同正常key_context与on_action挂在同一聚焦区域loading / empty / error / 取消路径在 UI 中都有表达错误不是只进日志大数据集走虚拟化组件键盘选择与滚动在模型坐标中进行新增公共 API 保持依赖方向向下、字段私有或#[non_exhaustive]测试在合适层证明了行为格式化与 Clippy 通过需要设计层面的取舍间距、层级、交互态、界面文案先读 website/docs/design-guides.md更完整的工程规范见 skills/gpui-kit/references/coding-guides.md组件级 API 细节以 website/component/ 下的各组件页与当前源码为准。记住本文只有一条主线先问谁拥有这份状态/这段行为再决定代码落在哪一层、用什么名字——其余所有规则都是这句话的推论。【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
