表單檔案

自訂、跨瀏覽器一致、支援單一檔案、多個檔案，以及資料夾上傳的檔案輸入控制（適用於支援資料夾模式的瀏覽器）。

<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 總是為 Array。當未選取任何檔案，將會傳回一個空陣列。當選取一個或多个檔案後，傳回值將會是 JavaScript File 物件執行個體的陣列。

資料夾模式

注意：資料夾模式是一個非標準功能。雖然所有現代瀏覽器都支援它，但不應該依賴它用於製作階段。在 MDN 和 Can I use 上閱讀更多資訊。

透過加入 directory 屬性，使用者可以選擇資料夾而不是檔案。當選取資料夾時，資料夾及其內容的完整階層都會包含在選取項目集中。

處於 目錄 模式時，檔案會以巢狀陣列格式回傳，預設為如此。

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

會回傳類似以下的內容（或檔案/目錄順序可能有所不同）

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

如果你設定 no-traverse prop，陣列將會扁平化

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

每個檔案條目會有個特殊 $path prop，其中會包含每個檔案的相對路徑。對於巢狀目錄結構，BootstrapVue 使用其自己的例程來決定相對路徑，否則它會依賴 File.webkitRelativePath。

當檔案輸入在 plain 模式時，在大多數現代瀏覽器上目錄模式也受支援。

拖放支援

預設情況下會啟用拖放模式。可以透過設定 no-drop prop 來停用。在 plain 模式中 no-drop 沒有作用（某些瀏覽器支援將檔案拖放到普通輸入檔案中）。

你可以選擇透過 drop-placeholder prop 或範圍 drop-placeholderslot 設定拖放過程中的不同佔位符。該 prop 僅支援純文字。使用該 slot 可建立自訂的 HTML 標記。slot 優先於 prop。drop-placeholder prop/slot 如果設定 no-drop或在 plain 模式時沒有作用。

請注意，原生瀏覽器限制（例如 required）會因拖放模式而無法運作，因為隱藏的檔案輸入不會處理拖放功能且沒有選擇任何檔案。

限制特定檔案類型

你可以透過設定 accept prop 為包含允許檔案類型字串，來限制檔案類型。若要指定多種類型，請用逗號分隔各個值。

<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> 不處於 plain 模式時，它提供許多功能來自訂其外觀。

控制大小

使用 size prop 來控制輸入的外觀大小。預設大小視為 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 標記。區段優先於屬性。

自訂瀏覽按鈕標籤

如果您想要變更全域 Browse 標籤，您可以在全域樣式表中加入類似這樣的內容。建議使用 :lang() 以使用多語言網站。

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

或者，您可以透過 browse-text 屬性設定自訂檔案瀏覽按鈕文字內容。請注意，僅支援純文字。HTML 和元件不受支援。

檔案名稱格式化器函式

將屬性 file-name-formatter 設定為接受三個引數的函式

引數	類型	說明
[1] `files`	陣列	`檔案`物件的平面陣列
[2] `filesTraversed`	陣列	`檔案`物件陣列陣列，指定於 `directory` 模式中
[3] `names`	陣列	檔案名稱平面陣列（字串）

函式應回傳單一格式化字串（不支援 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 來呈現檔案名稱。範圍區段將接收下列屬性

屬性	類型	說明
`files`	陣列	`檔案`物件的平面陣列
`filesTraversed`	陣列	`檔案`物件陣列陣列，指定於 `directory` 模式中
`names`	陣列	檔案名稱平面陣列（字串）

無論 multiple 屬性的設定為何，這三個屬性永遠都是陣列。

<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 包含驗證樣式以供在大部分的表單控制項上使用 有效 和 無效 狀態。

一般而言，您會想要對特定類型的回饋使用特定狀態

false（表示無效狀態）適用於有封鎖或必填欄位的情況。使用者必須正確填寫此欄位才能提交表單
true（表示有效狀態）適用於在整個表單中對每個欄位時進行驗證，並鼓勵使用者完成其餘欄位的情況
null 不顯示驗證狀態（既非有效也非無效）

要在 <b-form-file> 上套用其中一個情境狀態圖示，請將 state 屬性設定為 false（無效）、true（有效）或 null（無驗證狀態）。

請注意：在 plain 模式中不支援情境狀態。

自動對焦

當 autofocus 屬性設定在 <b-form-file>，輸入會在插入 (即掛載) 到文件中，或者在 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 相同的方式實作這項行為。

