RedisInsight Workbench 插件产品级 UI 指南主题契约、样式基线与验证清单【免费下载链接】RedisInsightRedis GUI by Redis项目地址: https://gitcode.com/GitHub_Trending/re/RedisInsight本篇指南聚焦 RedisInsight Workbench 可视化插件Plugin的产品级 UI 规范覆盖内部插件与外部独立插件两种形态下的主题适配、样式基线、组件规则与验证流程。读完本文你将掌握如何在插件 iframe 内实现与 RedisInsight 产品视觉完全一致light/dark双主题的紧凑型 Workbench 界面并能够用/api/plugins与真实 Redis 命令完成端到端验证。核心原则内部插件与外部插件的 UI 策略分野RedisInsight 的插件体系存在两种形态UI 策略也因此分叉详见 .ai/skills/redis-insight-plugin/SKILL.md内部插件Internal Plugin默认形态代码位于redisinsight/ui/src/packages/plugin-name/随 RedisInsight 本体一起构建发布。UI 直接由 Redis UI 组件uiSrc/components/ui包装层搭建遵循仓库 frontend 风格指南使用布局组件、主题色与标准组件目录结构。外部独立插件External Standalone Plugin用户手动安装到~/.redis-insight/plugins/name/用 Parcel 独立打包不能importredis-ui/*、uiSrc/或任何 RedisInsight monorepo 内部包必须以本地代码模拟同一套产品外观。本指南正文中的 Standalone Constraints独立约束仅约束外部独立插件内部插件始终以组件库与产品 token 为唯一来源。官方权威文档见 docs/plugins/development.md 与 docs/plugins/installation.md。主题Theme契约只用 light / dark绝不使用 light2 / dark2RedisInsight 产品主题对是light/darklight2/dark2是其他 Redis 产品 UI 的主题严禁用于 RedisInsight 插件。这是最容易被忽略、却最影响观感一致性的契约。主题在 iframe 内通过body的 className 暴露docs/plugins/development.md 明确说明 Rendered iframe also includestheme_DARKortheme_LIGHTclassName onbodyto indicate the application theme usedtheme_LIGHT 浅色主题theme_DARK 深色主题读取方式有两种直接读 body classdocument.body.classList.contains(theme_DARK)见 redis-insight-plugin-guidelines.md 的实践记录优先使用redisinsight-plugin-sdk的主题 helper若使用了 SDK优先调用其 theme helper 获取主题模式仅在必要时将同一模式镜像到本地类。仓库内置插件的真实写法可以印证这一点。例如geodata插件在 styles.scss 中通过body.theme_LIGHT .geodata-shell覆盖一组本地 CSS 变量实现浅色主题下的配色切换ri-explain插件则在 Explain.tsx 中根据暗色布尔值选择节点与连线的颜色常量。外部插件的样式基线external-styles.scss外部 Parcel 插件无法访问 RedisInsight 内部 token因此仓库提供了一个可复制的样式基线文件 templates/external-styles.scss它就是产品 token 的本地化模拟。接入步骤将templates/external-styles.scss复制为src/styles/styles.scss保持package.json中的styles: ./dist/styles.css不动确保样式被 Parcel 打包进dist/styles.css——RedisInsight 会把这个样式文件注入到插件 iframe 中。若styles字段缺失或路径错误表现是插件渲染成功但完全没有样式可用grep -c styles类检查辅助定位详见 redis-insight-plugin-guidelines.md 的 Troubleshooting 表。基线中的 CSS 变量体系基线文件定义了两套完整的变量分别在body.theme_LIGHT含body:not(.theme_DARK)兜底与body.theme_DARK下生效变量浅色主题值深色主题值语义--ri-bg#ffffff#101820页面背景--ri-surface#f7f8fa#17232d面板表面--ri-surface-strong#eef1f4#20303c强调表面--ri-border#d9dfe5#334654边框/分隔线--ri-text#0f1f2a#eef3f7主文本--ri-muted#5f6f7a#aab7c0次级文本--ri-primary#3366ff#8fb3ff主操作色--ri-primary-soft#edf3ff#172a45主色浅底--ri-success#0b7a4b#54d18f成功语义色--ri-success-soft#e8f6ef#103123成功浅底--ri-danger#b3261e#ff8a80危险/错误语义色--ri-danger-soft#fdeceb#3a1d1b危险浅底--ri-code-bg#101820#0a1117代码块背景--ri-code-text#f5f7fa#f5f7fa代码块文本同时定义字体变量--ri-font-bodyGeist, Inter, -apple-system, ...无衬线栈与--ri-font-codeSource Code Pro, SFMono-Regular, Consolas, monospace等宽栈根元素设置font-size: 62.5%正文默认1.4rem。基线的内置组件类模板还预置了一组开箱即用的组件类可直接作为外部插件的最小 UI 骨架.ri-plugin-shell插件外壳min-height: 100vh、内边距1.6rem所有插件样式的作用域挂载点.ri-plugin-panel带边框与圆角的面板容器.ri-plugin-header/.ri-plugin-rowFlex 布局的头部/行容器justify-content: space-between.ri-plugin-title/.ri-plugin-subtitle/.ri-plugin-meta标题、副标题与元信息.ri-plugin-badge/.ri-plugin-badge--success胶囊状状态徽章如成功徽章使用--ri-success-soft底 --ri-success文字.ri-plugin-command单行命令文本超出省略text-overflow: ellipsis.ri-plugin-code代码/原始值块max-height: 36rem且overflow: auto深色代码背景.ri-plugin-error错误态面板危险色边框与浅底。UI 规则紧凑的 Workbench 风格界面插件渲染在 Workbench 的结果面板 iframe 内应构建紧凑型Workbench 风格表面而不是大而空的 Web 页面组件形态工具栏toolbar、表格table、检查器inspector、代码/数值面板code/value panel以及空态empty、错误态error、加载态loading布局偏好Redis 命令响应优先采用表格 详情table-plus-detail布局——上层表格概览、下层或侧栏展示选中行的详情字体Redis 键名、Stream ID、命令、原始值和时间戳使用Source Code Pro或等宽字体栈对应--ri-font-code状态徽章使用文字 颜色双通道表达状态绝不能只依赖颜色兼顾色盲用户与可读性语义色成功、警告、危险、选中、中性等状态必须使用产品语义色即上述--ri-*变量不要自创配色控件稳定性长键名与 JSON 必须滚动、有意换行或以省略号 title/tooltip 呈现防止破坏 iframe 布局。内部插件由uiSrc/components/ui组件自动继承上述规则外部插件则通过复制的external-styles.scss基线获得同一套变量与类。独立插件约束Standalone Constraints外部独立插件必须遵守以下硬性约束否则会破坏隔离性或视觉一致性禁止导入uiSrc/、redis-ui/*、RedisInsight monorepo 包或任何私有源码禁止使用全局 CSS reset——它会与 iframe 宿主样式冲突样式作用域所有样式收拢在插件类下如.ri-plugin-shell避免污染 iframe 外环境品牌红克制不得把 Redis 品牌红用作通用强调色、标题色、CTA 色、错误色或状态色——它只属于品牌时刻brand moments。内部插件虽然可以 import 共享组件也应避免在插件代码中硬依赖ThemeProvider等 Insight 专属 Provider以免未来插件被外部复用时失效见 redis-insight-plugin-guidelines.md。把 UI 契约接入插件激活函数UI 规范最终落到插件入口。一个遵循产品 UI 契约的激活函数骨架如下结合 docs/plugins/development.md 的 props 契约与 redis-insight-plugin-guidelines.md 的防御式写法import { getTheme } from redisinsight-plugin-sdk; function renderExampleView(props) { const root document.getElementById(app); if (!root) { console.error([EXAMPLE_PLUGIN] #app element missing); return; } try { const { command, data [] } props; const [{ response, status }] data; // 主题优先走 SDK helperSDK 不可用时回退到 body class const isDark getTheme?.() dark || document.body.classList.contains(theme_DARK); // 空态data 缺失或为空时渲染空状态面板 if (!data.length) { root.innerHTML div classri-plugin-panelNo data/div; return; } // 正常渲染表格/详情/徽章等紧凑组件 } catch (err) { console.error([EXAMPLE_PLUGIN] render failed, err); root.innerHTML div classri-plugin-errorPlugin failed. See console./div; } } export default { renderExampleView };激活函数接收{ command, data }data为结果数组单项为{ response, status }Standalone 场景通常一项。额外的运行参数通过window.state提供const { config, modules } window.state其中config.baseUrl可用于引用插件自身资源config.appVersion为应用版本docs/plugins/development.md。产品级 UI 还需要 manifest 配合visualizations数组中每个条目必须包含id、name、activationMethod、matchCommands、description、default字段activationMethod必须与默认导出的函数名完全一致参考内置插件 clients-list/package.json 中renderClientsList与renderJSON的声明方式。matchCommands支持正则字符串如FT.*并用大写命令名匹配。验证清单双主题 四状态端到端验收UI 是否符合产品规范最终靠运行验证。完整步骤如下确认插件已被加载启动 RedisInsight 后执行curl -s http://localhost:5540/api/plugins响应中必须包含插件的name与其visualizationsredis-insight-plugin-guidelines.md 提醒部署后务必执行缓存的菜单会骗人。在 Workbench 中运行匹配命令逐一验证theme_LIGHT与theme_DARK两种主题下渲染正确切换应用主题后重跑命令空态、加载态、错误态、成功态四种状态均有样式可分别用空结果命令、超时命令、正常命令触发表格与pre代码块不会导致 iframe 溢出或布局错乱浏览器控制台无样式错误与运行时错误。内部插件额外检查npm run build后确认dist/index.js与dist/styles.css存在且grep -c process.env dist/index.js返回0Parcel 构建不得遗留process.env.*引用。对于外部插件可配合 templates/verify-plugin.sh 脚本完成文件存在性、process.env与激活函数名的自动化校验。常见样式问题排查症状可能原因修复插件功能正常但无样式styles字段缺失或路径错误补styles: ./dist/styles.css并确认文件存在样式污染宿主页面使用了全局 CSS reset 或未作用域化类名删除 reset将所有规则收拢到.ri-plugin-shell下深色主题下配色错乱未读取theme_DARKbody class 或未镜像 SDK 主题按body.theme_DARK覆盖本地变量或调用 SDK theme helper品牌红大面积出现把--ri-danger/品牌红当通用强调色主操作使用--ri-primary品牌红只留给品牌时刻长命令/长 JSON 撑破布局未做滚动/换行/省略处理使用.ri-plugin-command的 ellipsis 或.ri-plugin-code的overflow: auto以上排查项与 redis-insight-plugin-guidelines.md 的 Troubleshooting 表相互补充可作为插件 UI 验收的最终兜底清单。【免费下载链接】RedisInsightRedis GUI by Redis项目地址: https://gitcode.com/GitHub_Trending/re/RedisInsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考