gpui-base 原语目录GPUI 无样式行为组件全景指南【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit导读gpui-base代码库内 crate 名为gpui-base通过gpui_kit::base暴露是 GPUI Kit 的无样式行为层它只交付交互行为、受控状态、焦点管理与无障碍语义把所有视觉表现交给应用。本文以 原语目录 为骨架完整梳理 41 个面向用户的原语及其公开导入路径、最小可用组合与运行方式并结合crates/base源码与共享 showcase 示例说明行为层与表现层如何解耦、以及如何在自己的设计系统中组合这些部件。设计哲学行为内置表现归应用在深入目录之前先明确 gpui-base 的核心立场见 crates/base/src/lib.rs 顶部文档与 GPUI Base 总览行为内置控件提供一致的指针、键盘、焦点和状态行为开发者无需重复实现。表现由应用决定直接组合 GPUI 样式方法和 children不需要覆盖默认视觉——因为原语默认就没有产品级视觉。部件可组合每个原语暴露有意义的子部件如AccordionHeader、AccordionPanel、SliderTrack而不是把结构藏在单体组件中。状态明确受控输入通过回调报告变化最终状态由 view父渲染类型或 GPUI entity持有回调中更新并调用cx.notify()。依赖方向始终由上层指向基础层gpui-component构建于gpui-base之上应用可以只使用gpui-base自建设计系统也可以直接使用gpui-component的成品组件。原语目录总览下表是面向用户的完整原语清单链接指向中文文档各原语页面导入路径以gpui_kit::base::为前缀原语中文文档核心行为Accordionaccordion.md由可独立设置样式的标题、触发器和面板组成的折叠组Alert Dialogalert-dialog.md用于需要明确确认之操作的模态对话框Avataravatar.md带可组合后备内容的人物或实体图像Buttonbutton.md无样式、可访问且支持键盘激活的按钮Calendarcalendar.md支持选择匹配器和自定义日期渲染的状态驱动日历Checkboxcheckbox.md指示器可单独设置样式的受控三态复选框Collapsiblecollapsible.md不限定触发器样式的可折叠内容区域Color Pickercolor-picker.md构建自定义颜色选择器所需的状态和交互基础Comboboxcombobox.md结合文本输入、键盘导航建议和选择行为的组合框Date Pickerdate-picker.md将日历与弹出层组合起来、可感知焦点的日期输入Dialogdialog.md带焦点管理、遮罩、标题和关闭部件的可组合模态层Hover Cardhover-card.md与指针或键盘触发器关联的延迟浮动卡片Inputinput.md支持选择、掩码、验证和数值步进的单行输入Textareatextarea.md支持固定行数、换行和自动增高的多行文本框Editoreditor.md支持高亮、行号槽、折叠、装饰和 LSP 扩展的代码编辑器基础Linklink.md样式由应用定义的可访问链接控件Nav Stacknav-stack.md支持 push、pop、forward 与 replace 的视图导航栈过渡生命周期可动画Number Inputnumber-input.md带递增、递减和步进行为的数字输入OTP Inputotp-input.md由共享文本状态驱动的多单元格验证码输入Paginationpagination.md显式管理当前页与总页数的受控分页器Popoverpopover.md支持受控或内部开关状态的锚定浮层Popuppopup.md底层触发器与锚定浮动内容宿主Progressprogress.md用轨道和指示器报告任务完成度Radioradio.md具有选中与禁用语义的受控单选项Radio Groupradio-group.md为单项选择提供分组与键盘导航Resizableresizable.md用于可调整分栏布局的面板组和拖拽手柄Scrollbarscrollbar.md连接 GPUI 滚动句柄或统一列表句柄的滚动条Selectselect.md由锚定且支持键盘导航的弹层驱动的选择控件Sheetsheet.md从边缘进入并管理关闭和焦点的模态层Sliderslider.md轨道、指示区和滑块可独立设置样式的范围输入Switchswitch.md轨道与滑块可分别设置样式的受控开关Tabletable.md用于组合表头、表体、行和单元格的语义化表格原语Tabstabs.md带受控选择的标签列表和可访问标签控件Toasttoast.md受管理、带动画的临时状态消息栈Toggletoggle.md用于格式等持久选择的受控双态按钮Toggle Grouptoggle-group.md将多个 Toggle 协调为单选或多选组Tooltiptooltip.md与触发元素关联、延迟显示且可定位的说明Treetree.md显式管理展开与选择状态的虚拟化层级列表公开导入与模块布局目录中的每个原语都能在 crates/base/src/lib.rs 找到对应的pub use导出。例如pub use accordion::{Accordion, AccordionHeader, AccordionItem, AccordionPanel, AccordionTrigger}; pub use dialog::{ Dialog, DialogBackdrop, DialogChangeReason, DialogClose, DialogDescription, DialogHandle, DialogPopup, DialogTitle, DialogTrigger, }; pub use slider::{Slider, SliderIndicator, SliderThumb, SliderTrack}; pub use toast::{Toast, ToastAdvance, ToastManager, ToastMotion, ToastOptions, ToastStack, ToastStackState, ...};除组件外lib.rs还导出了行为层所需的周边设施FocusTrapElement焦点陷阱、IndexPath、History与UndoHistory导航历史、theme_tokensColorTokens、RadiusTokens、ShadowTokens、SpacingTokens、TypographyTokens等语义 token、motiontransition/spring/keyframes 动画原语、text与text_selectionTextView 与窗口级文本选择等。最小可用组合从单个原语到整套应用原语的设计原则是部件可组合文档中每个页面都说明公开导入路径和最小可用组合。以 Accordion 为例组合关系如下use gpui_kit::base::{Accordion, AccordionHeader, AccordionItem, AccordionPanel, AccordionTrigger};Accordion折叠组的根容器持有稳定元素 ID如example-accordionAccordionItem单个可展开条目受控状态open由外部传入AccordionHeader条目头部内嵌触发器AccordionTrigger可聚焦、键盘可激活的触发器通过on_change回调上报下一展开状态AccordionPanel展开后显示的面板内容区。这些部件本身不带任何产品视觉宽度、边框、颜色、字号全部通过 GPUI 样式方法.w(px(270.))、.border_t_1()、.text_xs()等现场组合见共享 showcase 实现 crates/base/examples/showcase/components/accordion.rsAccordion::new(example-accordion) .w(px(270.)) .border_t_1() .border_color(super::example_rgb(0xd4d4d4)) .children(items.into_iter().enumerate().map(|(index, (question, answer))| { let open self.accordion_items[index]; let entity cx.entity().downgrade(); AccordionItem::new() .open(open) .header(AccordionHeader::new( AccordionTrigger::new(format!(accordion-trigger-{index})) .on_change(move |next, _, _, cx| { _ entity.update(cx, |this, cx| { this.accordion_items[index] next; cx.notify(); }); }) // …样式方法 )) .panel(AccordionPanel::new().child(answer)) }))这段代码同时演示了受控状态的正确写法展开状态保存在self.accordion_itemsshowcase 视图持有的状态回调里entity.update写入新值并cx.notify()而不是在每次渲染时重建持久状态。受控状态的处理约定文档在 Accordion、Dialog、Select 等页面反复强调同一条约定受控状态应保存在父渲染类型或 GPUI entity 中在回调中更新并调用cx.notify()不要在每次渲染时重建持久 entity。跨渲染保持每个ElementId稳定GPUI 才能保留元素和焦点状态。Checkbox、Switch、Radio、Toggle 等受控组件通过回调报告下一个值把它存进视图并在下一次渲染时传回。运行示例原生与 WASM 共用一份代码目录说明提到页面上方的在线示例由crates/base/examples构建也可以作为原生 GPUI 应用运行。这与仓库中的实际结构一致——见 crates/base/examples/README.md原生示例包gpui-base-examples只有一个入口二进制 crates/base/examples/native/src/bin/components.rs通过#[path]引入共享 showcase 模块入口根据命令行第一个参数选择组件 slug缺省显示 overviewlet component std::env::args().nth(1).unwrap_or_else(|| overview.to_string()); let app gpui_platform::application().with_http_client(...); showcase::run(app, component);原生与 WASM 编译的是同一份 showcase 代码crates/base/examples/showcase/mod.rsrun走原生窗口run_embedded走浏览器内嵌二者都先调用gpui_base::init(cx)初始化全局基础设施。运行某个原语的原生示例cargo run -p gpui-base-examples -- accordion cargo run -p gpui-base-examples -- button cargo run -p gpui-base-examples -- virtual-list不带 slug 运行则显示 overview 总览页cargo run -p gpui-base-examplesMotion 因为演示的是连续行为transition、spring、keyframes、presence、stagger有独立二进制cargo run -p gpui-base-examples --bin motiondock是 showcase 中较大的一个组件一个完全构建在 gpui-base 之上的可停靠工作区嵌套分栏、标签组、底部停靠区。由于 base 层不绘制任何内容crates/base/examples/showcase/components/dock.rs 需要自己实现DockAreaRenderer、TabGroupRenderer、TilesRenderertrait——这使它成为理解 dock 渲染器接缝renderer seam最小完整皮肤的最佳阅读材料cargo run -p gpui-base dock网站侧则把同一份 showcase 编译为wasm32-unknown-unknown通过?componentslug查询参数加载到各原语页面见 crates/base/examples/wasm。快速上手初始化与第一个控件若你的应用只使用gpui-base不引入gpui-component需要手动初始化use gpui_kit::AppContext as _; fn main() { gpui_platform::application().run(|cx| { gpui_kit::base::init(cx); // 在这里打开应用窗口。 }); }若应用已经调用gpui_kit::component::init其中已经包含 Base 初始化无需重复调用。gpui_base::init的职责见 crates/base/src/lib.rs初始化全局Theme、GlobalState以及 dialog、focus_trap、popover、sheet、combobox、color_picker、select、number_input、input、tree、text 等模块各自持有的全局基础设施。随后即可渲染原语并按需设置样式base 控件刻意不提供内边距、颜色或圆角请用普通 GPUI 方法设置样式use gpui_kit::prelude::*; use gpui_kit::{px, rgb}; use gpui_kit::base::Button; Button::new(save) .px_3().py_2().rounded(px(6.)) .bg(rgb(0x2563eb)).text_color(rgb(0xffffff)) .on_click(|_, _, _| println!(save)) .child(Save)默认颜色 Tokengpui-base通过ColorTokens::light()和ColorTokens::dark()提供可直接使用的浅色、深色语义调色板ColorTokens::default()使用浅色调色板。两套颜色均使用Hsla并与gpui-component的默认浅色、深色主题保持相同的语义角色use gpui_kit::base::{ColorTokens, SemanticThemeTokens, Theme}; // 根据应用当前外观选择对应调色板。 let colors if is_dark { ColorTokens::dark() } else { ColorTokens::light() }; Theme::global_mut(cx).tokens SemanticThemeTokens { colors, ..Default::default() };调色板描述的是语义角色而非某个组件的专用颜色background/foreground、surface/surface_foreground、primary、secondary、muted、accent、destructive、border、input、ring、selection及其前景色。能从既有角色推导的细节Base 组件就直接推导——例如链接颜色取自primary不再单独加 tokenselection之所以自成一个角色是因为选区绘制在文字下方必须保证文字清晰accent和ring都无法保证这一点。调用gpui_kit::component::init时当前浅色或深色主题会自动映射到同一套 Base token只使用gpui-base的应用应在外观模式变化时安装对应的调色板。底层支撑这些原语依赖什么虽然目录页本身只列举原语但从crates/base/src/lib.rs的模块清单可以看清支撑整套原语的基础设施焦点与模态管理focus_trapFocusTrapElement、dialog、popover、sheet等模块在init中注册全局状态保证模态层之间的焦点隔离与关闭行为一致动画原语motion模块导出Transition、Spring、Keyframes、Presence、Stagger等类型供 Nav Stack 的过渡生命周期、Toast 的进出场等使用并有独立的基准 crates/base/benches/motion.rs虚拟化virtual_listVirtualList、v_virtual_list/h_virtual_list与Tree、Scrollbar协同服务超长列表与层级数据状态历史History导航轨迹与UndoHistoryundo/redo 事务在 history.md 中说明二者用途明确不同文本能力text与text_selection支撑 TextView、Editor、Input 与窗口级选区详见 text-view.md 与 text-selection.md主题 tokentheme_tokens把颜色、圆角、阴影、间距、排版收敛为语义 token保证原语不依赖具体视觉又能被主题系统驱动。可访问性与注意事项文档在每个原语页面都强调两类收尾工作可访问性让触发器可聚焦、可用键盘操作并向辅助技术暴露语义状态如展开/收起、选中、禁用。行为层的键盘导航、焦点管理已由原语内置应用只需保证元素 ID 稳定、语义角色正确。设计系统验证在消费端设计系统中验证焦点、悬停、按下、选中、禁用、减少动态效果和高对比度等状态——因为原语不带视觉这些状态的观感完全由应用负责。结语GPUI Base 的 41 个原语覆盖了从按钮、输入框到对话框、导航栈、虚拟树在内的完整交互骨架而把布局、颜色、尺寸与动效全部留给应用层。阅读目录时建议配合三份材料中文原语文档本文目录中逐页链接、共享 showcase 源码crates/base/examples/showcase/components/每个原语一份最小完整实现、以及gpui-base的导出清单 crates/base/src/lib.rs。原生与 WASM 共用同一份示例代码意味着先在浏览器里预览、再在桌面端运行可以零成本切换——这正是行为与表现分离带来的直接收益。【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
