Element-UI
数据展示组件

进度条（Progress）

# 进度条（Progress）

Element-UI 的进度条组件用于展示操作的进度，告知用户当前状态和预期完成的进度。进度条可以以线形、环形或仪表盘的形式显示，并且支持自定义颜色、大小、文本位置等属性。

提示

进度条（Progress）组件官方文档：https://element.eleme.cn/#/zh-CN/component/progress (opens new window)

# 1. 基本用法

基本语法：在 Vue 组件中使用 <el-progress> 标签创建一个进度条。通过 percentage 属性设置进度百分比，这是一个必填属性。type 属性用于选择进度条的展示类型，如线形、环形或仪表盘。

<template>
  <div>
    <el-progress :percentage="50"></el-progress>
    <el-progress type="circle" :percentage="75"></el-progress>
    <el-progress type="dashboard" :percentage="90"></el-progress>
  </div>
</template>

<script>
export default {
  data() {
    return {
      // 示例中的进度值可以根据实际需求进行动态调整
    };
  }
};
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

percentage：进度条的百分比，取值范围为 0-100。这是必填属性，显示进度的数值。
type：通过 type 属性选择进度条的展示类型，默认值为 line，还可以选择 circle 或 dashboard。

# Progress 属性

Progress 组件提供了多种属性，用于灵活调整进度条的外观和行为。

参数	说明	类型	可选值	默认值
`percentage`	进度条的百分比（必填）	`number`	0-100	0
`type`	进度条的类型	`string`	`line` / `circle` / `dashboard`	`line`
`stroke-width`	进度条的宽度，单位 `px`	`number`	—	6
`text-inside`	进度条显示文字是否内置在进度条内（仅在 `type="line"` 时可用）	`boolean`	—	false
`status`	进度条当前状态	`string`	`success` / `exception` / `warning`	—
`color`	进度条背景色（会覆盖 `status` 状态颜色）	`string` / `function` / `array`	—	—
`width`	环形进度条画布宽度（仅在 `type="circle"` 或 `dashboard"` 时可用）	`number`	—	126
`show-text`	是否显示进度条文字内容	`boolean`	—	true
`stroke-linecap`	`circle` / `dashboard` 类型路径两端的形状	`string`	`butt` / `round` / `square`	`round`
`format`	自定义进度条文字内容	`function(percentage)`	—	—
`define-back-color`	自定义进度条底色（支持 `hex` 格式）	`string`	—	—
`text-color`	自定义进度条字体颜色（支持 `hex` 格式）	`string`	—	—

# 2. 常用进度条

# 线形进度条

关键点：线形进度条是最基础的展示形式，通过 percentage 属性控制进度显示，必填，必须在 0-100。通过 format 属性来指定进度条文字内容。通过 status 属性设置进度条的状态，

<el-progress :percentage="50"></el-progress>
<el-progress :percentage="100" :format="format"></el-progress>
<el-progress :percentage="100" status="success"></el-progress>
<el-progress :percentage="100" status="warning"></el-progress>
<el-progress :percentage="50" status="exception"></el-progress>

<script>
  export default {
    methods: {
      format(percentage) {
        return percentage === 100 ? '满' : `${percentage}%`;
      }
    }
  };
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

线形进度条：这是默认的进度条样式，适合展示线性任务的完成进度。
百分比控制：通过 percentage 属性直接控制进度条的百分比显示。

# 环形进度条

关键点：环形进度条适用于展示百分比进度，通过 type="circle" 属性进行设置，可以更直观地展示任务的完成程度。

<el-progress type="circle" :percentage="0"></el-progress>
<el-progress type="circle" :percentage="25"></el-progress>
<el-progress type="circle" :percentage="100" status="success"></el-progress>
<el-progress type="circle" :percentage="70" status="warning"></el-progress>
<el-progress type="circle" :percentage="50" status="exception"></el-progress>

1
2
3
4
5

环形进度条：type="circle" 用于创建环形进度条，适合需要占用较小空间但仍要突出显示进度的场景。
直观显示：环形设计使用户可以轻松理解进度，适合用于概览或仪表盘中。

# 仪表盘进度条

关键点：仪表盘进度条采用类似速度计的显示方式，通过 type="dashboard" 来设置，适合用于显示状态或关键指标的场景。

<el-progress type="dashboard" :percentage="percentage" :color="colors"></el-progress>
<div>
  <el-button-group>
    <el-button icon="el-icon-minus" @click="decrease"></el-button>
    <el-button icon="el-icon-plus" @click="increase"></el-button>
  </el-button-group>
