FxStatistic 统计组件

展示统计数值与倒计时。含 FxStatistic（统计数字）与 FxCountdown（倒计时）两个组件。不依赖任何 UI 框架，样式走 @fx/styles token。

FxStatistic / FxCountdown 属于 @fx/components。

基础用法

突出一个或一组数字（统计值、金额、排名等），可在数字前后与标题处加图标、单位等元素；总交易数一列用 requestAnimationFrame 做了线性过渡（文档站无 @vueuse/core，用原生 rAF 实现）。

<template>
  <div class="statistic-grid">
    <div class="statistic-cell">
      <FxStatistic title="日活用户" :value="268500" />
    </div>
    <div class="statistic-cell">
      <FxStatistic :value="138">
        <template #title>
          <span class="title-with-icon">
            男女比例
            <FxIcon name="ep:male" :size="12" />
          </span>
        </template>
        <template #suffix>/100</template>
      </FxStatistic>
    </div>
    <div class="statistic-cell">
      <FxStatistic title="总交易数" :value="outputValue" />
    </div>
    <div class="statistic-cell">
      <FxStatistic title="反馈数" :value="562">
        <template #suffix>
          <FxIcon name="ep:chat-line-round" />
        </template>
      </FxStatistic>
    </div>
  </div>
</template>

<script setup lang="ts">
import { onMounted, ref } from "vue"

// EP 用 useTransition 做数字过渡；fx 文档站无 @vueuse/core，用 rAF 线性过渡对齐
const outputValue = ref(0)
onMounted(() => {
  const target = 172000
  const duration = 1500
  const start = performance.now()
  const step = (now: number) => {
    const t = Math.min((now - start) / duration, 1)
    outputValue.value = Math.floor(target * t)
    if (t < 1) requestAnimationFrame(step)
  }
  requestAnimationFrame(step)
})
</script>

