mailinapp
Documentation menu

仪表图模块

把单一指标与你自己定义的良好/警告/严重阈值区间进行对比——一种指针式表盘,而不是基于行数据的图表。它是为了回答"这个数字现在还好吗"这种问题而存在的:正常运行时间、错误率、NPS、延迟——任何适合用健康状态而非趋势或对比来呈现的指标。

工作原理

图片绘制一个由两个阈值分界点划分为三段颜色区间(良好、警告、严重)的半圆弧,并有一根指针指向手动输入的数值。与这个家族中其他每一种图表不同,仪表图完全没有行列表。它全部的"数据"只是五个标量数字:一个数值、一个最小/最大量程,以及两个阈值分界点——在形态上更接近 KPI 计分卡那单一的手动输入数值,而不是任何类别/系列/数据点表格。

这也是为什么仪表图是整个家族中唯一一个下方没有数据表格的图表模块。数据表格的存在是为了承载被图片锁进像素里的数字,但仪表图的数值和状态从一开始就不会被锁在图片里。它们会作为真实的 HTML 文本直接渲染在图片旁边:一行加粗的数值(格式化为纯数字、货币或百分比),紧跟着一个带颜色的状态词("Good""Warning" 或 "Serious")。图片下方还有一行小号的弱化文字,重复数值、状态和量程范围。这段文字是无条件的——无论图片是否加载成功都会渲染,与该家族中其他每一种图表用 <table> 履行的那份不容妥协的无障碍契约完全相同。

阈值区间始终使用保留的状态调色板(绿/琥珀/红),绝不是一个可以由你替换的字段——与瀑布图模块增加/减少颜色所遵循的"红色永远代表坏消息"信任规则相同。goodMax 和 warningMax 把 min–max 量程按顺序划分为三段递增的区间:良好,然后是警告,超过 warningMax 的部分则是严重。这是经典的"速度表"读法,数值低是安全的,数值高是风险的,比如 CPU 负载或错误率。对于数值越高反而越好的指标(比如 NPS 或正常运行时间分数),只需反过来手动输入阈值,把 goodMax 设置在接近 max 的位置即可,而不需要一个单独的"方向"标志。

可配置字段:

  • 标签——数值上方的可选标题文字。
  • 值——指标本身,以文本形式提供(因此可以携带合并标签)。
  • 格式——数字、货币,或百分比,控制数值以文本形式渲染的方式。
  • 量程最小值 / 量程最大值——表盘的 min/max 边界。
  • 良好区间上限——goodMax 分界点。
  • 警告区间上限(超过则为严重)——warningMax 分界点;超出这个值的部分渲染为严重区间。
  • 卡片的背景色、内边距、边框和圆角半径。
  • 数值颜色/字号和标签颜色/字号——大号数值行与标题标签的文字样式。

如果值为空,或者无法解析为一个数字(例如一个未解析的合并标签),模块会跳过绘制圆弧,只渲染标签和卡片外框,并用一条朴素的"请添加一个数值以渲染此仪表图"提示替代。手动输入的范围如果出现 min >= max,或者阈值顺序颠倒,会被自动纠正,而不会在编辑过程中出现一个损坏的表盘。

示例

一份 SLA 或正常运行时间快照——"本月正常运行时间 99.94%",99.9% 以上为良好,99.5% 以上为警告,低于此为严重——放进一份状态页摘要邮件中,能让订阅者无需点击仪表盘链接就获得一目了然的健康状态读数。一个支持团队可以把平均响应时间与目标 SLA 进行对比绘图(2 小时以内为良好,6 小时以内为警告,超过则为严重)。一份面向客户的 NPS 或满意度评分报告,可以在季度关系邮件中把仪表图作为头条视觉元素,阈值经过手动设置,使得高分读起来是良好而不是危险信号。

静态回退效果是什么样子

<div style="margin:12px 0;background-color:#ffffff;padding:16px">
  <p style="margin:0 0 4px;font-weight:600;font-size:13px;color:#6b7280">Uptime this month</p>
  <p style="margin:0 0 6px;font-weight:700;font-size:32px;color:#111827">
    99.94%  <span style="font-size:14px;font-weight:600;color:#16a34a">Good</span>
  </p>
  <img src="https://mailinapp.com/api/analytics/chart?d=eyJ0eXBlIjoi...&s=3f9a2b1c..." width="320" height="200"
       alt="Gauge: 99.94 of 0–100 (Good)" />
  <p style="margin:4px 0 0;font-size:11px;color:#9ca3af">Uptime this month — 99.94% (Good) — scale 0–100</p>
</div>

加粗的数值行和图片下方弱化的摘要行都是真实的 HTML 文本。数值和状态从不依赖圆弧图片是否渲染成功——这正是为什么仪表图是这个家族中唯一没有数据表格的模块。

相关内容