文件选择(Form File Input)

定制的，跨浏览器一致的文件输入控件，支持单个文件，多个文件和目录上传（对于支持目录模式的浏览器）

Choose a file or drop it here...

Selected file:

<template>
  <div>
    <!-- Styled -->
    <b-form-file
      v-model="file"
      :state="Boolean(file)"
      placeholder="Choose a file or drop it here..."
      drop-placeholder="Drop file here..."
    ></b-form-file>
    <div class="mt-3">Selected file: {{ file ? file.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 {
        file: null,
        file2: null
      }
    }
  }
</script>

为了实现跨浏览器的一致性，Form文件默认为Bootstrap定制文件输入，以替换浏览器的默认设置。它们建立在语义和可访问标记之上，因此可以替代默认文件输入。

单个文件（默认）

在单文件模式下，当未选择任何文件或用户取消“浏览”对话框时，v-model 为 null 表示未选择文件。选择文件后，返回值将是 JavaScript File 对象实例。

多个文件

通过向组件添加 multiple 属性来支持多个文件上传。在这种情况下，v-model 始终是一个 Array 。如果未选择任何文件，则将返回一个空数组。当选择一个或多个文件时，返回值将是 JavaScript File 对象实例的数组。

目录模式

通过添加 directory【目录】属性，用户可以选择目录而不是文件。选择目录后，该目录及其整个内容层次结构将包含在所选项目集中。可以使用 webkitEntries 属性获取选定的文件系统条目。

注意这是一项非标准功能，但最新的 Firefox 和 Chrome 版本支持该功能，因此不应将其用于生产。进一步了解MDN 。

当文件输入为 plain 模式时，不支持目录模式。

拖放支持

默认情况下，启用丢弃模式。可以通过设置 no-drop 属性来禁用它。在 plain 模式下，no-drop 无效。

您可以选择通过 drop-placeholder 属性设置其他占位符。默认为无放置占位符文本。仅支持纯文本。不支持HTML和组件。如果未设置 no-drop 或在 plain 模式下，drop-placeholder 属性无效。

限制为某些文件类型

您可以通过将 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 Media Types【IANA媒体类型】。

注意： 并非所有浏览器都支持或尊重文件输入的 accept 属性。

自定义

<b-form-file> 不在 plain mode 下时，提供了几种自定义其外观的功能。

控制尺寸

使用 size 属性控制输入的视觉大小。默认大小被认为是 md（中）。可选大小为 lg（大）和 sm（小）。这些大小与其他窗体控件上可用的大小一致。

Small:

No file chosen

Default:

No file chosen

Large:

No file chosen

<div>
  <b-form-group label="Small:" label-for="file-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-for="file-default" label-cols-sm="2">
    <b-form-file id="file-default"></b-form-file>
  </b-form-group>

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

注意： Bootstrap v4.x 本身不支持自定义文件控件的大小。但是，BootstrapVue 包含自定义 SCSS / CSS，它增加了对自定义文件输入控件的大小的支持。

自定义占位符文本

使用 placeholder 属性更改未选择文件时显示的提示文本。仅支持纯文本。不支持 HTML 和组件。

自定义浏览按钮标签

如果要全局更改 Browse 标签，则可以在全局样式表中添加类似的内容。另外，建议将 :lang() 用于多语言站点。

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

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

文件名格式化函数

将 file-name-formatter 属性设置为接受单个参数的函数，该参数是 File 对象的数组。该函数应返回单个格式化的字符串（不支持 HTML ）。如果未选择文件，则不会调用格式化程序。

无论是否设置了 multiple 属性，格式化程序的参数始终是一个数组。

No file chosen

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

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

通过作用域插槽格式化文件名

或者，您可以使用作用域插槽 file-name 来呈现文件名。作用域插槽将具有以下属性：

属性	类型	描述
`files`	Array	`File`【文件】对象数组
`names`	Array	文件名数组

不管 multiple【多重】属性的设置如何，这两个属性始终都是数组。

No file chosen

<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-name 插槽时，将忽略 file-name-formatter 属性。另外，如果没有选择文件，则不会渲染该插槽。

非自定义文件输入

您可以通过设置 plain【纯】属性使 <b-form-file> 呈现浏览器本机文件输入。请注意，设置为 plain 时，许多自定义表单文件功能均不适用。

