表单文件

自定义的、跨浏览器一致的文件输入控件，支持单个文件、多个文件和目录上传（适用于支持目录模式的浏览器）。

<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 属性，用户可以选择目录而不是文件。如果选择了目录，则该目录及其所有内容层次结构都将包含在所选项目集中。

在 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。

在大多数现代浏览器中，当文件输入处于 plain 模式时，也支持目录模式。

拖放支持

默认情况下启用 Drop 模式。可以通过设置 no-drop 属性来禁用它。 no-drop 在 plain 模式下无效（某些浏览器支持将文件拖放到普通输入文件中）。

您可以选择通过 drop-placeholder 属性或作用域 drop-placeholder 插槽设置拖动时的不同占位符。该属性仅支持纯文本。使用插槽进行自定义 HTML 标记。插槽优先于属性。如果设置了 no-drop 或处于 plain 模式，则 drop-placeholder 属性/插槽无效。

请注意，本机浏览器约束（例如 required）不适用于 Drop 模式，因为隐藏的文件输入不处理拖放功能，并且不会选择任何文件。

限制为某些文件类型

您可以通过将 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> 不处于 plain 模式时，它提供了一些用于自定义其外观的功能。

控制大小

使用 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 标记。插槽优先于属性。

自定义浏览按钮标签

如果您想全局更改 Browse 标签，您可以在全局样式表中添加类似这样的内容。此外，建议对多语言网站使用 :lang()。

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

或者，您可以通过 browse-text 属性设置自定义文件浏览按钮文本的内容。请注意，仅支持纯文本。不支持 HTML 和组件。

文件名格式化函数

将属性 file-name-formatter 设置为接受三个参数的函数

参数	类型	说明
[1] `files`	数组	`File` 对象的扁平数组
[2] `filesTraversed`	数组	处于 `directory` 模式时，`File` 对象的数组数组
[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`	数组	`File` 对象的扁平数组
`filesTraversed`	数组	处于 `directory` 模式时，`File` 对象的数组数组
`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 包含大多数表单控件的 valid 和 invalid 状态的验证样式。

一般来说，你希望对特定类型的反馈使用特定状态

false（表示无效状态）非常适合在有阻止或必填字段时使用。用户必须正确填写此字段才能提交表单
true（表示有效状态）非常适合在整个表单中进行逐字段验证，并希望引导用户完成其余字段的情况
null 不显示验证状态（既不是有效也不是无效）

要在 <b-form-file> 上应用其中一个上下文状态图标，请将 state 属性设置为 false（无效）、true（有效）或 null（无验证状态）。

注意：在 plain 模式下不支持上下文状态。

自动对焦

当在 <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 相同的方式实现该行为。

组件参考

`<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` 时，尝试在装载时自动聚焦控件，或在保持活动状态时重新激活。不会在控件上设置 `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	`Array` 或 `File`	`null`	文件输入的当前值。将是一个 `File` 对象或 `File` 对象的数组（如果设置了 `multiple` 或 `directory`）。可以设置为 `null` 或空数组以重置文件输入

`v-model`

属性	事件
`value`	`input`

插槽

名称	作用域	说明
`drop-placeholder`		当文件即将被拖放时显示的占位符内容。默认为 `drop-placeholder` 属性的值
`file-name`		用于格式化文件名的作用域插槽
`placeholder`	否	当未选择文件时的占位符内容。默认为 `placeholder` 属性值

事件

事件	参数	说明
`change`	`event` - 原生 change 事件对象	输入的原始 change 事件
`input`	`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)