</div>

<script>
  export default {
    data() {
      return {
        percentage: 10,
        colors: [
          {color: '#f56c6c', percentage: 20},
          {color: '#e6a23c', percentage: 40},
          {color: '#5cb87a', percentage: 60},
          {color: '#1989fa', percentage: 80},
          {color: '#6f7ad3', percentage: 100}
        ]
      };
    },
    methods: {
      increase() {
        this.percentage += 10;
        if (this.percentage > 100) {
          this.percentage = 100;
        }
      },
      decrease() {
        this.percentage -= 10;
        if (this.percentage < 0) {
          this.percentage = 0;
        }
      }
    }
  }
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

仪表盘进度条：type="dashboard" 创建了仪表盘样式的进度条，提供了一种更具视觉冲击力的进度显示方式。
状态指示：适合用作状态指示器或关键性能指标的展示。

# 自定义颜色进度条

关键点：通过 color 属性可以设置进度条的颜色，支持单一颜色、渐变色或通过函数动态生成颜色。

<el-progress :percentage="percentage" :color="customColor"></el-progress>

<el-progress :percentage="percentage" :color="customColorMethod"></el-progress>

<el-progress :percentage="percentage" :color="customColors"></el-progress>
<div>
  <el-button-group>
    <el-button icon="el-icon-minus" @click="decrease"></el-button>
    <el-button icon="el-icon-plus" @click="increase"></el-button>
  </el-button-group>
</div>

<script>
  export default {
    data() {
      return {
        percentage: 20,
        customColor: '#409eff',
        customColors: [
          {color: '#f56c6c', percentage: 20},
          {color: '#e6a23c', percentage: 40},
          {color: '#5cb87a', percentage: 60},
          {color: '#1989fa', percentage: 80},
          {color: '#6f7ad3', percentage: 100}
        ]
      };
    },
    methods: {
      customColorMethod(percentage) {
        if (percentage < 30) {
          return '#909399';
        } else if (percentage < 70) {
          return '#e6a23c';
        } else {
          return '#67c23a';
        }
      },
      increase() {
        this.percentage += 10;
        if (this.percentage > 100) {
          this.percentage = 100;
        }
      },
      decrease() {
        this.percentage -= 10;
        if (this.percentage < 0) {
          this.percentage = 0;
        }
      }
    }
  }
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

自定义颜色：color 属性允许设置自定义背景色，支持多种颜色格式，如 hex、rgb 和渐变色。
视觉优化：通过颜色设置来增强进度条的视觉效果，使其更具吸引力。

# 带文字内置的进度条

关键点：在 type="line" 的进度条中，text-inside 属性可以将显示的百分比文字内置到进度条内部。
可以通过 stroke-width 属性更改进度条的高度，并可通过 text-inside 属性来将进度条描述置于进度条内部。

<el-progress :text-inside="true" :stroke-width="26" :percentage="70"></el-progress>
<el-progress :text-inside="true" :stroke-width="24" :percentage="100" status="success"></el-progress>
<el-progress :text-inside="true" :stroke-width="22" :percentage="80" status="warning"></el-progress>
<el-progress :text-inside="true" :stroke-width="20" :percentage="50" status="exception"></el-progress>

1
2
3
4

文字内置：text-inside 属性允许进度条的文字内置，这样的设计更节省空间并且能更好地展示进度信息。
增强可读性：在狭小空间中展示进度的同时，还能清晰显示百分比信息。

# 不同状态的进度条

关键点：通过 status 属性可以设置进度条的状态，如 success、exception、warning，以不同的颜色和样式展示当前进度的状态。

<template>
  <el-progress :percentage="100" status="success"></el-progress>
  <el-progress :percentage="50" status="exception"></el-progress>
  <el-progress :percentage="70" status="warning"></el-progress>
</template>

<script>
export default {
  data() {
    return {
      percentage: 100
    };
  }
};
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

状态反馈：通过 status 属性设置进度条的不同状态，success 显示为绿色，exception 为红色，warning 为黄色。
直观显示：通过状态颜色的变化让用户直观感知当前进度的状态，适合用来展示任务的成功、失败或警告状态。

# 3. 如何制作一个进度条

# 1. 选择合适的进度条类型

Element UI 提供了三种类型的进度条：线形、圆形、仪表盘。选择进度条的类型取决于你要展示的数据和视觉效果。

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

上面这个示例就是最基本的线形进度条，显示进度为 50%。

