Progress 进度条 - Vant 4

📈 Progress 进度条

🎯 介绍

Progress 组件用于展示操作的当前进度，支持设置颜色、线条粗细、状态置灰等，直观体现任务完成度，就像生活中的进度条一样清晰明了 ⏳

📦 引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from 'vue';
import { Progress } from 'vant';

const app = createApp();
app.use(Progress);

🚀 代码演示

🔧 基础用法

进度条默认为蓝色，使用 percentage 属性来设置当前进度，简单直观地展示完成状态 ✨

<van-progress :percentage="50" />

import { ref } from 'vue';

export default {
  setup() {
    // 模拟进度变化，动态展示进度效果 📊
    const percentage = ref(50);
    
    // 增加进度的函数
    const increaseProgress = () => {
      if (percentage.value < 100) {
        percentage.value += 10;
      }
    };
    
    // 重置进度的函数
    const resetProgress = () => {
      percentage.value = 0;
    };

    return {
      percentage,
      increaseProgress,
      resetProgress,
    };
  },
};

📏 线条粗细

通过 stroke-width 可以设置进度条的粗细，打造不同的视觉层次感 🎨

<van-cell-group>
  <van-cell title="细线条">
    <van-progress :percentage="50" stroke-width="2" />
  </van-cell>
  <van-cell title="标准线条">
    <van-progress :percentage="50" />
  </van-cell>
  <van-cell title="粗线条">
    <van-progress :percentage="50" stroke-width="8" />
  </van-cell>
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const percentage = ref(50);

    return {
      percentage,
    };
  },
};

🌫️ 置灰

设置 inactive 属性后进度条将置灰，表示禁用或暂停状态 ⏸️

<van-cell-group>
  <van-cell title="正常状态">
    <van-progress :percentage="50" />
  </van-cell>
  <van-cell title="置灰状态">
    <van-progress :percentage="50" inactive />
  </van-cell>
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const percentage = ref(50);
    const isInactive = ref(false);
    
    // 切换置灰状态
    const toggleInactive = () => {
      isInactive.value = !isInactive.value;
    };

    return {
      percentage,
      isInactive,
      toggleInactive,
    };
  },
};

🎨 样式定制

可以使用 pivot-text 属性自定义文字，color 属性自定义进度条颜色，打造个性化的进度展示 🌈

<van-cell-group>
  <van-cell title="自定义颜色">
    <van-progress :percentage="25" color="#f2826a" />
  </van-cell>
  <van-cell title="自定义文字">
    <van-progress :percentage="50" pivot-text="进行中" />
  </van-cell>
  <van-cell title="渐变色">
    <van-progress 
      :percentage="75" 
      color="linear-gradient(to right, #be99ff, #7232dd)" 
    />
  </van-cell>
  <van-cell title="隐藏文字">
    <van-progress :percentage="50" :show-pivot="false" />
  </van-cell>
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const percentage = ref(50);
    const customColor = ref('#f2826a');
    const customText = ref('进行中');
    
    // 动态改变进度和样式
    const changeStyle = () => {
      percentage.value = Math.floor(Math.random() * 100);
      const colors = ['#f2826a', '#07c160', '#1989fa', '#ff976a'];
      customColor.value = colors[Math.floor(Math.random() * colors.length)];
    };

    return {
      percentage,
      customColor,
      customText,
      changeStyle,
    };
  },
};

🎯 动态进度

展示动态变化的进度条效果，模拟真实的加载场景 🔄

<van-cell-group>
  <van-cell title="文件上传">
    <van-progress :percentage="uploadProgress" color="#07c160" />
  </van-cell>
  <van-cell title="下载进度">
    <van-progress :percentage="downloadProgress" color="#1989fa" />
  </van-cell>
  <van-button @click="startUpload" type="primary" size="small">
    开始上传
  </van-button>
  <van-button @click="startDownload" type="success" size="small">
    开始下载
  </van-button>
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const uploadProgress = ref(0);
    const downloadProgress = ref(0);
    
    // 模拟上传进度
    const startUpload = () => {
      uploadProgress.value = 0;
      const timer = setInterval(() => {
        uploadProgress.value += Math.random() * 10;
        if (uploadProgress.value >= 100) {
          uploadProgress.value = 100;
          clearInterval(timer);
        }
      }, 200);
    };
    
    // 模拟下载进度
    const startDownload = () => {
      downloadProgress.value = 0;
      const timer = setInterval(() => {
        downloadProgress.value += Math.random() * 15;
        if (downloadProgress.value >= 100) {
          downloadProgress.value = 100;
          clearInterval(timer);
        }
      }, 300);
    };

    return {
      uploadProgress,
      downloadProgress,
      startUpload,
      startDownload,
    };
  },
};

样式定制

可以使用 pivot-text 属性自定义文字，color 属性自定义进度条颜色。

📋 API

🎛️ Props

参数	说明	类型	默认值
percentage	进度百分比，控制进度条的完成度 📊	number | string	0
stroke-width	进度条粗细，默认单位为 px，调节视觉厚度 📏	number | string	4px
color	进度条颜色，支持渐变色，打造个性化外观 🎨	string	#1989fa
track-color	轨道颜色，进度条背景色，营造对比效果 🛤️	string	#e5e5e5
pivot-text	进度文字内容，自定义显示文本 📝	string	百分比
pivot-color	进度文字背景色，文字区域的背景颜色 🏷️	string	同进度条颜色
text-color	进度文字颜色，确保文字清晰可读 ✍️	string	white
inactive	是否置灰，表示禁用或暂停状态 🌫️	boolean	false
show-pivot	是否显示进度文字，控制文字显示 👁️	boolean	true

🏷️ 类型定义

组件导出以下类型定义：

import type { 
  ProgressProps, 
  ProgressInstance,
  ProgressThemeVars 
} from 'vant';

ProgressInstance 是组件实例的类型，用法如下：

import { ref } from 'vue';
import type { ProgressInstance } from 'vant';

const progressRef = ref<ProgressInstance>();

🎨 主题定制

🎭 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-progress-height	4px	进度条高度，控制进度条的视觉厚度 📏
--van-progress-color	var(--van-primary-color)	进度条颜色，主要的进度显示色彩 🎨
--van-progress-inactive-color	var(--van-gray-5)	置灰状态颜色，禁用时的显示色彩 🌫️
--van-progress-background	var(--van-gray-3)	进度条背景色，轨道的基础颜色 🛤️
--van-progress-pivot-padding	0 5px	进度文字内边距，文字区域的留白空间 📦
--van-progress-pivot-text-color	var(--van-white)	进度文字颜色，确保文字清晰可读 ✍️
--van-progress-pivot-font-size	var(--van-font-size-xs)	进度文字字号，控制文字大小 📝
--van-progress-pivot-line-height	1.6	进度文字行高，优化文字垂直对齐 📐
--van-progress-pivot-background	var(--van-primary-color)	进度文字背景色，文字区域的背景颜色 🏷️

📚 相关文档

🔗 相关组件

• Loading 加载 - 加载状态指示器，展示数据加载过程 ⏳
• Button 按钮 - 操作按钮组件，触发各种交互行为 🔘
• Toast 轻提示 - 轻量级反馈提示，不打断用户操作流程 🍞
• Dialog 弹出框 - 模态对话框，用于重要信息确认和用户决策 💬
• Circle 环形进度条 - 环形进度展示，适合空间紧凑的场景 ⭕
• Skeleton 骨架屏 - 内容加载占位符，优化加载体验 🦴
• PullRefresh 下拉刷新 - 下拉刷新功能，更新页面内容 🔄