OpenMetadata UI 设计体系解析Tag 标签组件的规范、令牌与核心组件实现【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata导读Tag 是 OpenMetadata 前端设计体系位于 openmetadata-ui/src/main/resources/ui/specs/components/tags.md中负责呈现可交互元数据标签的基础组件覆盖分类标签classification tags、术语表术语glossary terms与数据层级tiers等典型场景。本文以该规范文档为主体结合仓库中的真实样式源码tags.less、语义令牌定义tokens.css以及 Badge 等兄弟组件规范系统讲解 Tag 的适用边界、结构解剖、令牌映射、Props/API、交互状态与可复用的 LESS/TSX 实现帮助你在 OpenMetadata UI 中正确使用并扩展 Tag 组件。组件定位什么时候用 Tag什么时候不该用规范将 Tag 归类为Base / metadata级别的基础组件状态为Stable其组件实现分散在两条技术线上现代实现openmetadata/ui-core-components包中的Tag、TagGroup、TagList新增工作遗留实现Ant DesignTag与自研tier-tag。Use when适用场景表示可交互的元数据标签——分类标签、术语表术语、数据层级tier——这些标签可以被选择select、计数count或移除remove。Dont use when不适用场景规范给出了两条清晰的边界当 chip 是只读的状态或计数时应改用 Badge而非 Tag当 chip 承担按钮职责时应改用 Button而非 Tag。这与 Badge 规范形成互补Badge 的定位是非交互的状态、计数或内联类别标签如实体 tier、管道状态、标题旁的项目计数其明确写着当 chip 可点击、可移除或可选中时请使用 Tags。因此判断口诀可以概括为可交互 → Tag纯展示 → Badge要触发动作 → Button。AnatomyTag 的结构解剖规范的解剖图ASCII展示了 Tag 从左到右的可选部件组合┌──────────────────────────────────────┐ │ [☑] ●/avatar Label [count] [×] │ └──────────────────────────────────────┘ │ │ │ │ │ │ │ │ │ └─ close X (removable) │ │ │ └─ count chip (bg-tertiary) │ │ └─ label: font-weight medium │ └─ optional avatar or status dot └─ optional selection checkbox各部件职责如下部件说明pill container胶囊容器承载全部内容的表面由背景色 ::after伪元素描边构成checkbox选择框可选仅在可选中模式下出现selectionMode为single/multipleavatar / dot头像/状态点可选置于标签文本前用于带图标的实体标签或状态指示label标签文本核心内容font-weight: medium中字重count chip计数块可选使用--om-color-bg-tertiary背景的独立计数块close X关闭按钮可选出现即代表标签可移除点击触发onCloseTokensTag 使用的设计令牌规范强调了一个值得注意的事实tags.less中真正的--om-*令牌只有圆角作用在tier-tag上现代 core-components 的 Tag 将剩余语义映射到全局语义令牌而遗留的tier-tag仍在使用purple-*LESS 变量。在仓库的 tags.less 中可以验证这一描述——遗留样式源码仅有 20 行import (reference) ../variables.less; .tier-tag { color: purple-5; background-color: purple-1; border-color: purple-5; border-radius: var(--om-radius-md); }规范给出的令牌映射表如下Part部件TokenCorner radius圆角--om-radius-mdSurface表面背景--om-color-bg-primaryLabel text标签文本色--om-color-text-secondaryCount chip surface计数块背景--om-color-bg-tertiaryHairline outline细描边--om-color-borderFocus ring焦点环--om-color-focus-ringTier tint遗留purple-1/purple-5--om-color-purple-50/--om-color-purple-700这些令牌的具体取值可以在 tokens.css 中找到定义均通过var(--xxx, fallback)方式级联上游设计令牌示例取值来自该文件--om-radius-md: var(--radius-md, 6px)--om-color-bg-tertiary: var(--color-bg-tertiary, #f5f5f5)--om-color-interactive-selected: var(--color-bg-brand-primary, #eff8ff)--om-color-focus-ring: var(--color-focus-ring, #2e90fa)--om-color-purple-50: var(--color-purple-50, #f4f3ff)--om-color-purple-700: var(--color-purple-700, #5925dc)。从 Radius 基础规范 看--om-radius-md为 6px用于按钮--om-radius-sm为 4px用于输入框、小型控件、tags这与 Tag 结构中使用--om-radius-sm修饰计数块的示例一致而 Badge 这类胶囊则使用--om-radius-full9999px。圆角统一走令牌而非裸写border-radius像素值是 Radius 规范 中明确的硬性约束yarn token-audit会把裸的border-radius值标记为警告。Props / APIcore-components 的 Tag 与 TagGroup规范的 API 表格定义了现代实现TagGroup/Tag的完整属性契约Prop取值/说明TagGroup.labelstringaria-label必填无障碍标签TagGroup.selectionModenone、single、multipleTagGroup.sizesm、md、lgTag.idstring需要选择/关闭功能时必填Tag.countnumber渲染计数块Tag.avatarSrc/Tag.dot前置头像或状态点Tag.isDisabledbooleanTag.onClose(id: string) void传入后渲染关闭 X几点实现层面的解读TagGroup.label是必填项TagGroup 在语义上是一个可聚焦的标签组必须提供aria-label供读屏软件识别这也是 UI 无障碍规范的一部分Tag.id与选择/关闭强绑定由于selectionMode支持单选/多选onClose回调签名是(id: string) void因此每个 Tag 必须有稳定的id才能被组内区分count与avatarSrc/dot是二选一的附加部件计数块与头像/状态点互不冲突均作为 label 之外的增强信息呈现。StatesTag 的六种交互状态StateTreatment处理方式Default默认--om-color-bg-primary背景 ::after上的--om-color-border描边Hover悬停关闭 X 表面出现色调可选中的行高亮Selected选中复选框勾选--om-color-interactive-selected表面色Focus聚焦--om-color-focus-ring焦点环2px 宽度、2px 偏移Disabled禁用变暗dimmedcursor: not-allowed规范附带了一条重要的实现约束以引用块强调描边放在::after上、焦点用outline—— 永远不要用tw:ring-*。这条约束的目的是保证焦点环不改变布局outline不占文档流、描边可通过伪元素灵活控制圆角裁切同时避免 Tailwind 的 ring 实现与设计令牌体系冲突。这属于层级 3组件样式只允许引用层级 2 令牌原则的具体体现——组件内部组合令牌、但不再引入新的原始像素值或框架专有写法。Code example可复用的实现示例样式层LESSLayer 3 组件样式只引用 Layer 2 令牌/* Layer 3 — component styles reference Layer 2 tokens only */ .custom-tag { border-radius: var(--om-radius-md); font-weight: var(--om-font-weight-medium); background: var(--om-color-bg-primary); color: var(--om-color-text-secondary); outline: 1px solid var(--om-color-border); outline-offset: -1px; .tag-count { background: var(--om-color-bg-tertiary); border-radius: var(--om-radius-sm); } .tier-tag { background: var(--om-color-purple-50); color: var(--om-color-purple-700); } }要点说明根容器使用border-radius: var(--om-radius-md)6px与tier-tag在 tags.less 中的圆角取值保持一致计数块.tag-count使用--om-radius-sm4px呼应 Radius 规范 中tags 用小圆角的指引描边通过outline实现并配合outline-offset: -1px与规范描边在::after/outline上、不用 ring的约束一致.tier-tag分支把遗留purple-*的视觉语义浅紫底purple-1、深紫字purple-5迁移到--om-color-purple-50/--om-color-purple-700令牌实现遗留样式 → 令牌化的渐进改造路径。组件层TSXcore-componentsimport { Tag, TagGroup, TagList } from openmetadata/ui-core-components; TagGroup label{t(label.tag-plural)} selectionModemultiple TagList Tag count{3} idpii onClose{onRemove}{t(label.pii)}/Tag /TagList /TagGroup;要点说明TagGroup承担标签组的容器与选择语义label传入国际化后的aria-label示例使用t(label.tag-plural)国际化函数TagList作为子元素集合包裹实际Tag示例中的pii标签携带count{3}展示 3 个相关项与onClose{onRemove}渲染可移除的关闭 X并处于multiple多选模式——完整覆盖了可选中、可计数、可移除三大核心交互能力。与设计体系其他部分的关系Tag 不是孤立组件规范末尾给出了明确的交叉引用关系同级组件Badge只读状态/计数与 Tag 互斥使用、Card卡片容器可在内部承载 Tag 列表、Button触发动作不可冒充 TagFoundation 基础层Color语义色板Tag 的选中/焦点/表面色均取自语义色、Radius圆角刻度md用于主体、sm用于计数块、Typographyfont-weight-medium的文本层级。从整个设计体系的视角看Tag 属于典型的语义令牌消费者组件它本身只在 tags.less 中保留了极少量的--om-*令牌圆角其余全部通过 core-components 映射到--om-color-*语义令牌。这种组件样式 → 语义令牌 → 基础令牌 → 上游设计变量的分层结构在 tokens.css 中以var(--xxx, fallback)逐级级联正是 OpenMetadata UI 设计体系保证跨主题、跨版本一致性的关键机制——当你需要自定义业务标签样式时遵循只引用--om-*令牌、不写裸像素值、描边用 outline/::after三条规则即可与现有体系无缝对齐。【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考