0
# Vue Progressbar
1

2
Vue Progressbar is a lightweight progress bar component for Vue.js applications that provides comprehensive configuration options, seamless router integration, and programmatic control. It supports both Vue.js 1.x and 2.x with automatic progress indication during route transitions and rich customization capabilities.
3

4
## Package Information
5

6
- **Package Name**: vue-progressbar
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install vue-progressbar`
10

11
## Core Imports
12

13
```javascript
14
import VueProgressBar from 'vue-progressbar';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const VueProgressBar = require('vue-progressbar');
21
```
22

23
## Basic Usage
24

25
```javascript
26
import Vue from 'vue';
27
import VueProgressBar from 'vue-progressbar';
28

29
// Configure options
30
const options = {
31
  color: '#bffaf3',
32
  failedColor: '#874b4b',
33
  thickness: '5px',
34
  transition: {
35
    speed: '0.2s',
36
    opacity: '0.6s',
37
    termination: 300
38
  },
39
  autoRevert: true,
40
  location: 'top',
41
  inverse: false
42
};
43

44
// Install plugin
45
Vue.use(VueProgressBar, options);
46

47
// Use in components
48
export default {
49
  mounted() {
50
    this.$Progress.start();
51
    // Simulate work
52
    setTimeout(() => {
53
      this.$Progress.finish();
54
    }, 2000);
55
  }
56
}
57
```
58

59
## Architecture
60

61
Vue Progressbar is built around several key components:
62

63
- **Vue Plugin**: Install function that sets up the progress system globally
64
- **Progress Controller**: Core object (`$Progress`) attached to Vue prototype for programmatic control
65
- **Vue Component**: Visual progress bar component that renders based on configuration
66
- **Event Bus**: Internal Vue instance for managing progress state and options
67
- **Router Integration**: Meta parsing system for automatic progress indication during navigation
68

69
## Capabilities
70

71
### Plugin Installation
72

73
Install the Vue Progressbar plugin with optional configuration.
74

75
```javascript { .api }
76
/**
77
 * Vue plugin install function
78
 * @param Vue - Vue constructor
79
 * @param options - Configuration options object
80
 */
81
function install(Vue, options = {});
82
```
83

84
### Core Progress Control
85

86
Methods for starting, stopping, and controlling progress bar state.
87

88
```javascript { .api }
89
/**
90
 * Start progress bar animation
91
 * @param time - Duration in milliseconds (default: 3000)
92
 */
93
$Progress.start(time);
94

95
/**
96
 * Complete progress bar to 100% and hide
97
 */
98
$Progress.finish();
99

100
/**
101
 * Set progress bar to failed state and hide
102
 */
103
$Progress.fail();
104

105
/**
106
 * Pause progress bar animation
107
 */
108
$Progress.pause();
109

110
/**
111
 * Hide progress bar with transition
112
 */
113
$Progress.hide();
114
```
115

116
### Progress Manipulation
117

118
Methods for directly controlling progress percentage values.
119

120
```javascript { .api }
121
/**
122
 * Set progress to specific percentage
123
 * @param num - Percentage value (0-100)
124
 */
125
$Progress.set(num);
126

127
/**
128
 * Get current progress percentage
129
 * @returns Current percentage value
130
 */
131
$Progress.get();
132

133
/**
134
 * Increase progress by specified amount
135
 * @param num - Amount to increase
136
 */
137
$Progress.increase(num);
138

139
/**
140
 * Decrease progress by specified amount
141
 * @param num - Amount to decrease
142
 */
143
$Progress.decrease(num);
144
```
145

146
### Permanent Configuration
147

148
Methods for permanently changing progress bar appearance and behavior.
149

150
```javascript { .api }
151
/**
152
 * Set progress bar color permanently
153
 * @param color - CSS color value
154
 */
155
$Progress.setColor(color);
156

157
/**
158
 * Set fail state color permanently
159
 * @param color - CSS color value
160
 */
161
$Progress.setFailColor(color);
162

163
/**
164
 * Set progress bar location permanently
165
 * @param loc - Location ('top', 'bottom', 'left', 'right')
166
 */
167
$Progress.setLocation(loc);
168

169
/**
170
 * Set transition settings permanently
171
 * @param transition - Transition configuration object
172
 */
173
$Progress.setTransition(transition);
174
```
175

176
### Temporary Configuration
177

178
Methods for temporarily changing progress bar settings that auto-revert after completion.
179

180
```javascript { .api }
181
/**
182
 * Set progress bar color temporarily
183
 * @param color - CSS color value
184
 */
185
$Progress.tempColor(color);
186

187
/**
188
 * Set fail state color temporarily
189
 * @param color - CSS color value
190
 */
191
$Progress.tempFailColor(color);
192

193
/**
194
 * Set progress bar location temporarily
195
 * @param loc - Location ('top', 'bottom', 'left', 'right')
196
 */
197
$Progress.tempLocation(loc);
198

199
/**
200
 * Set transition settings temporarily
201
 * @param transition - Transition configuration object
202
 */
