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 プルリフレッシュ - 画面更新 🔄