Файл формы

Настраиваемый, кросс-браузерный, элемент управления вводом файлов, который поддерживает загрузку одного файла, нескольких файлов и каталогов (для браузеров, поддерживающих режим каталогов).

<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">Выбранный файл: {{ file1 ? file1.name : '' }}</div>

    <!-- Plain mode -->
    <b-form-file v-model="file2" class="mt-3" plain></b-form-file>
    <div class="mt-3">Выбранный файл: {{ 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 и Могу я использовать.

Добавляя свойство 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 в большинстве современных браузеров.

Поддержка перетаскивания

По умолчанию включен режим перетаскивания. Его можно отключить, установив свойство no-drop. no-drop не действует в режиме plain (некоторые браузеры поддерживают перетаскивание файлов в простой входной файл).

При желании вы можете установить другой заполнитель при перетаскивании через свойство drop-placeholder или слот drop-placeholder с заданной областью действия. Свойство поддерживает только обычный текст. Используйте слот для пользовательской разметки HTML. Слот имеет приоритет над свойством. Свойство/слот drop-placeholder не действует, если установлено no-drop или в режиме plain.

Обратите внимание, что собственные ограничения браузера (такие как required) не будут работать в режиме перетаскивания, поскольку скрытый ввод файла не обрабатывает функциональность перетаскивания и будет иметь нулевые выбранные файлы.

Ограничение определенными типами файлов

Вы можете ограничить типы файлов, установив свойство accept в строку, содержащую разрешенный тип(ы) файлов. Чтобы указать более одного типа, разделите значения запятой.

<div>
  <!-- Принять все форматы изображений с помощью подстановочного знака типа мультимедиа IANA-->
  <b-form-file accept="image/*"></b-form-file>

  <!-- Принимать определенные форматы изображений по типу IANA -->
  <b-form-file accept="image/jpeg, image/png, image/gif"></b-form-file>

  <!-- Принимать определенные форматы изображений по расширению -->
  <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 Array Плоский массив объектов File
[2] filesTraversed Array Массив массивов объектов File в режиме directory
[3] names Array Плоский массив имен файлов (строк)

Функция должна возвращать одну отформатированную строку (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 Array Плоский массив объектов File
filesTraversed Array Массив массивов объектов File в режиме directory
names Array Плоский массив имен файлов (строк)

Все три свойства всегда являются массивами, независимо от настройки свойства 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 }} Больше файлов
     </b-badge>
   </template>
  </b-form-file>
</template>

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

При использовании слота file-name свойство file-name-formatter игнорируется. Слот не будет отображаться, если не выбран ни один файл(ы).

Нестандартный ввод файла

Вы можете сделать так, чтобы <b-form-file> отображал исходный файл браузера, установив свойство plain. Обратите внимание, что многие из настраиваемых функций не применяются, когда установлен plain.

Контекстная обратная связь о состоянии

Bootstrap включает стили проверки valid и invalid состояний для большинства элементов управления формой.

Вообще говоря, вы захотите использовать определенное состояние для определенных типов обратной связи:

  • false (обозначает недопустимое состояние) отлично подходит, когда есть блокирующее или обязательное поле. Пользователь должен правильно заполнить это поле, чтобы отправить форму
  • true (обозначает допустимое состояние) идеально подходит для ситуаций, когда у вас есть проверка по полю во всей форме и вы хотите побудить пользователя пройти через остальные поля
  • null diне отображает состояние проверки (ни действительное, ни недействительное)

Чтобы применить один из иконок контекстного состояния к <b-form-file>, установите для свойства state значение false (для недопустимого), true (для действительного) или null (состояние проверки отсутствует).

Примечание: Контекстные состояния не поддерживаются в режиме plain.

Автофокус

Когда свойство autofocus установлено на <b-form-file>, ввод будет автоматически сфокусирован, когда он вставлен (т.е. установлен) в документ, или повторно активирован, когда он находится внутри Vue. Компонент <keep-alive>. Обратите внимание, что это свойство не устанавливает атрибут autofocus на входе и не может определить, когда ввод становится видимым.

Доступность

При использовании пользовательской версии ввода <b-form-file>, которая скрывает исходный ввод, настоятельно рекомендуется указать строку уникального идентификатора документа через свойство id. Это автоматически отобразит дополнительные атрибуты ARIA, необходимые для повышения удобства использования людьми, использующими вспомогательные технологии.

Очистка выбора файла

При вводе типа file обычно 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">Сброс с помощью метода</b-button>
    <b-button @click="file = null">Сброс через v-model</b-button>

    <p class="mt-2">Выбранный файл: <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-file>

Примечание: Псевдонимы компонентов доступны только при импорте всего BootstrapVue или при использовании подключаемого модуля группы компонентов.

Свойства

Все значения свойств по умолчанию настраиваются глобально.

Свойство
(Click to sort ascending)
Тип
(Click to sort ascending)
По умолчанию
Описание
accept
String''Значение, устанавливаемое для атрибута `accept` входного файла
autofocus
BooleanfalseЕсли установлено значение `true`, пытается автоматически сфокусировать элемент управления, когда он установлен, или повторно активировать, когда находится в состоянии активности. Не устанавливает атрибут `autofocus` на элементе управления
browse-text
String'Browse'Текстовое содержимое для кнопки просмотра файла
capture
BooleanfalseЕсли установлено, будет указывать браузеру использовать камеру устройства (если поддерживается)
directory
BooleanfalseВключите режим `directory` (в браузерах, которые его поддерживают)
disabled
BooleanfalseЕсли установлено значение `true`, отключает функциональность компонента и переводит его в отключенное состояние.
drop-placeholder
String'Drop files here'Текст, отображаемый в качестве заполнителя, когда файлы перетаскиваются, и их можно оставить
file-name-formatter
FunctionМетод форматирования имен файлов для отображения. Подробности смотрите в документации
form
StringИдентификатор формы, к которой принадлежит элемент управления формой. Устанавливает атрибут `form` в элементе управления
id
StringИспользуется для установки атрибута `id` для визуализированного контента и используется в качестве основы для генерации любых дополнительных идентификаторов элементов по мере необходимости.
multiple
BooleanfalseЕсли установлено, можно выбрать несколько файлов. `v-model` будет массивом
name
StringУстанавливает значение атрибута `name` в элементе управления формы
no-drop
BooleanfalseОтключить режим перетаскивания
no-drop-placeholder
String'Not allowed'Текст, отображаемый в качестве заполнителя, когда файлы перетаскиваются, и их нельзя бросать
no-traverse
BooleanfalseСледует ли возвращать в виде плоского массива в режиме `directory`
placeholder
String'No file chosen'Устанавливает значение атрибута `placeholder` элементе управления формы
plain
BooleanfalseВизуализируйте элемент управления формы в обычном режиме, а не в режиме пользовательского стиля
required
BooleanfalseДобавляет атрибут `required` в элемент управления формы
size
StringУстанавливает размер внешнего вида компонента. 'sm', 'md' (по умолчанию) или 'lg'
state
BooleannullУправляет внешним видом состояния проверки компонента. `true` для действительного, `false` для недопустимого или `null` для отсутствия проверки состояния
value
v-model
Array или FilenullТекущее значение входного файла. Будет одиночным объектом `File` или массивом объектов `File` (если установлено `multiple` или `directory`). Может иметь значение `null` или пустой массив для сброса ввода файла

v-model

Свойство
Событие
valueinput

Слоты

Наименование
Область
Описание
drop-placeholder Контент-заполнитель, когда файлы собираются отбрасывать. По умолчанию значение свойства `drop-placeholder`
file-name Слот с ограниченным размером для форматирования имен файлов
placeholder НетЗаполнитель содержимого, когда файлы не выбраны. По умолчанию значение свойства `placeholder`

События

Событие
Аргументы
Описание
change
  1. event - Собственный объект события изменения
Исходное событие изменения ввода
input
  1. file - Будет одиночным объектом File в одиночном режиме или массивом объектов File в множественном режиме
Обновляет значение `v-model` (подробности смотрите в документации)

Импорт отдельных компонентов

Вы можете импортировать отдельные компоненты в свой проект с помощью следующих именованных экспортов:

Компонент
Именованный экспорт
Путь импорта
<b-form-file>BFormFilebootstrap-vue

Пример:

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

Импортировать как плагин Vue.js

Этот плагин включает в себя все перечисленные выше отдельные компоненты. Плагины также включают псевдонимы любых компонентов.

Именованный экспорт
Путь импорта
FormFilePluginbootstrap-vue

Пример:

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