フォームファイル

<template>
  <div>
    <!-- Styled -->
    <b-form-file
      v-model="file1"
      :state="Boolean(file1)"
      placeholder="Choose a file or drop it here..."
      drop-placeholder="Drop file here..."
    ></b-form-file>
    <div class="mt-3">Selected file: {{ file1 ? file1.name : '' }}</div>

    <!-- Plain mode -->
    <b-form-file v-model="file2" class="mt-3" plain></b-form-file>
    <div class="mt-3">Selected file: {{ file2 ? file2.name : '' }}</div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        file1: null,
        file2: null
      }
    }
  }
</script>

<!-- b-form-file.vue -->

クロスブラウザの一貫性を保つため、<b-form-file> はデフォルトで、ブラウザのデフォルトのファイル入力をBootstrapカスタムファイル入力に置き換えます。これらは、セマンティックでアクセシブルなマークアップ上に構築されているため、デフォルトのファイル入力の確実な代替手段となります。

単一ファイル（デフォルト）

単一ファイルモードでは、ファイルが選択されていない場合、またはユーザーが「参照」ダイアログをキャンセルした場合、v-model は null になり、ファイルが選択されていないことを示します。ファイルが選択されると、戻り値は JavaScript の File オブジェクトインスタンスになります。

複数ファイル

複数ファイルのアップロードは、コンポーネントに multiple プロパティを追加することでサポートされます。この場合、v-model は常に配列です。ファイルが選択されていない場合は、空の配列が返されます。1つ以上のファイルが選択されると、戻り値は JavaScript の File オブジェクトインスタンスの配列になります。

ディレクトリモード

directory プロパティを追加することにより、ユーザーはファイルの代わりにディレクトリを選択できます。ディレクトリが選択されると、ディレクトリとそのコンテンツの階層全体が、選択された項目のセットに含まれます。

ディレクトリモードでは、ファイルはデフォルトでネストされた配列形式で返されます。例：

dirA/
  - fileA1
  - fileA2
  - dirB/
    - fileB1
  - dirC/
    - fileC1
    - fileC2
dirD/
  - fileD1

は、次のように返されます（または、ファイル/ディレクトリの順序が異なる場合があります）。

[[fileA1, fileA2, [fileB1], [fileC1, fileC2]], [fileD1]]

no-traverse プロパティを設定すると、配列はフラット化されます

[fileA1, fileA2, fileB1, fileC1, fileC2, fileD1]

各ファイルエントリには、各ファイルの相対パスを含む特別な $path プロパティがあります。ネストされたディレクトリ構造の場合、BootstrapVueは独自のルーチンを使用して相対パスを決定します。そうでない場合は、File.webkitRelativePathに依存します。

ディレクトリモードは、ファイル入力が**ほとんどの**最新のブラウザでプレーンモードの場合にもサポートされます。

ドラッグアンドドロップのサポート

ドロップモードはデフォルトで有効になっています。 no-drop プロパティを設定することで無効にすることができます。 no-drop は、プレーンモードでは効果がありません（一部のブラウザは、プレーン入力ファイルへのファイルのドロップをサポートしています）。

オプションで、drop-placeholder プロパティまたはスコープ付き drop-placeholder スロットを介してドラッグ中に別のプレースホルダーを設定できます。プロパティはプレーンテキストのみをサポートします。カスタムHTMLマークアップにはスロットを使用してください。スロットはプロパティよりも優先されます。 drop-placeholder プロパティ/スロットは、no-drop が設定されている場合、またはプレーンモードの場合は効果がありません。

ネイティブブラウザの制約（ required など）は、非表示のファイル入力がドラッグアンドドロップ機能を処理せず、選択されたファイルがゼロになるため、ドロップモードでは機能しないことに注意してください。

特定のファイルタイプへの制限

許可されるファイルタイプを含む文字列に accept プロパティを設定することで、ファイルタイプを制限できます。複数のタイプを指定するには、値をコンマで区切ります。

