OpenMetadata Slider 组件设计规范全解从 token 体系到 React 实现【免费下载链接】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导读本文基于 OpenMetadata 仓库中 slider.md 组件规范文档系统梳理 Slider 滑动条在 OpenMetadata 设计系统中的定位、Anatomy结构拆解、token 配色、Props/API 契约与完整状态机并结合仓库内的样式文件与业务组件实现进行源码级印证。读完你将掌握如何在 OpenMetadata 的 token 体系下正确使用 Slider、新老两套技术栈UntitledUI Tailwind 与 Ant Design Less之间的迁移关系以及如何编写不触发 CI 审计失败的组件样式。组件定位连续范围选择器适用场景Use whenSlider 在 OpenMetadata 中服务于从连续或分级的数值范围中做出近似选择的场景典型用例包括采样百分比sampling %数据质量与画像任务中按比例抽取样本如 profiler 的采样率配置阈值设定thresholds告警、数据质量规则中的阈值边界双滑块区间选择two-thumb range同时设定最小值和最大值。其核心特征是近似位置比精确数值更重要——用户通过拖动滑块在轨道上定位获得的是直观的比例感而非键入的精确值。不适用场景Dont use when规范明确划定了两条边界情况正确做法需要输入精确数值如 73.5%改用数字输入框number input候选是少量离散命名值如 3 个固定档位改用 Select 下拉选择这一判断逻辑在仓库中有真实业务印证SliderWithInput.tsx 正是把 Slider 与InputNumber组合使用——滑块的近似直觉与数字框的精确输入互为补充同时保留百分比0%/100%刻度标记并提供一个清空按钮data-testidclear-slider-input将值重置为null。这恰好诠释了规范中Slider 适合近似、数字输入适合精确的分工两者并不互斥而是可以配对出现。Anatomy滑动条的部件拆解规范用一幅 ASCII 示意图定义 Slider 的结构●─────────────── ← handle (thumb) ══════╪═════════════════════════════ ← filled track ═ / rail ─ 0 25 50 75 100 ← range labels (showRange)从下至上可拆解为四个部件部件说明rail轨道底色未填充部分的轨道即用户尚未选中的区域fill填充段已选中部分从起点延伸到当前值单滑块或两滑块之间双滑块handle滑块手柄可拖拽的圆形拇指含焦点环focus ringvalue tooltip / hover ghost值提示拖动或悬停时浮出的数值气泡属可选部件range labels范围刻度标签showRange开启时渲染的 min…max 刻度文字可选仓库中对应的 go-forward 版本specs/untitled/slider.md给出了更细的部件说明track rail fillthumb 尺寸为size-6hover 时出现半透明 ghost 预览手柄opacity-60浮层 tooltip 通过 portal 渲染。Token 体系Slider 使用的全部设计令牌OpenMetadata 的样式系统采用分层 token 架构详见 specs/README.mdLayer 1 globals.css 上游原始 token--color-*、--radius-*、--shadow-* …来自 openmetadata/ui-core-components是唯一事实来源 Layer 2 --om-* 项目别名定义在 tokens.css引用 Layer 1 并携带原始值兜底 Components 组件样式只引用 Layer 2禁止出现裸 hex / pxSlider 规范给出了一张完整的 token 映射表任何部件都必须通过var(--om-*)引用部件TokenRail--om-color-bg-quaternaryFill--om-color-bg-brand-solidFill禁用--om-color-bg-disabledHandle 表面 / 边框--om-color-bg-primary/--om-color-borderHandle 阴影--om-shadow-mdRail 与 handle 圆角--om-radius-full焦点环--om-color-focus-ringTooltip 表面 / 阴影--om-color-bg-primary/--om-shadow-lg范围标签 / 激活标签--om-color-text-tertiary/--om-color-text-brand过渡--om-duration-fast这些 token 的真实取值可在 tokens/token-reference.md 中核对例如--om-radius-full解析为9999px、--om-duration-fast为150ms、--om-color-focus-ring为#2e90fa、--om-color-bg-quaternary为#e9eaeb。选择语义化 token 的意义在 foundations/color.md 中有明确说明语义 token 会随.dark-mode自动翻转上游--color-*在.dark-mode作用域下被重定义--om-color-*因直接引用上游而继承这一行为而调色板 token 不表达页面 / 画布 / 表面的角色语义。阴影规范见 foundations/elevation.md--om-shadow-md属于第 3 级下拉、抬升卡片--om-shadow-lg属于第 4 级popover、菜单二者与 handle、tooltip 的层级关系正好匹配。Props / API 契约核心组件openmetadata/ui-core-components的Slider暴露以下 PropsProp取值minValue/maxValuenumber默认0/100stepnumber吸附步长value/defaultValuenumber|number[]传 2 个值即双滑块区间labelReactNodelabelPositiondefault、top、bottom、top-floating、bottom-floatinglabelFormatter(value) string自定义刻度文案formatOptionsIntl.NumberFormatOptions本地化数字格式化showRangeboolean渲染 min…max 刻度标签showHoverPreviewboolean轨道悬停时显示 ghost tooltiprangeCountnumber刻度数量最少 2isDisabledboolean继承自AriaSliderPropsonChange(value) void值得注意的契约细节区间模式value传number[]且含 2 个值时组件切换为双滑块 range 模式fill 填充在两个 thumb 之间无障碍a11yisDisabled、formatOptions等直接来自 React Aria 的AriaSliderProps基类说明该组件底层基于 React Aria 的无障碍交互模型实现键盘操作与读屏语义由 Aria 保证国际化formatOptions支持Intl.NumberFormatOptions配合labelFormatter可输出本地化的百分比或阈值文案。go-forward 版本specs/untitled/slider.md在此基础上补充了orientation、name两个 Aria 属性且formatOptions同样归入 Aria 侧。States完整状态机与视觉处理规范定义了 Slider 的六种状态及各自的 token 处理状态处理方式Track rail--om-color-bg-quaternaryTrack fill--om-color-bg-brand-solid禁用时 →--om-color-bg-disabledHandle--om-color-bg-primary--om-color-border--om-shadow-mdcursor: grabDraggingcursor: grabbing浮层 tooltip 使用--om-color-bg-primary表面Focushandle 使用--om-color-focus-ring的 outline2pxoffset 2pxDisabledfill 用--om-color-bg-disabledhandle 变暗cursor: not-allowed这里有一条容易被忽视的硬性规则规范中以引用块强调Focus 使用outline绝不使用tw:ring-*handle 边框绘制在::afterborderAfter2上——参见docs/colors.md§2.3.1仓库实际路径为 docs/colors.md。其原因是ring会绘制在边框外侧并叠加阴影之上破坏 focus ring 与 handle 边框之间的视觉层级outlineoutline-offset才能确保焦点环严格贴合 handle 轮廓、间距可控且在border-radius: full9999px 圆形下正确跟随圆角。代码示例Less 组件样式与 TSX 用法组件样式LessLegacy 层规范给出的样式示例严格遵循Layer 3 组件样式只引用 Layer 2 token的分层纪律/* Layer 3 — component styles reference Layer 2 tokens only */ .custom-slider { __rail { background: var(--om-color-bg-quaternary); border-radius: var(--om-radius-full); } __fill { background: var(--om-color-bg-brand-solid); } __handle { background: var(--om-color-bg-primary); outline: 1px solid var(--om-color-border); box-shadow: var(--om-shadow-md); transition: outline-color var(--om-duration-fast) ease; :focus-visible { outline: 2px solid var(--om-color-focus-ring); outline-offset: 2px; } } }这份示例同时示范了两个关键点任何部件都不出现裸 hex / rgba / px 间距否则yarn token-audit会以 error 级别失败并阻断 CIhandle 常态用 1px outline 模拟边框focus-visible时升级为 2px 2px offset 的焦点环。仓库现有的 src/styles/components/slider.less 是 legacy 阶段的 Ant Design 覆盖层仅做了一件事——让ant-slider-track跟随主题色primary-color。随着迁移推进这类.less文件属于被yarn tw-guard拦截的新增对象不允许新增.less文件新的 Slider 样式应直接在 core-components 中按 token 体系实现。TSX 用法import { Slider } from openmetadata/ui-core-components; Slider showRange aria-label{t(label.percentage)} defaultValue{30} maxValue{100} minValue{0} step{5} /;该示例展示了最小可用配置minValue/maxValue限定 0–100、step以 5 为吸附步长、showRange开启刻度标签、aria-label通过 i18nt(label.percentage)提供无障碍标签。go-forward 版本示例在此基础上加入label如t(label.threshold)与classNametw:max-w-md说明新栈中使用tw:utility 控制布局宽度。双栈迁移现状legacy vs go-forwardOpenMetadata 的 UI 正处于 Ant Design Less 向 UntitledUI Tailwind 迁移的过渡期详见 specs/README.mdSlider 是观察这一迁移的最佳样本之一维度Legacy已弃用Go-forward新工作组件Ant DesignSlideropenmetadata/ui-core-components→Slider样式方式.lessvar(--om-*)tw:utility class如tw:bg-brand-solidToken 来源tokens/token-reference.mdtokens/tailwind-utility-reference.md审计命令yarn token-audityarn tw-audit/yarn tw-guard规范文档components/slider.mduntitled/slider.md两条规范在 Anatomy、token 语义、状态处理上高度一致go-forward 用tw:bg-brand-solid/tw:bg-quaternary等 utility 表达了与--om-color-bg-brand-solid/--om-color-bg-quaternary相同的角色差异集中在实现载体与审计工具上。约束同样一致两套栈都不允许硬编码值——TSX 中用tw:token utility 或var(--color-*)存量.less中用var(--om-*)。对开发者而言这意味着新功能请直接使用openmetadata/ui-core-components的Slider并按 go-forward 规范书写如需维护存量.less样式必须遵守 token 纪律并通过yarn token-audit零 error才能合入。相关规范速查同层组件规范Select · Toggle switch · Button基础设计规范Color · Radius · Elevation · MotionToken 全量参考tokens/token-reference.md业务使用示例SliderWithInput.tsx【免费下载链接】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），仅供参考