# 2. 配置进度条属性

进度条有多个可配置的属性，如 percentage、type、stroke-width、status 等等。

percentage：表示当前进度的百分比（必填）。
type：进度条类型，如 line（线形），circle（圆形），dashboard（仪表盘）。
stroke-width：设置进度条的宽度，以像素为单位。
status：设置进度条的状态，如 success、exception、warning。

例如：

<el-progress :percentage="75" type="circle" :stroke-width="10" status="success"></el-progress>

# 3. 添加进度条的文本说明

如果需要在进度条上显示额外的信息，可以使用 format 属性进行自定义。例如显示百分比和描述文字：

<el-progress :percentage="70" :format="formatText"></el-progress>

export default {
  methods: {
    formatText(percentage) {
      return `完成度：${percentage}%`;
    }
  }
};

1
2
3
4
5
6
7

# 4. 控制进度条的动态变化 (重点)

在实际开发中，控制进度条的动态变化，特别是在处理长时间的请求（如文件上传、数据处理等）时，是一个比较常见的需求。通常，有几种不同的策略可以控制进度条的动态变化，这取决于具体的应用场景和需求。

# 通过响应数据的 `Content-Length` 头部来计算进度

对于文件上传、下载等操作，如果后端支持，可以通过 HTTP 的 Content-Length 头部来获取总数据量，并通过监听 progress 事件实时更新进度条。这是最准确的进度控制方法。

文件上传的例子：

