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% 误导用户。
按自己的节奏,确认真正理解。