203
$Progress.tempTransition(transition);
204
```
205

206
### Configuration Reversion
207

208
Methods for reverting temporary configuration changes back to previous values.
209

210
```javascript { .api }
211
/**
212
 * Revert all temporary changes if autoRevert is enabled
213
 */
214
$Progress.revert();
215

216
/**
217
 * Revert temporary color change
218
 */
219
$Progress.revertColor();
220

221
/**
222
 * Revert temporary fail color change
223
 */
224
$Progress.revertFailColor();
225

226
/**
227
 * Revert temporary location change
228
 */
229
$Progress.revertLocation();
230

231
/**
232
 * Revert temporary transition change
233
 */
234
$Progress.revertTransition();
235
```
236

237
### Vue Router Integration
238

239
Method for parsing meta configuration from vue-router for route-specific progress settings.
240

241
```javascript { .api }
242
/**
243
 * Parse meta configuration from vue-router
244
 * @param meta - Meta configuration object with func array
245
 */
246
$Progress.parseMeta(meta);
247
```
248

249
**Vue Router Usage Example:**
250

251
```javascript
252
// In router configuration
253
export default [
254
  {
255
    path: '/dashboard',
256
    name: 'dashboard',
257
    component: Dashboard,
258
    meta: {
259
      progress: {
260
        func: [
261
          { call: 'color', modifier: 'temp', argument: '#ffb000' },
262
          { call: 'fail', modifier: 'temp', argument: '#6e0000' },
263
          { call: 'location', modifier: 'temp', argument: 'top' },
264
          { call: 'transition', modifier: 'temp', argument: { speed: '1.5s', opacity: '0.6s', termination: 400 } }
265
        ]
266
      }
267
    }
268
  }
269
];
270

271
// In App.vue
272
export default {
273
  created() {
274
    this.$router.beforeEach((to, from, next) => {
275
      if (to.meta.progress !== undefined) {
276
        this.$Progress.parseMeta(to.meta.progress);
277
      }
278
      this.$Progress.start();
279
      next();
280
    });
281
    
282
    this.$router.afterEach((to, from) => {
283
      this.$Progress.finish();
284
    });
285
  }
286
}
287
```
288

289
### Vue Component Integration
290

291
The progress bar component is automatically mounted to the document body when the plugin is installed. No manual template inclusion is required.
292

293
**Note**: The component is automatically appended to `document.body` during plugin installation.
294

295
## Configuration Options
296

297
Default configuration object with all available options:
298

299
```javascript { .api }
300
interface ProgressOptions {
301
  /** Whether progress can succeed (default: true) */
302
  canSuccess: boolean;
303
  /** Whether progress bar is visible (default: false) */
304
  show: boolean;
305
  /** Progress bar color (default: '#73ccec') */
306
  color: string;
307
  /** CSS position (default: 'fixed') */
308
  position: string;
309
  /** Failed state color (default: 'red') */
310
  failedColor: string;
311
  /** Progress bar thickness (default: '2px') */
312
  thickness: string;
313
  /** Transition configuration */
314
  transition: {
315
    /** Animation speed (default: '0.2s') */
316
    speed: string;
317
    /** Opacity transition (default: '0.6s') */
318
    opacity: string;
319
    /** Hide delay in ms (default: 300) */
320
    termination: number;
321
  };
322
  /** Auto-revert temporary changes (default: true) */
323
  autoRevert: boolean;
324
  /** Bar location - 'top', 'bottom', 'left', 'right' (default: 'top') */
325
  location: string;
326
  /** Inverse direction (default: false) */
327
  inverse: boolean;
328
  /** Auto-finish when near 95% (default: true) */
329
  autoFinish: boolean;
330
}
331
```
332

333
## Meta Configuration Format
334

335
For vue-router integration, meta objects use the following structure:
336

337
```javascript { .api }
338
interface MetaProgress {
339
  progress: {
340
    func: MetaFunction[];
341
  };
342
}
343

344
interface MetaFunction {
345
  /** Method to call: 'color', 'fail', 'location', 'transition' */
346
  call: string;
347
  /** Modifier: 'set' for permanent, 'temp' for temporary */
348
  modifier: string;
349
  /** Value to set (string for color/location, object for transition) */
350
  argument: string | object;
351
}
352
```
353

354
## External Access
355

356
In browser environments, the progress bar can be accessed externally through the global `VueProgressBarEventBus`:
357

358
```javascript { .api }
359
// Available on window object
360
window.VueProgressBarEventBus.RADON_LOADING_BAR.percent; // Current progress
361
window.VueProgressBarEventBus.RADON_LOADING_BAR.options; // Current options
362
```
363

364
**Axios Interceptor Example:**
365

366
```javascript
367
import axios from 'axios';
368
import app from '../main'; // Vue instance
369

370
const instance = axios.create({
371
  baseURL: '/api'
372
});
373

374
instance.interceptors.request.use(config => {
375
  app.$Progress.start();
376
  return config;
377
});
378

379
instance.interceptors.response.use(response => {
380
  app.$Progress.finish();
381
  return response;
382
});
383
```