<div>
  <!-- Accept all image formats by IANA media type wildcard-->
  <b-form-file accept="image/*"></b-form-file>

  <!-- Accept specific image formats by IANA type -->
  <b-form-file accept="image/jpeg, image/png, image/gif"></b-form-file>

  <!-- Accept specific image formats by extension -->
  <b-form-file accept=".jpg, .png, .gif"></b-form-file>
</div>

すべてのファイルタイプを受け入れるには、 accept を null （デフォルト）のままにします。IANAメディアタイプと拡張子を混在させて使用できます。

標準メディアタイプの完全なリストについては、IANAメディアタイプを参照してください。

**注意：**すべてのブラウザがファイル入力の accept 属性をサポートまたは尊重しているわけではありません。

ドラッグアンドドロップの場合、BootstrapVueは内部ファイルタイプチェックルーチンを使用し、正しいIANAメディアタイプまたは拡張子を持たないファイルをフィルタリングします。

カスタマイズ

<b-form-file> は、プレーンモードでない場合、その外観をカスタマイズするためのいくつかの機能を提供します。

コントロールのサイズ変更

size プロパティを使用して、入力の視覚的なサイズを制御します。デフォルトサイズは md （中）と見なされます。オプションのサイズは lg （大）と sm （小）です。これらのサイズは、他のフォームコントロールで使用可能なサイズと一致します。

<div>
  <b-form-group label="Small:" label-cols-sm="2" label-size="sm">
    <b-form-file id="file-small" size="sm"></b-form-file>
  </b-form-group>

  <b-form-group label="Default:" label-cols-sm="2">
    <b-form-file id="file-default"></b-form-file>
  </b-form-group>

  <b-form-group label="Large:" label-cols-sm="2" label-size="lg">
    <b-form-file id="file-large" size="lg"></b-form-file>
  </b-form-group>
</div>

<!-- form-file-sizes.vue -->

**注意：** Bootstrap v4.xは、カスタムファイルコントロールのサイズをネイティブでサポートしていません。ただし、BootstrapVueには、カスタムファイル入力コントロールのサイズ変更をサポートするカスタムSCSS / CSSが含まれています。

プレースホルダーテキストのカスタマイズ

placeholder プロパティまたはスコープ付き placeholder スロットを使用して、ファイルが選択されていない場合に表示されるプロンプトテキストを変更します。プロパティはプレーンテキストのみをサポートします.カスタムHTMLマークアップにはスロットを使用してください。スロットはプロパティよりも優先されます。

参照ボタンラベルのカスタマイズ

「参照」ラベルをグローバルに変更する場合は、グローバルスタイルシートに次のようなものを追加できます。また、多言語サイトの場合は :lang() を使用することをお勧めします。

.custom-file-input:lang(en) ~ .custom-file-label::after {
  content: 'Browse';
}

または、 browse-text プロパティを介してカスタムファイルの参照ボタンテキストのコンテンツを設定することもできます。プレーンテキストのみがサポートされていることに注意してください。HTMLとコンポーネントはサポートされていません。

ファイル名フォーマッター関数

プロパティ file-name-formatter を、3つの引数を受け入れる関数に設定します

関数は、単一のフォーマット済み文字列を返す必要があります（HTMLはサポートされていません）。ファイルが選択されていない場合、フォーマッターは呼び出されません。

<template>
  <b-form-file multiple :file-name-formatter="formatNames"></b-form-file>
</template>

<script>
  export default {
    methods: {
      formatNames(files) {
        return files.length === 1 ? files[0].name : `${files.length} files selected`
      }
    }
  }
</script>

<!-- file-formatter-function.vue -->

スコープ付きスロットによるファイル名のフォーマット

または、スコープ付きスロット file-name を使用してファイル名を表示することもできます。スコープ付きスロットは、次のプロパティを受け取ります

multiple プロパティの設定に関係なく、3つのプロパティはすべて常に配列です。

<template>
  <b-form-file multiple>
   <template slot="file-name" slot-scope="{ names }">
     <b-badge variant="dark">{{ names[0] }}</b-badge>
     <b-badge v-if="names.length > 1" variant="dark" class="ml-1">
       + {{ names.length - 1 }} More files
     </b-badge>
   </template>
  </b-form-file>
