xtf-progress

组件说明

xtf-progress 是进度条组件，用于展示任务完成度或数据占比。支持 line（线性）/ circle（环形）/ dashboard（仪表盘）三种形态、渐变/玻璃/辉光/霓虹等变体、条纹/不定态/步骤分段等表现，配合 active 动效、format 自定义文案和 steps 步骤条能力，是数据展示层反馈进度的核心组件。

基础用法

1. 最简示例

通过 percentage 设置进度值（0~100），theme 控制主题色：

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-progress :percentage="30" />
    <xtf-progress :percentage="60" theme="success" />
    <xtf-progress :percentage="85" theme="warning" />
  </view>
</template>

2. 标题与描述

通过 title / desc 展示进度标题和描述，通过 show-text 控制百分比文字显隐：

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-progress :percentage="70" title="课程进度" desc="已完成 14/20 节" />
    <xtf-progress
      :percentage="45"
      title="上传进度"
      desc="正在上传中..."
      theme="info"
      :show-text="false"
    />
  </view>
</template>

3. 环形与仪表盘

通过 type="circle" / type="dashboard" 切换形态：

vue

<template>
  <view style="display: flex; gap: 64rpx; align-items: center; padding: 32rpx">
    <xtf-progress type="circle" :percentage="75" />
    <xtf-progress type="dashboard" :percentage="60" theme="success" />
    <xtf-progress type="circle" :percentage="90" theme="danger" :note="'风险'" />
  </view>
</template>

4. 条纹与不定态

通过 striped 开启条纹动画，通过 indeterminate 显示无限加载：

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-progress :percentage="50" striped />
    <xtf-progress indeterminate :show-text="false" />
  </view>
</template>

5. 步骤进度

通过 steps 将线性进度转为 N 段步骤条：

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-progress :percentage="60" :steps="5" title="注册进度" />
    <xtf-progress :percentage="40" :steps="4" theme="success" title="实名认证" />
  </view>
</template>

6. 自定义文案与激活动效

通过 format 自定义百分比文案，通过 active 开启从 0 到目标值的激活动画：

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-progress :percentage="80" :format="formatText" />
    <xtf-progress :percentage="100" active title="激活动画" desc="加载完成后展示" />
  </view>
</template>

<script>
export default {
  methods: {
    formatText(percentage) {
      // percentage 为当前显示值
      return percentage === 100 ? '已完成' : percentage + '%'
    }
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
`type`	`String`	`'line'`	形态：`'line'` / `'circle'` / `'dashboard'`	切换形态
`percentage`	`String \| Number`	`0`	进度值（0~100）	设置进度
`percent`	`String \| Number`	`undefined`	进度值别名（优先于 `percentage`）	兼容命名
`theme`	`String`	`'primary'`	主题色：`'primary'` / `'success'` / `'warning'` / `'danger'` / `'info'`	切换颜色
`variant`	`String`	`'gradient'`	变体：`'gradient'` / `'default'` / `'glass'` / `'glow'` / `'neon'`	切换视觉形态
`title`	`String`	`''`	标题	展示标题
`desc`	`String`	`''`	描述	展示描述
`note`	`String`	`''`	环形内部的备注文字（优先于 `desc`）	环形标注
`showText`	`Boolean`	`true`	是否显示百分比文字	显隐文案
`insideText`	`Boolean`	`false`	百分比文字是否显示在进度条内部	线性内嵌
`striped`	`Boolean`	`false`	是否显示条纹	视觉强调
`indeterminate`	`Boolean`	`false`	不定态无限加载	未知进度
`size`	`String`	`'md'`	尺寸：`'sm'` / `'md'` / `'lg'`	控制粗细/直径
`strokeWidth`	`String \| Number`	`''`	自定义描边宽度	精确控制
`trackColor`	`String`	`''`	自定义轨道颜色	精确控制轨道
`steps`	`String \| Number`	`0`	步骤分段数，`0` 为连续进度	步骤条
`indicator`	`Boolean`	`false`	仅声明的兼容属性，当前实现未消费，传入不会显示指示器	无实际展示效果
`color`	`String`	`''`	自定义激活色	精确控制颜色
`activeColor`	`String`	`''`	自定义激活色（同 `color`）	精确控制颜色
`active`	`Boolean`	`false`	是否激活从 0 到目标值的动画	加载动效
`activeMode`	`String`	`'backwards'`	激活动画模式：`'backwards'`	动效模式
`showInfo`	`Boolean`	`undefined`	显示文案（`show-text` 的兼容别名）；传入时优先于 `showText`	显隐文案
`format`	`Function`	`null`	自定义百分比文案，`(percentage: Number) => String`	自定义文案
`customClass`	`String`	`''`	自定义类名	样式覆盖
`customStyle`	`String \| Object`	`''`	自定义样式	动态样式覆盖

事件

xtf-progress 为纯展示组件，不对外抛出事件。如需在进度变化时做业务处理，可通过父级 v-model 绑定数值并配合 watch 实现。

示例：监听进度变化

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 32rpx; padding: 32rpx">
    <xtf-progress :percentage="progress" title="下载进度" />
    <xtf-button label="开始下载" :loading="downloading" @click="startDownload" />
  </view>
</template>

<script>
export default {
  data() {
    return { progress: 0, downloading: false }
  },
  watch: {
    progress(val) {
      console.log('进度变化:', val + '%')
      if (val >= 100) {
        this.downloading = false
        uni.showToast({ title: '下载完成', icon: 'success' })
      }
    }
  },
  methods: {
    startDownload() {
      this.downloading = true
      this.progress = 0
      const timer = setInterval(() => {
        this.progress += 10
        if (this.progress >= 100) {
          clearInterval(timer)
        }
      }, 400)
    }
  }
}
</script>

插槽

xtf-progress 暂未开放插槽，所有内容均通过属性配置。

主题说明

轨道色使用 var(--xtf-progress-track)，激活色使用 var(--xtf-progress-accent)，柔和色使用 var(--xtf-progress-soft)
描边宽度使用 var(--xtf-progress-stroke)，环形角度使用 var(--xtf-progress-angle) / var(--xtf-progress-dashboard-angle)
环形 dashboard 使用 conic-gradient 实现仪表盘
glass 变体轨道为半透明白色 + backdrop-filter 模糊
glow / neon 变体使用 box-shadow 发光

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

xtf-progress ​

组件说明 ​

基础用法 ​

1. 最简示例 ​

2. 标题与描述 ​

3. 环形与仪表盘 ​

4. 条纹与不定态 ​

5. 步骤进度 ​

6. 自定义文案与激活动效 ​

全部属性 ​

事件 ​

示例：监听进度变化 ​

插槽 ​

主题说明 ​