組件參考

`<b-form-file>`

查看原始碼

<b-form-file> 組件別名
<b-form-file> 屬性
<b-form-file> v-model
<b-form-file> 插槽
<b-form-file> 事件

組件別名

<b-form-file> 還可透過下列別名使用

<b-file>

注意：唯在匯入所有 BootstrapVue 或使用組件群組外掛時元件別名才可以使用。

屬性

所有的預設屬性值都可進行全域配置。

屬性 (按一下進行升冪排序)	類型 (按一下進行升冪排序)	預設值	說明
`accept`	`字串`	`''`	設定於檔案輸入 `accept` 屬性上的值
`autofocus`	`布林值`	`false`	設定為 `true` 時，嘗試在掛載時自動對焦控制項，或在 keep-alive 中重新啟用時自動對焦。不會設定控制項的 `autofocus` 屬性
`browse-text`	`字串`	`'瀏覽'`	檔案瀏覽按鈕的文字內容
`capture`	`布林值`	`false`	設定後，會指示瀏覽器使用裝置相機（若支援）
`directory`	`布林值`	`false`	啟用 `directory` 模式（在支援它的瀏覽器上）
`disabled`	`布林值`	`false`	設定為 `true` 時，會停用組件功能並置入停用狀態
`drop-placeholder`	`字串`	`'將檔案拖曳到這裡'`	在檔案被拖曳且允許放置到這裡時，作為放置區文字顯示的內容
`file-name-formatter`	`函式`		用於設定檔案顯示名稱格式的方法。詳細資料請參考文件
`form`	`字串`		表單控制項所屬的表單 ID。設定控制項的 `form` 屬性
`id`	`字串`		用於設定呈現內容的 `id` 屬性，並用作依需要產生任何額外元素 ID 的基礎
`multiple`	`布林值`	`false`	設定後，允許多重檔案選取。`v-model` 將會是陣列
`name`	`字串`		設定表單控制項上 `name` 屬性的值
`no-drop`	`布林值`	`false`	停用拖放模式
`no-drop-placeholder`	`字串`	`'不允許'`	在檔案被拖曳且不允許放置到這裡時，作為放置區文字顯示的內容
`no-traverse`	`布林值`	`false`	是否在 `directory` 模式時，將檔案回傳為平面陣列
`placeholder`	`字串`	`'尚未選擇檔案'`	設定表單控制項的 `placeholder` 屬性值
`plain`	`布林值`	`false`	以純文字模式，而非自訂樣式模式，呈現表單控制項
`required`	`布林值`	`false`	將 `required` 屬性加入表單控制項
`size`	`字串`		設定組件樣式的尺寸。'sm'、'md'（預設）或 'lg'
`state`	`布林值`	`null`	控制組件的驗證狀態外觀。`true` 代表有效，`false` 代表無效，或 `null` 代表沒有驗證狀態
`value` v-model	`陣列` 或 `檔案`	`null`	檔案輸入的目前值。將會是單一 `檔案` 物件或 `檔案` 物件陣列（如果設定 `multiple` 或 `directory`）。可以設定為 `null` 或空陣列，以重設檔案輸入

`v-model`

屬性	事件
`value`	`input`

插槽

名稱	範圍	說明
`drop-placeholder`		當檔案準備就緒時，顯示的放置區內容。預設為 `drop-placeholder` 屬性值
`file-name`		檔案顯示名稱格式設定的範圍插槽
`placeholder`	否	放置區內容，表示沒有選取任何檔案。預設為 `placeholder` 屬性值

事件

事件	參數	說明
`change`	`event` - 原生變更事件物件	輸入的原始變更事件
`input`	`檔案` - 單一模式的單一 File 物件或多重模式中的 File 物件陣列	更新 `v-model` 值 (如需詳細資訊，請參閱文件)

匯入個別元件

您可以透過下列命名匯出將個別元件匯入您的專案

元件	命名匯出	匯入路徑
`<b-form-file>`	`BFormFile`	`bootstrap-vue`

範例

import { BFormFile } from 'bootstrap-vue'
Vue.component('b-form-file', BFormFile)

以 Vue.js 外掛程式匯入

此外掛程式包含以上所有列出的個別元件. 外掛程式也包含所有元件別名。

命名匯出	匯入路徑
`FormFilePlugin`	`bootstrap-vue`

範例

import { FormFilePlugin } from 'bootstrap-vue'
Vue.use(FormFilePlugin)