</template>

<!-- file-formatter-slot.vue -->

file-name スロットを使用する場合、 file-name-formatter プロパティは無視されます。ファイルが選択されていない場合、スロットはレンダリングされません。

カスタム以外のファイル入力

plain プロパティを設定することにより、<b-form-file> にブラウザネイティブのファイル入力をレンダリングさせることができます。 plain が設定されている場合、多くのカスタム機能が適用されないことに注意してください。

コンテキスト状態フィードバック

Bootstrapには、ほとんどのフォームコントロールで valid および invalid 状態の検証スタイルが含まれています。

一般的に、特定の種類のフィードバックに特定の状態を使用することをお勧めします

• false （無効な状態を示す）は、ブロッキングまたは必須フィールドがある場合に最適です。ユーザーはフォームを送信するためにこのフィールドに正しく入力する必要があります
• true （有効な状態を示す）は、フォーム全体でフィールドごとの検証を行い、ユーザーが残りのフィールドに入力することを促したい場合に最適です
• null は、検証状態を表示しません（有効でも無効でもありません）

<b-form-file> にコンテキスト状態アイコンのいずれかを適用するには、 state プロパティを false （無効の場合）、 true （有効の場合）、または null （検証状態なし）に設定します。

**注意：**コンテキスト状態は、プレーンモードではサポートされていません。

自動フォーカス

<b-form-file> に autofocus プロパティが設定されている場合、入力はドキュメントに挿入（つまり、**マウント**）されたとき、または Vue の <keep-alive> コンポーネント内で再アクティブ化されたときに自動的にフォーカスされます。 このプロパティは入力に autofocus 属性を設定するわけではなく、入力が表示可能になったときを認識することもできないことに注意してください。

アクセシビリティ

元の入力を非表示にするカスタムバージョンの <b-form-file> 入力を使用する場合は、id プロパティを介してドキュメント内で一意の ID 文字列を提供することを**強くお勧めします**。 これにより、支援技術を使用するユーザーの使いやすさを向上させるために必要な追加の ARIA 属性が自動的にレンダリングされます。

ファイル選択のクリア

ファイルタイプの入力では、通常、v-model は単方向です（つまり、選択されたファイルを事前に設定することはできません）。 ただし、v-model を null（単一モードの場合）または空の配列 []（multiple/directory モードの場合）に設定することで、ファイル入力の選択されたファイルをクリアできます。

あるいは、<b-form-file> は、ファイル入力をクリアするために呼び出すことができる reset() メソッドを提供します。 reset() メソッドを利用するには、<b-form-file> コンポーネントへの参照を取得する必要があります。

<template>
  <div>
    <b-form-file v-model="file" ref="file-input" class="mb-2"></b-form-file>

    <b-button @click="clearFiles" class="mr-2">Reset via method</b-button>
    <b-button @click="file = null">Reset via v-model</b-button>

    <p class="mt-2">Selected file: <b>{{ file ? file.name : '' }}</b></p>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        file: null
      }
    },
    methods: {
      clearFiles() {
        this.$refs['file-input'].reset()
      }
    }
  }
</script>

<!-- b-form-file-reset.vue -->

実装に関する注意事項

すべてのブラウザがファイル入力の値の設定（null または空の文字列でさえも）を許可しているわけではないため、b-form-input は、入力タイプを null に変更し、すぐにタイプ file に戻すという、クロスブラウザで機能する手法を採用しています。

directory モード のネストされたファイル構造には、ブラウザでの Promise のサポートが必要です。 IE 11 などの古いブラウザをアプリのターゲットとする場合は、Promise のサポートを提供するポリフィルを含めてください。 Promise のサポートが検出されない場合、ファイルは常にフラットなファイル構造になります。

Chromium の「バグ」のため、directory モード のネストされたファイル構造は、現在、ディレクトリがファイル入力にドロップされた場合にのみサポートされています。 「参照」ダイアログを介して選択すると、常にフラット化された配列構造になります。 Mozilla は、Chromium と同じ方法で動作を実装しました。