Vant

日本語

繁體中文
简体中文
English

日本語

繁體中文
简体中文
English

Appearance

Uploader ファイルアップロード - Vant 4

📤 Uploader ファイルアップロード ​

🎯 概要 ​

Uploader コンポーネントは、モバイル向けのファイルアップロードソリューションを提供します。ユーザーが画像やファイルを選択し、サーバーにアップロードすることができます。このコンポーネントは、画像のプレビュー、一括アップロード、進捗状況の表示など、多くの便利な機能を提供します。 Uploader はモバイル向けに設計された強力なファイルアップロードコンポーネントです。画像やファイルのローカル選択とプレビューに対応するだけでなく、豊富なアップロード状態の表示、進捗状況の追跡、カスタムスタイル機能も提供します。単一ファイルのアップロードでも一括アップロードでも、Uploader はユーザーにスムーズなアップロード体験を提供します。

主な特徴：

  • 📸 複数フォーマットに対応した画像とファイルのアップロードをサポート
  • 🖼️ リアルタイムプレビュー機能、フルスクリーン画像ブラウジング対応
  • 📊 アップロード状態管理（アップロード中、成功、失敗）
  • 🎨 高度にカスタマイズ可能なスタイルとレイアウト
  • 🔒 完全な権限管理とファイル検証
  • 📱 モバイル最適化、写真撮影とアルバム選択に対応

注意： Uploader コンポーネントはフロントエンドのインタラクティビティに特化しており、サーバーアップロードインターフェースのロジックは含まれていません。開発者が独自にバックエンドのアップロード機能を実装する必要があります。

📦 導入 ​

以下の方法でグローバルにコンポーネントを登録できます。詳細な登録方法についてはコンポーネント登録を参照してください。

js
import { createApp } from 'vue';
import { Uploader } from 'vant';

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

🎨 代码演示 ​

📤 基本的な使い方 ​

最もシンプルなファイルアップロード方法です。ユーザーがファイルを選択すると、after-read コールバック関数がトリガーされます。このコールバック内でファイルオブジェクトを取得し、サーバーへのアップロードなどの後続処理を行うことができます。

html
<van-uploader :after-read="afterRead" />
js
import { showToast } from 'vant';

export default {
  setup() {
    const afterRead = (file) => {
      // 此時 file 對象包含了文件的詳細信息
      // 你可以在這裡自行將文件上傳至服務器
      console.log('選擇的文件:', file);
      showToast('文件選擇成功');
      
      // 示例：模擬上傳到服務器
      // uploadToServer(file);
    };

    return {
      afterRead,
    };
  },
};

🖼️ ファイルプレビュー ​

v-model を使用して既にアップロードされたファイルリストをバインドできます。コンポーネントは自動的にファイルのプレビュー画像を表示します。画像プレビューとファイルアイコンの表示をサポートし、ユーザーがアップロード済みの内容を明確に確認できるようにします。

html
<van-uploader v-model="fileList" multiple />
js
import { ref } from 'vue';

export default {
  setup() {
    const fileList = ref([
      { 
        url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg',
        name: '美丽の葉.jpg'
      },
      // Uploader は拡張子で画像かどうかを判定します
      // 画像 URL に種類情報がない場合は isImage で明示します
      { 
        url: 'https://cloud-image', 
        isImage: true,
        name: '云端画像.png'
      },
    ]);

    return {
      fileList,
    };
  },
};

📊 アップロード状態 ​

status 属性でアップロード状態を示すことができ、ユーザーはファイルのアップロード進捗をリアルタイムで把握できます。uploading（アップロード中）、failed（アップロード失敗）、done（アップロード完了）の3つの状態をサポートしています。

