Как добавить загрузку файла¶

Загрузка файлов¶

Добавлять загрузку файлов можно в схемах страниц, конфигурации, плагинов и тем. Загрузка файлов всегда выполняется через Ajax и позволяет перетаскивать файлы с рабочего стола или выбирать их как в обычных полях файлов. Каждый раз, когда файл добавляется в поле, он автоматически загружается во временную папку и сохраняется только при выполнении действия Save (или Submit).

Пример использования:

1
2
3
4
5
6
7
8
9

custom_file:
  name: myfile
  type: file
  label: A Label
  destination: 'plugins://my-plugin/assets'
  multiple: true
  autofocus: false
  accept:
    - image/*

Параметры¶

У поля файла есть множество параметров: от допустимого MIME-типа или расширения до разрешённого размера файла:

Значения по умолчанию¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

custom_file:
  type: file
  label: A Label
  multiple: false
  destination: 'self@'
  random_name: false
  avoid_overwriting: false
  limit: 10
  accept:
    - image/*

multiple¶

multiple: false # [false | true]

Как и обычное HTML5-поле файла, при включённом параметре multiple оно позволяет загрузить больше одного файла. Этот параметр также связан с параметром limit, который определяет, сколько из нескольких файлов разрешено для поля.

destination¶

destination: 'self@' # [<path> | <stream> | self@ | page@:<path>]

Destination — место, где должны храниться загруженные файлы. Это может быть обычный path (относительно корня Grav), stream (например, theme://images), self@ или специальный префикс page@:. Также можно указать подпапку относительно текущей страницы с помощью self@/path.

Примеры¶

1. Если нужно загружать файлы в папку плагина testing (user/plugins/testing), destination будет таким:

destination: 'plugins://testing'

1. Предположим, у нас есть элемент блога по маршруту /blog/ajax-upload (физически user/pages/02.blog/ajax-upload); с префиксом page@: destination будет таким:

destination: 'page@:/blog/ajax-upload'

1. Предположим, текущая тема — antimatter, и мы хотим загружать файлы в папку assets (физически user/themes/antimatter/assets); с потоком theme destination будет таким:

destination: 'theme://assets'

random_name¶

random_name: false # [false | true]

Когда random_name включён, загруженный файл переименовывается в случайную строку длиной 15 символов. Это полезно, если вы хотите хэшировать загружаемые файлы или ищете способ уменьшить коллизии имён.

Пример¶

'my_file.jpg' => 'y5bqsGmE1plNTF2.jpg'

avoid_overwriting¶

avoid_overwriting: false # [false | true]

Когда avoid_overwriting включён и файл с тем же именем, что и загружаемый, уже существует в destination, он будет переименован. К имени нового загруженного файла будет добавлен префикс из текущей даты и времени, соединённых дефисом.

Пример¶

'my_file.jpg' => '20160901130509-my_file.jpg'

limit¶

limit: 10 # [1...X | 0 (unlimited)]

Когда параметр multiple включён, limit позволяет ограничить число разрешённых файлов для отдельного поля. Если multiple не включён (по умолчанию он выключен), limit автоматически принимает значение 1.

Если limit равен 0, это означает отсутствие ограничений на количество загружаемых файлов.

accept¶

1
2

accept:
  - 'image/*' # Массив MIME-типов и/или расширений. ['*'] разрешает любой файл.

Параметр accept принимает массив MIME-типов, а также определения расширений. Все расширения должны начинаться с . (точки), за которой следует само расширение.

Кроме того, разрешить любой файл можно с помощью звёздочки __*__: accept: ['*'].

Примеры¶

1. Разрешить только файлы yaml и json:

1
2
3

accept:
  - .yaml
  - .json

1. Разрешить только изображения и видео:

1
2
3

accept:
  - 'image/*'
  - 'video/*'

1. Разрешить любые изображения, любые видео и только файлы mp3:

1
2
3
4

accept:
  - 'image/*'
  - 'video/*'
  - .mp3

1. Разрешить любой файл:

1
2

accept:
  - '*'

filesize¶

Максимальный размер файла ограничивается:

1. параметром filesize: на уровне поля; затем…

2. параметром files: filesize: в конфигурации плагина Form (user/plugins/form.yaml); затем, если ни один из них не ограничивает…

3. конфигурацией PHP: upload_max_filesize для отдельных загружаемых файлов и post_max_size для максимального общего размера POST-запроса формы.

Примеры¶

1. Ограничить конкретное поле до 5M:

1
2
3
4
5
6
7
8

custom_file:
  name: myfile
  type: file
  label: A Label
  destination: 'plugins://my-plugin/assets'
  filesize: 5
  accept:
    - image/*

1. Ограничить все поля файлов до 5M: отредактируйте файл user/config/form.yaml:

1
2
3
4
5
6
7
8
9

files:
  multiple: false
  limit: 10
  destination: 'self@'
  avoid_overwriting: false
  random_name: false
  filesize: 5
  accept:
    - 'image/*

allow_extensions¶

1

allow_extensions: [css] # Массив расширений, любые из: md, markdown, css, scss, sass, less

В Admin2 поля файлов загружают данные через API, который по умолчанию запрещает содержимое страниц (.md, .markdown) и таблицы стилей (.css, .scss, .sass, .less), поскольку иначе учётная запись с правом загрузки медиа могла бы записывать или удалять эти файлы где угодно в user/. Разработчик может разрешить их для конкретного поля, перечислив их в allow_extensions. Требуются API 1.0.38 и Admin2 2.1.21.

Пример¶

1
2
3
4
5
6
7

custom_css:
  type: file
  label: Custom stylesheet
  destination: 'self@:css'
  accept:
    - .css
  allow_extensions: [css]

### Устаревшая обработка загрузки файлов и ручное управление

Для базовой обработки файлов достаточно определения поля. Файлы загружаются во временное место через виджет Dropzone с помощью XHR-запроса к серверу. При отправке формы файлы автоматически перемещаются из временного места в окончательное. Однако можно использовать действие upload: true в блоке process:, чтобы вручную указать, на каком этапе рабочего процесса должны перемещаться эти файлы.

##### Пример.

1
2
3
4

process:
    upload: true
    message: 'Thank you for your files'
    reset: true