startUpload() {
  const formData = new FormData();
  formData.append('file', this.selectedFile);

  axios.post('/upload', formData, {
    onUploadProgress: progressEvent => {
      // progressEvent.loaded 是已上传的数据量，progressEvent.total 是总数据量
      this.uploadPercentage = Math.round((progressEvent.loaded * 100) / progressEvent.total);
    }
  }).then(response => {
    this.$message.success('上传完成');
  }).catch(error => {
    this.$message.error('上传失败');
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

在这个例子中，onUploadProgress 回调函数会在上传过程中多次被调用，通过 progressEvent.loaded 和 progressEvent.total 计算当前的上传进度，并动态更新进度条的 percentage。

# 通过分段加载或分批处理来计算进度

如果后端能够提供一个分段处理的接口，例如分页获取数据或者分段处理大文件，你可以在每次请求完成后更新进度条的状态。

例如，分页获取数据时：

methods: {
  fetchData() {
    const totalSteps = 5; // 假设总共有5个分页需要请求
    let currentStep = 0;

    const fetchPage = (page) => {
      axios.get(`/api/data?page=${page}`).then(response => {
        // 处理数据
        currentStep++;
        this.uploadPercentage = Math.round((currentStep * 100) / totalSteps);

        if (currentStep < totalSteps) {
          fetchPage(page + 1); // 获取下一页
        } else {
          this.$message.success('数据加载完成');
        }
      }).catch(error => {
        this.$message.error('数据加载失败');
      });
    };

    fetchPage(1); // 从第一页开始获取
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 通过后端反馈状态进行更新

有时后端会在处理过程中返回进度信息，前端可以根据这些信息动态更新进度条。例如，后端返回一个任务处理的百分比，前端通过轮询或 WebSocket 等方式获取最新的进度。

methods: {
  startProcess() {
    axios.post('/start-process').then(response => {
      this.pollProgress(response.data.taskId); // 开始轮询任务进度
    });
  },
  pollProgress(taskId) {
    const interval = setInterval(() => {
      axios.get(`/task-status?taskId=${taskId}`).then(response => {
        this.uploadPercentage = response.data.progress;

        if (response.data.progress >= 100) {
          clearInterval(interval);
          this.$message.success('任务完成');
        }
      }).catch(error => {
        clearInterval(interval);
        this.$message.error('任务失败');
      });
    }, 1000); // 每隔一秒轮询一次
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 假进度条与实际进度结合

在某些情况下，为了避免进度条长时间停留在某个位置而给用户带来不好的体验，可以使用一个假进度条：在前期快速增长，然后在后期配合实际进度。

startUpload() {
  let fakeProgress = 0;
  const interval = setInterval(() => {
    if (fakeProgress < 70) {
      fakeProgress += 5; // 假进度前70%快速增长
      this.uploadPercentage = fakeProgress;
    } else {
      clearInterval(interval); // 假进度停止，开始等待实际进度
    }
  }, 200);

  axios.post('/upload', this.formData, {
    onUploadProgress: progressEvent => {
      const realProgress = Math.round((progressEvent.loaded * 100) / progressEvent.total);
      this.uploadPercentage = Math.max(fakeProgress, realProgress); // 取假进度和真实进度的最大值
    }
  }).then(() => {
    this.uploadPercentage = 100;
    this.$message.success('上传完成');
  }).catch(() => {
    this.$message.error('上传失败');
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

总结

精确控制：使用 onUploadProgress 或 progress 事件，可以精准地控制进度条的变化，这种方法适用于文件上传、下载等操作。
分段控制：通过分段请求或分段处理，每次操作完成后更新进度条，适用于数据获取或大文件处理。
后台反馈：轮询或 WebSocket 等方法，依赖后端提供的实时进度反馈，适用于长时间的任务处理。
假进度结合实际进度：在实际进度较慢的场景中，可以结合一个假进度条，提升用户体验。

实际开发中，具体选择哪种方式取决于后端接口的设计以及用户体验的要求。

# 5. 设置进度条的颜色

你可以通过 color 属性为进度条设置不同的颜色，以符合项目的品牌色或视觉要求。

<el-progress :percentage="45" color="#409EFF"></el-progress>

你还可以使用函数或数组来设置渐变色：

<el-progress :percentage="50" :color="progressColor"></el-progress>

export default {
  methods: {
    progressColor(percentage) {
      if (percentage < 30) {
        return '#909399';
      } else if (percentage < 70) {
        return '#e6a23c';
      } else {
        return '#67c23a';
      }
    }
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
13

# 6. 模拟上传示例

<template>
  <div>
    <!-- 线形进度条 -->
    <el-progress :percentage="uploadProgress" :stroke-width="10" color="#67c23a"></el-progress>

    <!-- 圆形进度条 -->
    <el-progress type="circle" :percentage="uploadProgress" :width="120" color="#e6a23c"></el-progress>

    <!-- 仪表盘进度条 -->
    <el-progress type="dashboard" :percentage="uploadProgress" :width="120" color="#f56c6c"></el-progress>

    <!-- 控制按钮 -->
    <el-button @click="simulateUpload">模拟上传</el-button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      uploadProgress: 0
    };
  },
  methods: {
    simulateUpload() {
      this.uploadProgress = 0;
      const interval = setInterval(() => {
        if (this.uploadProgress < 100) {
          this.uploadProgress += 10;
        } else {
          clearInterval(interval);
          this.$message.success('上传完成');
        }
      }, 500);
    }
  }
};
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

动态更新：通过 setInterval 动态更新 percentage，模拟上传的过程。此方法常用于文件上传进度、数据加载进度等。
颜色控制：color 属性允许你为进度条定义颜色，这在视觉设计和品牌一致性方面非常重要。
文本定制：通过 format 方法，你可以展示不同的进度文本，这对于用户理解操作状态非常有帮助。

# 4. NProgress (页面加载进度条)

为了在每次进入路由跳转或者刷新页面时，在页面顶部显示一个加载进度条，可以使用第三方库 NProgress (opens new window) 实现。这种进度条能给用户提供一个视觉反馈，表示页面正在加载。

# 1. 安装 NProgress

首先，你需要在项目中安装 NProgress 这个库：

npm install nprogress --save

# 2. main.js中引入 NProgress

在项目的主入口文件（ main.js 或 index.js）中引入 NProgress 以及其默认的 CSS 样式：

import NProgress from 'nprogress';
import 'nprogress/nprogress.css';

1
2

进度条逻辑：NProgress 是一个轻量级的 JavaScript 库，专门用来显示页面加载进度条。它可以在路由导航开始时启动进度条，在导航结束时停止进度条。
样式控制：nprogress.css 提供了默认的样式，你也可以根据需要自定义这些样式。

# 3. 配置 NProgress

NProgress 提供了几种配置选项，你可以根据项目需求进行调整：

NProgress.configure({ showSpinner: false, speed: 500 });

showSpinner: false 表示不显示加载时的微调器（spinner）。
speed: 设置进度条的速度（单位是毫秒）。500 表示进度条的动画速度为 500 毫秒。

配置是否必须？

可选配置：如果你对默认行为和样式满意，那么配置步骤是可选的。配置仅在你需要更改默认行为时使用。
常见配置：大多数情况下，我们会关闭微调器（showSpinner: false），因为它可能不符合所有项目的设计需求。

# 4. 在路由中使用 NProgress

为了在每次路由跳转或刷新页面时显示进度条，你需要在 Vue Router 的导航守卫中启动和停止 NProgress：

import Vue from 'vue';
import Router from 'vue-router';
import NProgress from 'nprogress';

Vue.use(Router);

const router = new Router({
  // 你的路由配置
});

router.beforeEach((to, from, next) => {
  NProgress.start(); // 开始进度条
  next();
});

router.afterEach(() => {
  NProgress.done(); // 结束进度条
});

export default router;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

beforeEach 钩子：在路由开始切换时，调用 NProgress.start() 启动进度条。
afterEach 钩子：在路由完成切换后，调用 NProgress.done() 停止进度条。

# 5. 自定义样式（可选）

NProgress 自带的样式是简单的蓝色进度条，你可以通过自定义 CSS 来改变进度条的颜色或样式：

/* nprogress-custom.css */

/* 修改进度条颜色 */
#nprogress .bar {
  background: #29d; /* 你想要的颜色 */
}

/* 修改进度条高度 */
#nprogress .bar {
  height: 3px;
}

/* 修改微调器颜色 */
#nprogress .spinner-icon {
  border-top-color: #29d;
  border-left-color: #29d;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

自定义样式的使用：

创建一个自定义样式文件：如上所示，可以创建一个 nprogress-custom.css 文件，来放置所有自定义样式。
在项目中引入：在 main.js 中引入自定义样式文件：

import 'path/to/nprogress-custom.css';

# 6. 处理错误和延迟

在实际使用中，可能需要处理一些特殊情况，比如路由切换失败，或者页面加载过快导致进度条瞬间消失。可以在路由导航守卫中处理这些情况：

router.beforeEach((to, from, next) => {
  NProgress.start();

  if (to.name) {
    next();
  } else {
    NProgress.done(); // 停止进度条
    next('/404'); // 跳转到 404 页面
  }
});

router.afterEach(() => {
  NProgress.done(); // 结束进度条
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 7. 完整配置实例

// main.js
import Vue from 'vue';
import App from './App.vue';
import router from './router';
import NProgress from 'nprogress';
import 'nprogress/nprogress.css'; // 默认样式
import './assets/nprogress-custom.css'; // 自定义样式

NProgress.configure({ showSpinner: false, speed: 500 });

Vue.config.productionTip = false;

new Vue({
  router,
  render: h => h(App)
}).$mount('#app');

// router/index.js
import Vue from 'vue';
import Router from 'vue-router';
import Home from '@/views/Home.vue';
import About from '@/views/About.vue';
import NProgress from 'nprogress';

Vue.use(Router);

const router = new Router({
  routes: [
    { path: '/', name: 'Home', component: Home },
    { path: '/about', name: 'About', component: About }
  ]
});

router.beforeEach((to, from, next) => {
  NProgress.start();
  next();
});

router.afterEach(() => {
  NProgress.done();
});

export default router;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

总结

NProgress 的灵活性：NProgress 提供了基础的进度条控制，你可以通过配置、样式自定义和钩子函数实现更复杂的需求。
配置的必要性：根据项目需求，你可以选择是否对 NProgress 进行配置，通常关闭 spinner 是一个常见的选择。
样式自定义：将自定义样式放在单独的 CSS 文件中，确保样式管理的清晰和可维护性。

编辑此页

上次更新: 2024/12/28, 18:32:08

← Tag (标签) 树形控件（Tree）→

进度条（Progress）

# 进度条（Progress）

# 1. 基本用法

# Progress 属性

# 2. 常用进度条

# 线形进度条

# 环形进度条

# 仪表盘进度条

# 自定义颜色进度条

# 带文字内置的进度条

# 不同状态的进度条

# 3. 如何制作一个进度条

# 1. 选择合适的进度条类型

# 2. 配置进度条属性

# 3. 添加进度条的文本说明

# 4. 控制进度条的动态变化 (重点)

# 通过响应数据的 Content-Length 头部来计算进度

# 通过分段加载或分批处理来计算进度

# 通过后端反馈状态进行更新

# 假进度条与实际进度结合

# 5. 设置进度条的颜色

# 6. 模拟上传示例

# 4. NProgress (页面加载进度条)

# 1. 安装 NProgress

# 2. main.js中引入 NProgress

# 3. 配置 NProgress

# 4. 在路由中使用 NProgress

# 5. 自定义样式（可选）

# 6. 处理错误和延迟

# 7. 完整配置实例

# 通过响应数据的 `Content-Length` 头部来计算进度