html
<van-uploader v-model="fileList" :after-read="afterRead" />
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const fileList = ref([
      {
        url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg',
        status: 'uploading',
        message: 'アップロード中...',
      },
      {
        url: 'https://fastly.jsdelivr.net/npm/@vant/assets/tree.jpeg',
        status: 'failed',
        message: 'アップロード失敗',
      },
    ]);

    const afterRead = (file) => {
      file.status = 'uploading';
      file.message = 'アップロード中...';
      
      // 模拟上传过程
      setTimeout(() => {
        if (Math.random() > 0.5) {
          file.status = 'done';
          file.message = 'アップロード成功';
          showToast('アップロード成功');
        } else {
          file.status = 'failed';
          file.message = 'アップロード失敗';
          showToast('アップロードに失敗しました。再試行してください');
        }
      }, 2000);
    };

    return {
      fileList,
      afterRead,
    };
  },
};

🔢 アップロード数の制限 ​

max-count 属性でアップロードファイルの数を制限できます。制限に達するとアップロードエリアが自動的に非表示になり、ユーザーがファイルを追加し続けるのを防ぎます。ユーザーのアップロード行動を制御するのに非常に役立ちます。

html
<van-uploader v-model="fileList" multiple :max-count="3" />
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const fileList = ref([]);

    const afterRead = (file) => {
      showToast(`選択したファイル数: ${fileList.value.length}`);
    };

    return {
      fileList,
      afterRead,
    };
  },
};

📏 アップロードサイズの制限 ​

max-size 属性でアップロードファイルのサイズを制限できます。サイズを超えるファイルは自動的にフィルタリングされます。ファイルが制限を超えると oversize イベントがトリガーされ、このイベント内でユーザーに分かりやすいメッセージを表示できます。

html
<van-uploader 
  v-model="fileList" 
  multiple 
  :max-size="500 * 1024" 
  @oversize="onOversize" 
/>
js
import { showToast } from 'vant';

export default {
  setup() {
    const onOversize = (file) => {
      console.log('超過サイズのファイル:', file);
      showToast('ファイルサイズは 500KB を超えることはできません');
    };

    return {
      onOversize,
    };
  },
};

高度な使い方： 異なるタイプのファイルに異なるサイズ制限を設定する必要がある場合は、max-size 属性に関数を渡し、file.type でファイルタイプを区別できます。

html
<van-uploader 
  v-model="fileList" 
  multiple 
  :max-size="isOverSize" 
  @oversize="onOversize" 
/>
js
import { showToast } from 'vant';

export default {
  setup() {
    const isOverSize = (file) => {
      // 画像ファイルは 500KB、その他は 1MB を上限
      const maxSize = file.type.startsWith('image/') ? 500 * 1024 : 1000 * 1024;
      return file.size >= maxSize;
    };

    const onOversize = (file) => {
      const limit = file.type.startsWith('image/') ? '500KB' : '1MB';
      showToast(`${file.type.startsWith('image/') ? '画像' : 'ファイル'}のサイズは ${limit} を超えないでください`);
    };

    return {
      isOverSize,
      onOversize,
    };
  },
};

🎨 アップロードスタイルのカスタマイズ ​

デフォルトスロットを使用してアップロードエリアのスタイルを完全にカスタマイズでき、アップロードインターフェースをデザイン要件に合わせることができます。

html
<van-uploader v-model="fileList">
  <van-button icon="plus" type="primary" plain>
    カスタムアップロードスタイル
  </van-button>
</van-uploader>

🖼️ プレビュースタイルのカスタマイズ ​

preview-cover スロットを使用してプレビューエリアの上に表示する内容をカスタマイズできます。例えば、編集ボタンや削除確認などのインタラクティブ要素を追加できます。

html
<van-uploader v-model="fileList">
  <template #preview-cover="{ file }">
    <div class="preview-cover van-ellipsis">
      {{ file.name }}
    </div>
  </template>
</van-uploader>

<style>
.preview-cover {
  position: absolute;
  bottom: 0;
  box-sizing: border-box;
  width: 100%;
  padding: 4px;
  color: #fff;
  font-size: 12px;
  text-align: center;
  background: rgba(0, 0, 0, 0.3);
}
</style>

📐 プレビューサイズのカスタマイズ ​