<style scoped>
.statistic-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: 16px;
}
.statistic-cell {
  text-align: center;
}
.title-with-icon {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
</style>

倒计时

FxCountdown 是薄包装 FxStatistic 的倒计时组件，到达目标时间触发 finish，每帧触发 change。value 设置目标时间（时间戳毫秒或 Dayjs），默认 format="HH:mm:ss"；format 支持 Y / M / D / H / m / s / S token，[ ] 包裹的内容视为转义文本不参与替换。

<template>
  <div class="countdown-grid">
    <div class="countdown-cell">
      <FxCountdown title="开始抢购" :value="value" />
    </div>
    <div class="countdown-cell">
      <FxCountdown title="VIP 剩余时间" format="HH:mm:ss" :value="value1" />
      <div class="countdown-footer">
        <FxBtn type="primary" size="small" @click="reset">重置</FxBtn>
      </div>
    </div>
    <div class="countdown-cell">
      <FxCountdown format="DD [天] HH:mm:ss" :value="value2">
        <template #title>
          <span class="title-with-icon">
            <FxIcon name="ep:calendar" :size="12" />
            距下月还有
          </span>
        </template>
      </FxCountdown>
      <div class="countdown-footer">
        {{ value2.format("YYYY-MM-DD") }}
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { dayjs } from "@fx/utils"

const value = ref(Date.now() + 1000 * 60 * 60 * 7)
const value1 = ref(Date.now() + 1000 * 60 * 60 * 24 * 2)
const value2 = ref(dayjs().add(1, "month").startOf("month"))

function reset() {
  value1.value = Date.now() + 1000 * 60 * 60 * 24 * 2
}
</script>

<style scoped>
.countdown-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  gap: 16px;
}
.countdown-cell {
  text-align: center;
}
.countdown-footer {
  margin-top: 8px;
}
.title-with-icon {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
</style>

TIP

格式范围建议在天（DD）及以上。月 / 年按近似值（30 天 / 365 天）计算，跨度大时会有精度偏差。

卡片用法

卡片式统计展示，可自由组合：标题加 tooltip 提示、底部加环比与箭头图标。

<template>
  <div class="card-grid">
    <div class="statistic-card">
      <FxStatistic :value="98500">
        <template #title>
          <span class="title-with-icon">
            日活用户
            <FxTooltip content="一天内登录产品的用户数" placement="top">
              <FxIcon name="ep:warning" :size="12" />
            </FxTooltip>
          </span>
        </template>
      </FxStatistic>
      <div class="statistic-footer">
        <div class="footer-item">
          <span>较昨日</span>
          <span class="green">
            24%
            <FxIcon name="ep:caret-top" :size="12" color="var(--fx-color-success)" />
          </span>
        </div>
      </div>
    </div>

    <div class="statistic-card">
      <FxStatistic :value="693700">
        <template #title>
          <span class="title-with-icon">
            月活用户
            <FxTooltip content="一个月内登录产品的用户数" placement="top">
              <FxIcon name="ep:warning" :size="12" />
            </FxTooltip>
          </span>
        </template>
      </FxStatistic>
      <div class="statistic-footer">
        <div class="footer-item">
          <span>环比</span>
          <span class="red">
            12%
            <FxIcon name="ep:caret-bottom" :size="12" color="var(--fx-color-danger)" />
          </span>
        </div>
      </div>
    </div>

    <div class="statistic-card">
      <FxStatistic :value="72000">
        <template #title>今日新增交易</template>
      </FxStatistic>
      <div class="statistic-footer">
        <div class="footer-item">
          <span>较昨日</span>
          <span class="green">
            16%
            <FxIcon name="ep:caret-top" :size="12" color="var(--fx-color-success)" />
          </span>
        </div>
        <div class="footer-item">
          <FxIcon name="ep:arrow-right" :size="14" />
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
  gap: 16px;
}
.statistic-card {
  height: 100%;
  padding: 20px;
  border-radius: 4px;
  background-color: var(--fx-bg-color);
  border: 1px solid var(--fx-border-color);
}
/* EP 用 --el-statistic-content-font-size: 28px 覆盖；fx 用 :deep 等价 */
.statistic-card :deep(.fx-statistic__content) {
  font-size: 28px;
}
.statistic-footer {
  display: flex;
  justify-content: space-between;
  align-items: center;
  flex-wrap: wrap;
  font-size: 12px;
  color: var(--fx-text-color-secondary);
  margin-top: 16px;
}
.footer-item {
  display: flex;
  justify-content: space-between;
  align-items: center;
}
.footer-item span:last-child {
  display: inline-flex;
  align-items: center;
  margin-left: 4px;
}
.title-with-icon {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
.green {
  color: var(--fx-color-success);
}
.red {
  color: var(--fx-color-danger);
}
</style>

Statistic API

Attributes

参数	说明	类型	默认值
value	数值内容	number | Dayjs	0
title	标题	string	—
prefix	前缀（与 prefix slot 互斥）	string	—
suffix	后缀（与 suffix slot 互斥）	string	—
decimal-separator	小数点分隔符	string	'.'
group-separator	千分位分隔符	string	','
precision	数值精度（小数位数）	number	0
formatter	自定义数值呈现（优先级最高）	(...args: any[]) => string | number	—
value-style	数值样式	StyleValue	—

Slots

名称	说明
title	自定义标题
prefix	自定义前缀
suffix	自定义后缀

Exposes

名称	说明	类型
displayValue	当前显示值	ComputedRef<string | number>

Countdown API

Attributes

参数	说明	类型	默认值
value	目标时间（时间戳毫秒或 Dayjs）	number | Dayjs	0
format	格式化（Y/M/D/H/m/s/S，转义用 [ ]）	string	'HH:mm:ss'
prefix	前缀	string	—
suffix	后缀	string	—
title	标题	string	—
value-style	数值样式	StyleValue	—

Events

名称	说明	类型
change	每帧触发，参数为剩余毫秒	(value: number) => void
finish	倒计时归零时触发	() => void

Slots

名称	说明（透传 FxStatistic）
title	自定义标题
prefix	自定义前缀
suffix	自定义后缀

Exposes

名称	说明	类型
displayValue	当前显示值（格式化字符串）	ComputedRef<string>

实现说明

• Statistic 数值规则：formatter 优先 → 非数字或 NaN 原样返回 → 数字按 precision 补零/截断、groupSeparator 三位分隔、decimalSeparator 拼接小数。
• Countdown 薄包装：内部渲染 <FxStatistic>，formatter 固定为按 format 渲染剩余毫秒；驱动方式用浏览器原生 requestAnimationFrame，每帧计算 timestamp - Date.now()，到 0 停止并触发 finish。
• format token：Y/M 为近似值（月按 30 天、年按 365 天）；S 为毫秒，SSS 显示三位毫秒。
• 样式 token：标题 --color-text-secondary + --fw-normal + 14px；数值 --color-text-primary + --fw-normal + 20px，prefix/suffix 各 4px 间距，统一走 @fx/styles token 不引用第三方框架变量。