gpui-kit Tag 组件实战指南GPUI 桌面应用中的分类与状态标签【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kitTag标签是 gpui-kit 组件库中用于内容分类、状态标记与元数据展示的轻量级视觉指示器。本文将以 website/component/tag.md 为核心结合 crates/component/src/tag.rs 的源码实现系统讲解 Tag 的导入方式、语义变体、轮廓样式、尺寸控制、颜色定制、圆角组合以及标签云等实战场景帮助你在基于 GPUI 的跨平台桌面应用中快速落地统一的标签体系。导入 TagTag 组件位于gpui_kit组件库的component::tag模块。在使用前需在代码中导入Tag类型use gpui_kit::component::tag::Tag;需要用到颜色定制时再额外导入ColorName用到自定义 HSLA 颜色、圆角尺寸或布局工具时可一并引入use gpui_kit::component::ColorName; use gpui_kit::{hsla, Hsla, px}; use gpui_kit::component::{h_flex, v_flex};从源码看crates/component/src/lib.rs 中声明了pub mod tag;因此Tag可通过gpui_kit::component::tag::Tag访问同时crates/componentcrate 顶层通过pub use theme::*;等语句重导出了ColorName、hsla、px等辅助项见 crates/component/src/lib.rs。使用 Tag 前请确保已在应用入口调用gpui_kit::component::init(cx)完成主题等基础初始化见 crates/component/src/lib.rs。基础用法语义变体Tag 提供了 6 个开箱即用的语义变体分别对应不同的主题语义色。创建方式为调用对应构造方法再通过child(...)传入显示文本// Primary tag (default filled style) Tag::primary().child(Primary) // Secondary tag Tag::secondary().child(Secondary) // Status tags Tag::danger().child(Danger) Tag::success().child(Success) Tag::warning().child(Warning) Tag::info().child(Info)这些语义变体对应源码中的TagVariant枚举见 crates/component/src/tag.rsPrimary使用主题的primary色作背景、primary_foreground作前景文本Secondary使用secondary背景与secondary_foreground文本Danger/Success/Warning/Info分别映射danger、success、warning、info语义色及其*_foreground文本色。这些颜色字段定义在主题色结构体 crates/component/src/theme/theme_color.rs 的ThemeColor中Tag 通过cx.theme()读取当前全局主题见 crates/component/src/theme/mod.rs 的Theme::global因此标签外观会随主题自动切换。轮廓样式Outlineoutline()将标签切换为轮廓样式背景变为透明源码中使用transparent_white()见 crates/component/src/tag.rs文字颜色在多数语义变体下直接使用语义色本身边框色保持不变。轮廓样式在浅色/深色背景下都能保持边框可辨Tag::primary().outline().child(Primary Outline) Tag::secondary().outline().child(Secondary Outline) Tag::danger().outline().child(Error Outline) Tag::success().outline().child(Success Outline) Tag::warning().outline().child(Warning Outline) Tag::info().outline().child(Info Outline)从源码 crates/component/src/tag.rs 的fg(outline, cx)可以看到例如 Primary 在轮廓模式下前景色直接取cx.theme().primary而填充模式下取primary_foregroundSecondary 轮廓模式则使用muted_foreground。这正是轮廓标签在不同背景下仍保持可读的实现基础。尺寸控制Tag 的尺寸由Sizabletrait 提供见 crates/component/src/sizing.rs。Tag 支持Size::Medium默认与Size::Small两种尺寸还可通过with_size传入自定义像素值// Small size Tag::primary().small().child(Small Tag) // Medium size (default) Tag::primary().child(Medium Tag) // Custom pixel size use gpui_kit::px; Tag::primary().with_size(px(30.0)).child(Custom Size Tag)Size枚举定义于 crates/component/src/sizing.rs包含XSmall、Small、Medium默认、Large以及任意Pixels。从 crates/component/src/tag.rs 的渲染逻辑可见Small/XSmall 尺寸使用px_1p5().py_0p5()的紧凑内边距Medium 及以上使用px_2p5().py_1()同时源码注释明确Only support: Medium, Smallcrates/component/src/tag.rs因此实际使用中以 small 与默认中等尺寸为主。颜色定制预定义颜色ColorNameColorName枚举见 crates/component/src/theme/color.rs提供了 21 种可命名颜色包括White、Black、Neutral、Gray、Red、Orange、Amber、Yellow、Lime、Green、Emerald、Teal、Cyan、Sky、Blue、Indigo、Violet、Purple、Fuchsia、Pink、Rose。使用Tag::color(ColorName::...)即可创建任意颜色标签use gpui_kit::component::ColorName; Tag::color(ColorName::Blue).child(Blue Tag) Tag::color(ColorName::Green).child(Green Tag) Tag::color(ColorName::Purple).child(Purple Tag) Tag::color(ColorName::Pink).child(Pink Tag) Tag::color(ColorName::Indigo).child(Indigo Tag) Tag::color(ColorName::Yellow).child(Yellow Tag) Tag::color(ColorName::Red).child(Red Tag)ColorName还实现了TryFromstr因此也支持从字符串解析如blue、red见 crates/component/src/theme/color.rs。颜色变体对明暗主题做了差异化适配见 crates/component/src/tag.rs 与 crates/component/src/tag.rs浅色主题下背景使用color.scale(50)边框使用color.scale(200)前景使用color.scale(600)深色主题下背景使用color.scale(950)且透明度 0.5边框使用color.scale(800)且透明度 0.5前景使用color.scale(300)。这样同一ColorName在浅色与深色主题下都能保持适度的对比度无需手工切换颜色。自定义 HSLA 颜色当需要品牌色或设计系统专属颜色时使用Tag::custom(color, foreground, border)直接传入三个Hsla值背景色、前景色、边框色use gpui_kit::{hsla, Hsla}; // Custom colors with HSLA values let color hsla(220.0 / 360.0, 0.8, 0.5, 1.0); let foreground hsla(0.0, 0.0, 1.0, 1.0); let border hsla(220.0 / 360.0, 0.8, 0.4, 1.0); Tag::custom(color, foreground, border).child(Custom Color)hsla(h, s, l, a)中色相取 0.0 到 1.0 之间的归一化比值因此220.0 / 360.0表示 220° 的蓝色。源码中TagVariant::Custom直接透传这三个颜色见 crates/component/src/tag.rs、crates/component/src/tag.rs不经过主题换算。圆角控制Tag 默认圆角取自当前主题的radius令牌Small/XSmall 尺寸自动使用theme.radius / 2.Medium 及以上使用theme.radius见 crates/component/src/tag.rs。可以显式覆盖use gpui_kit::px; // Fully rounded tags Tag::primary().rounded_full().child(Rounded Full) // Custom border radius Tag::primary().rounded(px(4.0)).child(Custom Radius) // Square corners Tag::primary().rounded(px(0.0)).child(Square Tag)rounded_full()在源码中等价于rems(1.)见 crates/component/src/tag.rs形成胶囊形Pill标签rounded(radius)接受任何实现了IntoAbsoluteLength的值如px(4.0)这类像素值见 crates/component/src/tag.rs。样式组合各修饰方法可以自由链式组合构建出丰富的视觉形态// Small tags with full rounding Tag::primary().small().rounded_full().child(Small Pill) Tag::success().small().rounded_full().child(Success Pill) // Outline tags with custom rounding Tag::warning().outline().rounded(px(2.0)).child(Custom Outline) // Color tags with outline style Tag::color(ColorName::Purple).outline().child(Purple Outline)从渲染实现看crates/component/src/tag.rsTag 内部是一个div元素使用 flex 布局居中、1px 边框、text_xs字号、line_height(relative(1.25))并在 hover 时把整体透明度降到 0.9 提供悬停反馈同时实现了Styledtrait因此还可通过标准样式 API如.text_sm()、.font_bold()做进一步微调并通过.refine_style(self.style)应用用户自定义样式。典型场景示例标签集合用h_flex/v_flex组合多个标签即可构建横向标签组或纵向标签堆use gpui_kit::component::{h_flex, v_flex}; // Horizontal tag group h_flex() .gap_2() .child(Tag::primary().child(React)) .child(Tag::success().child(TypeScript)) .child(Tag::info().child(Next.js)) .child(Tag::warning().child(Beta)) // Vertical tag stack v_flex() .gap_1() .child(Tag::danger().small().child(Critical)) .child(Tag::warning().small().child(Important)) .child(Tag::secondary().small().child(Normal))状态仪表盘用语义变体呈现系统各模块的健康状态h_flex() .gap_3() .child( v_flex() .child(API Status:) .child(Tag::success().child(Operational)) ) .child( v_flex() .child(Database:) .child(Tag::warning().child(Maintenance)) ) .child( v_flex() .child(Cache:) .child(Tag::danger().child(Down)) )可交互标签列表Tag 本身是展示型组件源码中没有内置点击等交互处理器若需要筛选标签这类交互应在 Tag 外层用InteractiveElement包装如div().on_click(...)并配合应用状态管理// Filter tags (would need click handlers) h_flex() .gap_2() .child(Tag::primary().small().child(All)) .child(Tag::secondary().outline().small().child(Active)) .child(Tag::secondary().outline().small().child(Completed)) .child(Tag::secondary().outline().small().child(Archived))颜色编码的分类标签结合flex_wrap()让标签在空间不足时自动换行适合内容类型筛选use gpui_kit::component::ColorName; h_flex() .gap_2() .flex_wrap() .child(Tag::color(ColorName::Red).child(Bug)) .child(Tag::color(ColorName::Blue).child(Feature)) .child(Tag::color(ColorName::Green).child(Enhancement)) .child(Tag::color(ColorName::Purple).child(Documentation)) .child(Tag::color(ColorName::Yellow).child(Question)) .child(Tag::color(ColorName::Pink).child(Discussion))胶囊风格技能标签small()rounded_full()是技能/关键字标签的经典组合h_flex() .gap_2() .flex_wrap() .child(Tag::color(ColorName::Blue).rounded_full().small().child(Rust)) .child(Tag::color(ColorName::Green).rounded_full().small().child(JavaScript)) .child(Tag::color(ColorName::Purple).rounded_full().small().child(Python)) .child(Tag::color(ColorName::Red).rounded_full().small().child(Go))API 参考创建方法方法说明primary()创建 Primary 标签主题主色蓝色系secondary()创建 Secondary 标签灰色系danger()创建 Danger 标签红色系success()创建 Success 标签绿色系warning()创建 Warning 标签黄/橙色系info()创建 Info 标签蓝色系color(ColorName)使用预定义颜色名创建标签custom(color, fg, border)使用自定义 HSLA 颜色背景/前景/边框创建标签样式方法方法说明outline()应用轮廓样式透明背景见 crates/component/src/tag.rsrounded(radius)设置自定义圆角半径impl IntoAbsoluteLengthrounded_full()应用完全圆角形成胶囊形状尺寸方法来自 Sizable trait方法说明small()小尺寸标签紧凑内边距见 crates/component/src/sizing.rswith_size(size)设置自定义尺寸支持Size或PixelsSizabletrait 还提供xsmall()、large()快捷方法但 Tag 源码注释声明仅支持 Medium 与 Smallcrates/component/src/tag.rs实际渲染时 XSmall 与 Small 共用同一套紧凑内边距。内容方法来自 ParentElement trait方法说明child(element)向标签添加子内容文本、图标或任意 GPUI 元素Tag实现了ParentElementcrates/component/src/tag.rs因此child()可以接受任意实现了IntoElement的元素例如在标签中嵌入图标。行为说明结合源码 crates/component/src/tag.rs 的render实现Tag 的行为特性可以总结为标签外观完全跟随当前全局主题语义色、圆角、明暗模式无需手工适配轮廓标签使用透明背景边框与文字颜色随语义色/明暗模式自动调整在不同背景上均可辨小尺寸标签使用更紧凑的内边距px_1p5().py_0p5()适合紧凑布局自定义颜色ColorName与Custom都支持浅色/深色主题适配其中ColorName通过color.scale(n)按明暗模式取不同色阶Custom则原样透传Tag 是展示型组件不内置交互处理器交互需在外层元素上实现多个标签可在h_flex/v_flex等 flex 布局中自由组合配合flex_wrap()形成标签云圆角默认根据尺寸自动缩放Small 为theme.radius / 2.Medium 为theme.radius除非通过rounded()/rounded_full()显式覆盖Tag 在 hover 时应用opacity(0.9)的悬停反馈可在此基础上继续叠加自定义样式。设计指南何时使用 Tag内容分类Categorization按类型、主题或话题对内容分组状态指示Status Indication展示状态、进度或健康度如已完成维护中已下线元数据展示Metadata Display呈现属性、特性或分类信息筛选指示Filtering作为当前激活筛选条件的可视化指示器功能标记Feature Flags突出新Beta限量等特殊特性。颜色使用建议语义色错误用danger红、完成用success绿、警告用warning黄、信息用info蓝遵循用户对颜色的直觉认知分类色内容分类场景优先使用ColorName变体用颜色编码帮助快速识别自定义色仅在品牌色或设计系统有特定要求时使用Tag::custom。尺寸与圆角建议小尺寸标签用于紧凑布局、元数据行或空间受限的场景中等尺寸标签大多数场景的默认选择可读性与可点击面积均衡圆角需要胶囊形态时使用rounded_full()有具体设计规范时使用rounded()指定像素半径需要硬朗直角时传入px(0.0)。扩展阅读Tag 的完整源码实现crates/component/src/tag.rs尺寸枚举与Sizabletraitcrates/component/src/sizing.rs颜色名枚举ColorNamecrates/component/src/theme/color.rs主题色与全局主题访问crates/component/src/theme/theme_color.rs、crates/component/src/theme/mod.rs组件库入口与init初始化crates/component/src/lib.rs官方组件文档索引website/component/index.md【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考