preview-size 属性でプレビュー画像とアップロードエリアのサイズを柔軟に定義でき、さまざまなインターフェースレイアウトの要件に適応できます。

html
<!-- 设置统一大小 -->
<van-uploader v-model="fileList" preview-size="60px" />

preview-size を配列に設定すると幅と高さを別々に指定でき、矩形のプレビュー領域を作成できます。

html
<!-- 设置不同的宽高 -->
<van-uploader v-model="fileList" :preview-size="[60, 40]" />

🔍 アップロード前処理 ​

beforeRead 関数を渡すことで、アップロード前に検証と処理を行うことができます。ファイル形式の検証、サイズチェック、画像圧縮などの操作をサポートします。true を返すと検証が成功したことを示し、false を返すと検証が失敗したことを示します。

html
<van-uploader 
  :before-read="beforeRead" 
  :after-read="afterRead"
/>

<!-- 异步处理示例 -->
<van-uploader 
  :before-read="asyncBeforeRead" 
  :after-read="afterRead"
/>
js
import { showToast } from 'vant';

export default {
  setup() {
    // 返回布尔值 - 同步校验
    const beforeRead = (file) => {
      if (file.type !== 'image/jpeg') {
        showToast('JPG 形式の画像をアップロードしてください');
        return false;
      }
      if (file.size > 2 * 1024 * 1024) {
        showToast('画像サイズは 2MB を超えることはできません');
        return false;
      }
      return true;
    };

    // 返回 Promise - 异步处理
    const asyncBeforeRead = (file) => 
      new Promise((resolve, reject) => {
        if (file.type !== 'image/jpeg') {
          showToast('JPG 形式の画像をアップロードしてください');
          reject();
        } else {
          // 示例：创建处理后的文件对象
          const processedFile = new File(['processed'], 'processed.jpg', {
            type: 'image/jpeg',
          });
          resolve(processedFile);
        }
      });

    const afterRead = (file) => {
      console.log('画像処理が完了しました:', file);
    };

    return {
      beforeRead,
      asyncBeforeRead,
      afterRead,
    };
  },
};

🚫 ファイルアップロードの無効化 ​

disabled 属性でファイルアップロード機能を無効にできます。フォーム送信中や権限管理の場面でよく使用されます。

html
<van-uploader v-model="fileList" disabled />

🎨 個別の画像プレビューのカスタマイズ ​

v-model 配列内で個々のプレビュー画像のプロパティを設定できます。imageFit、deletable、previewSize、beforeDelete などのプロパティをサポートし、より細かい制御が可能です。

html
<van-uploader v-model="fileList" />
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const fileList = ref([
      {
        url: 'https://fastly.jsdelivr.net/npm/@vant/assets/sand.jpeg',
        deletable: true,
        beforeDelete: () => {
          showToast('画像を削除する前に処理を行います');
          return true;
        },
      },
      {
        url: 'https://fastly.jsdelivr.net/npm/@vant/assets/tree.jpeg',
        imageFit: 'contain',
      },
    ]);

    return {
      fileList,
    };
  },
};

🔄 上書きアップロードの有効化 ​

reupload 属性を設定すると、画像をクリックすると画像のプレビューではなく上書きアップロードが行われます。アップロード済みのファイルを置き換える必要がある場面で非常に便利です。

html
<van-uploader 
  v-model="fileList" 
  reupload 
  :after-read="afterRead"
/>
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const fileList = ref([
      { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' },
    ]);

    const afterRead = (file) => {
      showToast('画像が上書きアップロードされました');
      console.log('新ファイル:', file);
    };

    return {
      fileList,
      afterRead,
    };
  },
};

📚 API ​

Props ​

