Vue / 系统课时

构建指标卡片

构建指标卡片

指标卡片要在很小的空间里同时说明“当前值、单位、变化趋势和数据状态”。本课将建立稳定的数据模型,并用一个 Vue 3 组件统一处理加载、正常、异常和无效数值,避免页面出现闪烁、误导颜色或 NaN。

学习目标

  • 设计可承载数值、单位、趋势和状态的指标数据结构
  • 实现加载、正常、错误与无效数据的展示分支
  • 正确区分趋势方向与业务上的正负含义

先定义展示状态

一张卡片至少要区分 loading、ready 和 error。加载时显示骨架,不要提前渲染零值;接口失败时给出明确占位;数据成功但数值非法时显示 —,不能把 null、NaN 或无穷大直接交给模板。

指标卡片的四种展示状态

趋势还要拆成“方向”和“语义”。例如投诉量下降通常是好事,销售额下降通常是坏事,因此不能简单规定向上永远显示绿色。数据层应显式提供 tone,由业务决定正向、负向或中性。

实现可复用卡片

下面的单文件组件可直接放入 Vue 3 项目中渲染。示例把状态数据写在组件内部,接入接口后只需替换 metric 的赋值来源。

vue
<script setup lang="ts">
import { computed, reactive } from 'vue'

type MetricStatus = 'loading' | 'ready' | 'error'
type TrendDirection = 'up' | 'down' | 'flat'
type TrendTone = 'positive' | 'negative' | 'neutral'

interface MetricCardData {
  title: string
  value: number | null
  unit: string
  precision: number
  status: MetricStatus
  errorMessage?: string
  trend?: {
    direction: TrendDirection
    percent: number | null
    tone: TrendTone
  }
}

const metric = reactive<MetricCardData>({
  title: '本月销售额',
  value: 128560.4,
  unit: '元',
  precision: 1,
  status: 'ready',
  trend: {
    direction: 'up',
    percent: 12.6,
    tone: 'positive'
  }
})

const displayValue = computed(() => {
  if (metric.status !== 'ready') return ''
  return typeof metric.value === 'number' && Number.isFinite(metric.value)
    ? metric.value.toLocaleString('zh-CN', {
        minimumFractionDigits: metric.precision,
        maximumFractionDigits: metric.precision
      })
    : '—'
})

const displayTrend = computed(() => {
  const percent = metric.trend?.percent
  return typeof percent === 'number' && Number.isFinite(percent)
    ? `${Math.abs(percent)}%`
    : ''
})

const trendSymbol = computed(() => {
  if (metric.trend?.direction === 'up') return '↑'
  if (metric.trend?.direction === 'down') return '↓'
  return '→'
})
</script>

<template>
  <section class="metric-card" :aria-busy="metric.status === 'loading'">
    <template v-if="metric.status === 'loading'">
      <div class="skeleton skeleton-title"></div>
      <div class="skeleton skeleton-value"></div>
    </template>

    <template v-else-if="metric.status === 'error'">
      <p class="title">{{ metric.title }}</p>
      <p class="error">{{ metric.errorMessage || '数据加载失败' }}</p>
    </template>

    <template v-else>
      <p class="title">{{ metric.title }}</p>
      <p class="value">
        {{ displayValue }}
        <span v-if="displayValue !== '—'" class="unit">{{ metric.unit }}</span>
      </p>
      <p
        v-if="metric.trend && displayTrend"
        class="trend"
        :class="`trend-${metric.trend.tone}`"
      >
        {{ trendSymbol }} {{ displayTrend }} 较上期
      </p>
    </template>
  </section>
</template>

<style scoped>
.metric-card {
  width: 280px;
  min-height: 132px;
  padding: 20px;
  border: 1px solid #e5e7eb;
  border-radius: 12px;
  background: #fff;
}
.title { margin: 0 0 12px; color: #6b7280; }
.value { margin: 0 0 10px; font-size: 30px; font-weight: 700; }
.unit { margin-left: 4px; font-size: 14px; color: #6b7280; }
.trend { margin: 0; font-size: 14px; }
.trend-positive { color: #15803d; }
.trend-negative { color: #b91c1c; }
.trend-neutral { color: #6b7280; }
.error { color: #b91c1c; }
.skeleton {
  border-radius: 6px;
  background: #e5e7eb;
  animation: pulse 1.2s ease-in-out infinite;
}
.skeleton-title { width: 45%; height: 16px; margin-bottom: 20px; }
.skeleton-value { width: 70%; height: 34px; }
@keyframes pulse { 50% { opacity: 0.45; } }
</style>

预期结果

text
页面显示“本月销售额”、格式化后的“128,560.4 元”,以及绿色“↑ 12.6% 较上期”。
把 status 改为 loading 时显示骨架;改为 error 时显示错误信息;把 value 改为 null 时显示“—”。

处理单位与异常值

单位应作为独立字段展示,不要预先拼进数值字符串,否则排序、格式化和国际化都会变困难。金额可使用千分位,比例可保留一到两位小数,次数或人数通常不显示小数。

接口返回后先验证类型和值域。负数是否允许、百分比是否可能超过 100%、零值是否代表真实业务结果,都应由当前指标定义决定。组件只负责稳定展示,业务校验应尽量在数据适配层完成。

验收卡片行为

验收时依次切换三种状态,并额外测试 null、NaN、极大数和缺失趋势。页面不应出现布局跳动、未定义文本或错误颜色;无趋势数据时应直接隐藏趋势行,而不是显示 0% 误导用户。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

构建指标卡片

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通