上下文状态反馈

Bootstrap 包括大多数表单控件上 valid【有效】和 invalid【无效】状态的验证样式。

一般来说，您需要针对特定类型的反馈使用特定状态：

false （表示无效状态）非常适合存在阻塞或必填字段的情况。用户必须正确填写此字段才能提交表单。
true （表示有效状态）非常适合在整个表单中都进行逐字段验证并希望鼓励用户遍历其余字段的情况。
null 不显示验证状态（既不有效也不无效）

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

注意： 在按钮模式下，不支持上下文状态。

自动获取焦点

当将 autofocus 【自动对焦】属性设置为 <b-form-file> 时，输入将在插入（即 mounted【安装】）到文档中时自动对焦，或者在 Vue <keep-alive> 组件内部重新激活。请注意，此属性不会在输入上设置 autofocus【自动对焦】属性，也无法告诉输入何时可见。

辅助功能

使用 <b-form-file> 输入的自定义版本隐藏原始输入时，强烈建议 您通过 id 属性提供文档唯一的ID字符串。这将自动呈现所需的额外ARIA属性，以提高使用辅助技术的人员的可用性。

清除文件选择

使用文件类型输入时，通常 v-model 是单向的（这意味着您无法预设所选文件）。但是，您可以通过将 v-model 设置为 null（对于单模式）或空数组 []（对于多目录模式）来清除文件输入的选定文件。

另外，<b-form-file> 提供了 reset() 方法，可以调用该方法来清除文件输入。要利用 reset() 方法，您将需要获取对 <b-form-file> 组件的引用。

No file chosen

Selected 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>

实施注意事项： 实施注意事项：由于并非所有浏览器都允许设置文件输入的值（甚至设置为null或空字符串），因此 b-form-input 采用了一种跨浏览器工作的技术，该技术涉及将输入类型更改为 null ，然后立即返回键入 file【文件】。

组件引用

`<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 或使用组件组插件时可用。

属性

属性 (Click to sort Ascending)	类型	默认值	描述
`id`	String		用于在渲染的内容上设置“id”属性，并用作根据需要生成任何其他元素ID的基础
`name`	String		设置表单控件上“name”属性的值
`disabled`	Boolean		设置为“true”时，禁用组件的功能并将其置于禁用状态
`required`	Boolean	`false`	将“required”【必需】属性添加到表单控件
`form`	String		表单控件所属的表单的ID。在控件上设置“form”属性
`autofocus`	Boolean	`false`	设置为“true”时，尝试在安装控件时自动将其调焦，或者在保持活动状态时将其重新激活。未在控件上设置“autofocus”属性
`state`	Boolean		控制组件的验证状态外观。“true”表示有效，“false”表示无效”，“null”表示无验证状态
`plain`	Boolean	`false`	以普通模式而不是自定义样式模式渲染表单控件
`size`	String		设置组件外观的大小。'sm'，'md'（默认）或'lg'
`value` v-model	File or Array		文件输入的当前值。将是单个 File 对象或 File 对象数组（如果设置了多个或目录）。可以设置为null，也可以设置为空数组以重置文件输入
`accept`	String		在文件输入的“accept”属性上设置的值
`capture`	Boolean	`false`	设置后，将指示浏览器使用设备的摄像头（如果支持）
`placeholder`	String	`'No file chosen'`	在表单控件上设置“placeholder”属性值
`browse-text`	String	`'Browse'`	文件浏览按钮的文本内容
`drop-placeholder`	String	`'Drop files here'`	拖动文件时显示为占位符的文本
`multiple`	Boolean	`false`	设置后，将允许选择多个文件。v-model将是一个数组
`directory`	Boolean	`false`	启用目录删除模式（在支持目录模式的浏览器上）
`no-traverse`	Boolean	`false`	对于目录删除模式：以平面数组形式返回文件
`no-drop`	Boolean	`false`	禁用拖放模式
`file-name-formatter`	Function		格式化显示文件名的方法。有关详细信息，请参阅文档

v-model

属性	事件
`value`	`input`

插槽

插槽名称	描述	范围
`file-name`	用于格式化文件名的作用域插槽

事件

事件	参数	描述
`change`	`event` - 本机变更事件对象	输入时的原始本机更改事件
`input`	`file` - 在单一模式下将是单个 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)