パラメータ説明タイプデフォルト値
v-modelアップロード済みのファイルリストFileListItem[]-
acceptアップロードを許可するファイルタイプ、詳細な説明stringimage/*

| name | 🏷️ 識別子、通常は一意の文字列または数値、コールバック関数の2番目のパラメータで取得可能 | number | string | - | | preview-size | 📐 プレビュー画像とアップロードエリアのサイズ、デフォルトの単位は px | number | string | Array | 80px | | preview-image | 🖼️ アップロード完了後にプレビュー画像を表示するかどうか | boolean | true | | preview-full-image | 🔍 プレビュー画像をクリックした後にフルスクリーンの画像プレビューを表示するかどうか | boolean | true | | preview-options | ⚙️ フルスクリーン画像プレビューの設定オプション、利用可能な値は ImagePreview を参照 | object | - | | multiple | 📚 画像の複数選択を有効にするかどうか、一部のAndroidデバイスではサポートされていない | boolean | false | | disabled | 🚫 ファイルアップロードを無効にするかどうか | boolean | false | | readonly | 🔒 アップロードエリアを読み取り専用状態にするかどうか | boolean | false | | deletable | 🗑️ 削除ボタンを表示するかどうか | boolean | true | | reupload v4.4.0 | 🔄 上書きアップロードを有効にするかどうか、有効にすると画像プレビューが無効になる | boolean | false | | show-upload | ➕ アップロードエリアを表示するかどうか | boolean | true | | lazy-load | ⏳ 画像の遅延読み込みを有効にするかどうか、Lazyload コンポーネントと併用する必要がある | boolean | false | | capture | 📷 画像選択モード、camera (直接カメラを起動) が利用可能 | string | - | | after-read | ✅ ファイルの読み込みが完了した後のコールバック関数 | Function | - | | before-read | 🔍 ファイルの読み込み前のコールバック関数、false を返すとファイルの読み込みを中止でき、Promise の返しもサポート | Function | - | | before-delete | ⚠️ ファイルの削除前のコールバック関数、false を返すとファイルの削除を中止でき、Promise の返しもサポート | Function | - | | max-size | 📏 ファイルサイズの制限、単位は byte | number | string | (file: File) => boolean | Infinity | | max-count | 🔢 ファイルアップロード数の制限 | number | string | Infinity | | result-type | 📄 ファイル読み込み結果のタイプ、file、text、dataUrl から選択可能 | string | dataUrl | | upload-text | 💬 アップロードエリアのテキストヒント | string | - | | image-fit | 🖼️ プレビュー画像のクロップモード、利用可能な値は Image コンポーネントを参照 | string | cover | | upload-icon | 🎨 アップロードエリアのアイコン名または画像URL、Iconコンポーネントの name 属性 と同じ | string | photograph |

注意：accept、capture、multiple はブラウザの input タグのネイティブ属性です。モバイル端末の各デバイスではこれらの属性のサポートレベルに差異があるため、異なるデバイスや WebView で互換性の問題が発生する可能性があります。

イベント ​

イベント名説明コールバックパラメータ
oversize📏 ファイルサイズが制限を超えたときにトリガーafter-read と同じ
click-upload👆 アップロードエリアをクリックしたときにトリガーevent: MouseEvent
click-preview🖼️ プレビュー画像をクリックしたときにトリガーafter-read と同じ
click-reupload🔄 上書きアップロードをクリックしたときにトリガーafter-read と同じ
close-preview❌ フルスクリーン画像プレビューを閉じたときにトリガー-
delete🗑️ ファイルプレビューを削除したときにトリガーafter-read と同じ

スロット ​

名前説明パラメータ
default🎨 カスタムアップロードエリア-
preview-delete🗑️ カスタム削除ボタン-
preview-cover🖼️ プレビューエリアの上に表示するカスタムコンテンツitem: FileListItem

📋 コールバックパラメータ ​

before-read、before-delete 実行時には以下のコールバックパラメータが渡されます：

パラメータ名説明タイプ
file📁 file オブジェクトobject
detailℹ️ 追加情報、name と index フィールドを含むobject

✅ after-read コールバックパラメータ ​

after-read 実行時には以下のコールバックパラメータが渡されます：

パラメータ名説明タイプ
file📁 file オブジェクトを含むUploaderFileListItem | UploaderFileListItem[]
detailℹ️ 追加情報、name と index フィールドを含むobject

📄 ResultType の利用可能な値 ​

result-type フィールドはファイル読み取り結果のタイプを示します。大きなファイルをアップロードする場合は、フリーズを避けるために file タイプを使用することを推奨します。

値説明
file📁 結果には File オブジェクトのみが含まれる
text📝 結果には File オブジェクトとファイルのテキストコンテンツが含まれる
dataUrl🖼️ 結果には File オブジェクトとファイルに対応する base64 エンコーディングが含まれる

🔧 メソッド ​

ref を使用して Uploader インスタンスを取得し、インスタンスメソッドを呼び出すことができます。詳細についてはコンポーネントインスタンスメソッドを参照してください。

メソッド名説明パラメータ戻り値
closeImagePreview❌ フルスクリーンの画像プレビューを閉じる--
chooseFile📁 ファイル選択を明示的に呼び出す、ブラウザのセキュリティ制限により、ユーザーがトリガーした操作のコンテキスト内でのみ有効--
reuploadFile 4.9.3🔄 ファイル選択を明示的に呼び出し、新しいファイルを選択すると以前にアップロードされたファイルが上書きされる、ブラウザのセキュリティ制限により、ユーザーがトリガーした操作のコンテキスト内でのみ有効index: number-

📝 型定義 ​

コンポーネントは以下の型定義をエクスポートします：

ts
import type {
  UploaderProps,
  UploaderInstance,
  UploaderResultType,
  UploaderFileListItem,
  UploaderBeforeRead,
  UploaderAfterRead,
} from 'vant';

UploaderInstance はコンポーネントインスタンスの型です：

ts
import { ref } from 'vue';
import type { UploaderInstance } from 'vant';

const uploaderRef = ref<UploaderInstance>();
uploaderRef.value?.chooseFile();

🎨 テーマカスタマイズ ​

スタイル変数 ​

コンポーネントは次の CSS 変数を提供しており、カスタムスタイルに使用できます。使用方法については ConfigProvider コンポーネント を参照してください。

名前デフォルト値説明
--van-uploader-size80px📐 アップロードエリアのサイズ
--van-uploader-icon-size24px🎨 アップロードアイコンのサイズ
--van-uploader-icon-colorvar(--van-gray-4)🎨 アップロードアイコンの色
--van-uploader-text-colorvar(--van-text-color-2)💬 アップロードテキストの色
--van-uploader-text-font-sizevar(--van-font-size-sm)📝 アップロードテキストのサイズ
--van-uploader-upload-backgroundvar(--van-gray-1)🎨 アップロードエリアの背景色
--van-uploader-upload-active-colorvar(--van-active-color)🎨 アップロードエリアのアクティブカラー
--van-uploader-delete-colorvar(--van-white)🗑️ 削除ボタンの色
--van-uploader-delete-icon-size14px🗑️ 削除アイコンのサイズ
--van-uploader-delete-backgroundrgba(0, 0, 0, 0.7)🗑️ 削除ボタンの背景色
--van-uploader-file-backgroundvar(--van-background)📁 ファイルの背景色
--van-uploader-file-icon-size20px📁 ファイルアイコンのサイズ
--van-uploader-file-icon-colorvar(--van-gray-7)📁 ファイルアイコンの色
--van-uploader-file-name-padding0 var(--van-padding-base)📝 ファイル名のパディング
--van-uploader-file-name-margin-topvar(--van-padding-xs)📝 ファイル名の上マージン
--van-uploader-file-name-font-sizevar(--van-font-size-sm)📝 ファイル名のフォントサイズ
--van-uploader-file-name-text-colorvar(--van-gray-7)📝 ファイル名のテキストカラー
--van-uploader-mask-text-colorvar(--van-white)🎭 マスクテキストの色
--van-uploader-mask-backgroundfade(var(--van-gray-8), 88%)🎭 マスクの背景色
--van-uploader-mask-icon-size22px🎭 マスクアイコンのサイズ
--van-uploader-mask-message-font-sizevar(--van-font-size-sm)🎭 マスクメッセージのフォントサイズ
--van-uploader-mask-message-line-heightvar(--van-line-height-xs)🎭 マスクメッセージの行の高さ
--van-uploader-loading-icon-size22px⏳ ローディングアイコンのサイズ
--van-uploader-loading-icon-colorvar(--van-white)⏳ ローディングアイコンの色
--van-uploader-disabled-opacityvar(--van-disabled-opacity)🚫 無効状態の不透明度
--van-uploader-border-radius0px📐 ボーダーの角の丸み

❓ よくある質問 ​

📱 一部のAndroidデバイスでUploaderが画像をアップロードできない？ ​

Uploader は HTML ネイティブの <input type="file" /> タグを使用してアップロードを行います。アップロードが可能かどうかは現在のシステムとブラウザの互換性に依存します。アップロードができない問題が発生した場合、一般的には以下のような状況が考えられます：

  1. 🔧 AndroidアプリのWebViewの互換性の問題に直面している場合、Androidネイティブコードでの互換性対応が必要です。この記事を参照してください。
  2. 🖼️ 画像形式が正しくないため、現在のシステム/ブラウザで認識できない場合（例：webp や heic 形式）。
  3. 🌐 その他のブラウザ互換性の問題。

🔄 撮影してアップロードした画像が90度回転する？ ​

一部のスマートフォンでは、写真を撮ってアップロードすると画像が90度回転する問題が発生します。この問題は compressorjs やその他のオープンソースライブラリを使用して処理できます。

compressorjs はオープンソースの画像処理ライブラリであり、画像の圧縮、回転などの機能を提供します。

💡 例 ​

compressorjs を使用して処理するサンプルコードは次のとおりです:

html
<van-uploader :before-read="beforeRead" />
js
import Compressor from 'compressorjs';

export default {
  setup() {
    const beforeRead = (file) =>
      new Promise((resolve) => {
        // compressorjs 默认开启 checkOrientation 选项
        // 会将图片修正为正确方向
        new Compressor(file, {
          success: resolve,
          error(err) {
            console.log(err.message);
          },
        });
      });

    return {
      beforeRead,
    };
  },
};

💻 画像をアップロードするとブラウザが更新またはフリーズする現象が発生する？ ​

この現象は一般的にメモリ不足が原因で、古いデバイスでよく発生します。大きな画像をアップロードするときにもこの現象が発生することがあります。

このような状況の発生を減らすために、画像をアップロードする前に画像を圧縮することができます。圧縮方法については、上記で説明した compressorjs ライブラリを参照してください。

🖼️ HEIC/HEIF 形式の画像をアップロードした後、表示できない？ ​

現在、Chrome、Safari などのブラウザは HEIC/HEIF 形式の画像の表示をサポートしていないため、アップロード後に Uploader コンポーネントでプレビューすることができません。

[HEIF] 形式の互換性については caniuse を参照してください。

📷 ユーザーがカメラのアクセス権限を与えているかどうかを確認する方法は？ ​

画像をアップロードする際、ユーザーが現在のアプリにカメラのアクセス権限を与えていないと、Uploader コンポーネントが使用できなくなります。

ブラウザが提供する getUserMedia メソッドを使用して、カメラのアクセス権限が与えられているかどうかを判断できます（getUserMedia メソッドは iOS 10 では使用できないことに注意してください）。

以下是一个简化的示例：

ts
navigator.mediaDevices
  .getUserMedia({ video: true })
  .then((stream) => {
    console.log('摄像头权限已授予:', stream);
  })
  .catch((err) => {
    console.log('摄像头权限被拒绝:', err);
  });

📖 関連ドキュメント ​

📁 ファイル処理コンポーネント ​

📝 フォームコンポーネント ​

💬 フィードバックコンポーネント ​

🔧 ユーティリティコンポーネント ​

Vant に基づく企業向けモバイルソリューション

Copyright © 2025 siex.cn ｜ sitemap