diff --git a/files/uk/web/html/element/input/file/index.md b/files/uk/web/html/element/input/file/index.md new file mode 100644 index 0000000000..56e2853503 --- /dev/null +++ b/files/uk/web/html/element/input/file/index.md @@ -0,0 +1,458 @@ +--- +title: +slug: Web/HTML/Element/input/file +tags: + - Directory Picker + - File + - File Picker + - Files + - Form input + - HTML + - HTML forms + - Input Type + - Reference + - Type +browser-compat: html.elements.input.type_file +--- + +{{HTMLRef("Input_types")}} + +Елементи {{HTMLElement("input")}} із атрибутом **`type="file"`** дають користувачеві змогу обрати один чи більше файлів з його пристрою. Бувши обраними, файли можуть бути завантажені на сервер за допомогою [подання форми](/uk/docs/Learn/Forms), або ж використані за допомогою коду на JavaScript та [файлового API](/uk/docs/Web/API/File_API/Using_files_from_web_applications). + +{{EmbedInteractiveExample("pages/tabbed/input-file.html", "tabbed-shorter")}} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Значення + Рядок, що представляє шлях до вибраного файлу. +
Події + {{domxref("HTMLElement/change_event", "change")}} та {{domxref("HTMLElement/input_event", "input")}} +
Підтримувані загальні атрибути{{htmlattrxref("required", "input")}}
Додаткові атрибути + accept, + capture, + multiple +
Атрибути IDLfiles і value
Інтерфейс DOM

{{domxref("HTMLInputElement")}}

Методи + {{domxref("HTMLInputElement.select", "select()")}} +
+ +## Значення + +Атрибут файлового поля {{htmlattrxref("value", "input")}} містить рядок, що представляє шлях до обраного файлу (або файлів). Якщо користувач обрав декілька файлів, то `value` представляє перший файл з обраних. Решта файлів можуть бути встановлені за допомогою властивості поля `HTMLInputElement.files`. + +> **Примітка:** +> +> 1. Якщо вибрані декілька файлів, то рядок представляє перший із них. JavaScript може доступитися до решти [за допомогою властивості `files` поля введення](/uk/docs/Web/API/File_API/Using_files_from_web_applications#otrymannia-informatsiii-pro-vybrani-faily). +> 2. Якщо жоден файл іще не був вибраний, цей рядок – `""` (порожній). +> 3. Рядок [отримує префікс `C:\fakepath\` (англ.)](https://html.spec.whatwg.org/multipage/input.html#fakepath-srsly), щоб не дати зловмисним програмам дізнатися про файлову структуру пристрою користувача. + +## Додаткові атрибути + +На додачу до загальних атрибутів, що їх поділяють усі елементи {{HTMLElement("input")}}, поля типу `file` також підтримують наступні: + +### accept + +Значення атрибута [`accept`](/uk/docs/Web/HTML/Attributes/accept) – рядок, що визначає типи файлів, котрі повинно приймати файлове поле. Цей рядок – розділений комами список **[унікальних вказівок типу файлу](#unikalni-vkazivky-typu-failu)**. Оскільки певний тип файлу може бути ідентифікований більш ніж одним способом, слушно надавати повний набір вказівок типу, коли необхідні файли конкретного формату. + +Наприклад, є низка способів ідентифікувати файли Microsoft Word, тому сайт, що приймає файли Word, може використовувати `` такого виду: + +```html + +``` + +### capture + +Значення атрибута [`capture`](/uk/docs/Web/HTML/Attributes/capture) – рядок, що вказує яку камеру слід використовувати для захоплення фото чи відео, якщо атрибут [`accept`](/uk/docs/Web/HTML/Attributes/accept) вказує, що введені дані повинні бути фото чи відео. Значення `user` ("користувач") вказує, що повинні використовуватися фронтальні камера та (або) мікрофон. Значення `environment` ("середовище") вказує, що повинні використовуватися камера та (або) мікрофон, спрямовані назовні. Якщо такого атрибута немає, то {{Glossary("user agent", "користувацький агент")}} вільний сам вирішувати, що робити. Якщо вказаний фронтальний режим, але він недоступний, то користувацький агент може відступити до свого усталеного режиму. + +> **Примітка:** `capture` раніше був булевим атрибутом, котрий призводив до запиту на використання захоплення медіа, камери чи мікрофона, а не введення файлу. + +### multiple + +Коли вказаний булів атрибут [`multiple`](/uk/docs/Web/HTML/Attributes/multiple), то файлове поле дозволяє користувачеві вибрати більш ніж один файл. + +## Нестандартні атрибути + +На додачу до вище перелічених атрибутів, у деяких браузерах доступні наступні нестандартні атрибути. Слід уникати їх використання, коли це можливо, адже воно обмежує змогу вашого коду діяти в браузерах, що не мають їх реалізації. + +### `webkitdirectory` + +Булів атрибут `webkitdirectory`, коли присутній, вказує, що для вибору користувачем в інтерфейсі вибору файлу повинні бути доступні лише директорії. Дивіться {{domxref("HTMLInputElement.webkitdirectory")}} для отримання подробиць та прикладів. + +Бувши спершу реалізованим лише в браузерах на основі WebKit, `webkitdirectory` також працює в Microsoft Edge, а також Firefox 50 і новішим. Втім, навіть попри його відносно широку підтримку, він все ж є нестандартним і не повинен використовуватись, окрім випадків, коли немає інших варіантів. + +## Унікальні вказівки типу файлу + +**Унікальна вказівка типу** – рядок, що описує тип файлу, котрий може бути обраний користувачем в елементі {{HTMLElement("input")}} типу `file`. Кожна унікальна вказівка типу файлу може приймати одну з наступних форм: + +- Дійсне байдуже до регістру розширення імені файлу, що починається з символу крапки ("."). Наприклад: `.jpg`, `.pdf`, `.doc`. +- Чинний рядок типу MIME, без розширень. +- Рядок `audio/*`, що означає "будь-який файл аудіо". +- Рядок `video/*`, що означає "будь-який файл відео". +- Рядок `image/*`, що означає "будь-який файл зображення". + +Атрибут `accept` приймає за значення рядок, що містить одну чи більше таких унікальних вказівок типу файлу, розділених комами. Наприклад, вибір файлу, що потребує вмісту, котрий може бути представлений як зображення, включно зі стандартними форматами зображень і файлами PDF, може мати такий вигляд: + +```html + +``` + +## Використання файлових полів + +### Найпростіший приклад + +```html +
+
+ + +
+
+ +
+
+``` + +```css hidden +div { + margin-bottom: 10px; +} +``` + +This produces the following output: + +{{EmbedLiveSample('naiprostishyi-pryklad', 650, 90)}} + +> **Примітка:** Також цей приклад можна знайти на GitHub, дивіться [вихідний код](https://github.com/mdn/learning-area/blob/main/html/forms/file-examples/simple-file.html), а також [погляньте на нього в дії](https://mdn.github.io/learning-area/html/forms/file-examples/simple-file.html). + +Незалежно від пристрою чи операційної системи користувача, файлове поле надає кнопку, що відкриває діалог вибору файлу, котрий дає користувачеві змогу вибрати файл. + +Включення атрибута {{htmlattrxref("multiple", "input/file")}}, як показано вище, вказує, що водночас можуть бути обрані декілька файлів. Користувач може обрати декілька файлів у будь-який спосіб, котрий пропонує його платформа (наприклад, утримуючи натисненою клавішуShift або Control, а потім клацаючи). Якщо необхідно, щоб користувач міг обрати лише один файл в одному ``, слід упустити атрибут `multiple`. + +### Отримання інформації про вибрані файли + +Вибрані файли повертає властивість елемента `HTMLInputElement.files`, причому повертає у вигляді об‘єкта {{domxref("FileList")}}, що зберігає список об‘єктів {{domxref("File")}} objects. `FileList` поводиться подібно до масиву, тож для отримання числа вибраних файлів можна перевірити властивість `length`. + +Кожний об‘єкт `File` містить наступну інформацію: + +- `name` (ім‘я) + - : Ім‘я файлу. +- `lastModified` (востаннє змінений) + - : Число, що вказує дату й час, коли файл востаннє був змінений, у вигляді мілісекунд, що минули від початку епохи UNIX (опівночі 1 січня 1970 року). +- `lastModifiedDate` (дата останніх змін) {{deprecated_inline}} + - : Об‘єкт {{jsxref("Date")}}, що представляє дату й час, коли файл востаннє був змінений. _Ця властивість є нерекомендованою. Замість неї слід використовувати `lastModified`._ +- `size` (розмір) + - : Розмір файлу в байтах. +- `type` (тип) + - : [MIME-тип](/uk/docs/Web/HTTP/Basics_of_HTTP/MIME_types) файлу. +- `webkitRelativePath` (відносний шлях WebKit) {{non-standard_inline}} + - : Рядок, що представляє шлях до файлу відносно базової директорії, обраної при виборі директорії (тобто в інтерфейсі вибору `file`, що має атрибут {{htmlattrxref("webkitdirectory", "input/file")}}). _Ця властивість є нестандартною, її слід використовувати з обережністю._ + +> **Примітка:** У всіх сучасних браузерах значення `HTMLInputElement.files` можна як отримати, так і встановити; останнім з браузерів цю функціональність додав Firefox у версії 57 (дивіться {{bug(1384030)}}). + +### Обмеження прийнятних типів файлу + +Часто не хочеться давати користувачеві змогу обрати файл будь-якого довільного типу; натомість часто хочеться дозволити йому обирати файли певного типу чи типів. Наприклад, якщо файлове поле дає користувачам змогу завантажити зображення профілю, то, ймовірно, ви хочете дозволити вибрати сумісні з вебом формами зображень, наприклад, {{Glossary("JPEG")}} чи {{Glossary("PNG")}}. + +Прийнятні типи файлу можна задати за допомогою атрибута {{htmlattrxref("accept","input/file")}}, котрий приймає список дозволених розширень файлу чи MIME-типів, розділених комами. Трохи прикладів: + +- `accept="image/png"` чи `accept=".png"` — приймає файли PNG. +- `accept="image/png, image/jpeg"` чи `accept=".png, .jpg, .jpeg"` — Приймає файли PNG чи JPEG. +- `accept="image/*"` — Приймає будь-який файл з MIME-типом `image/*`. (Чимало мобільних пристроїв також дозволять користувачеві зробити фото за допомогою камери, коли таке застосовується.) +- `accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document"` — приймає що завгодно, від чого віє документом MS Word. + +Погляньмо на повніший приклад: + +```html +
+
+ + +
+
+ +
+
+``` + +```css hidden +div { + margin-bottom: 10px; +} +``` + +Це породжує вивід, подібний до того, що був у попередньому прикладі: + +{{EmbedLiveSample('obmezhennia-pryiniatnykh-typiv-failu', 650, 90)}} + +> **Примітка:** Цей приклад також можна знайти на GitHub, – дивіться [вихідний код](https://github.com/mdn/learning-area/blob/main/html/forms/file-examples/file-with-accept.html), а також [той самий приклад у дії](https://mdn.github.io/learning-area/html/forms/file-examples/file-with-accept.html). + +Це може здаватися схожим, але якщо спробувати вибрати файл із таким полем, то стане помітно, що інтерфейс вибору файлу дозволяє вибрати файли лише тих типів, що вказані у значенні `accept` (конкретний інтерфейс відрізняється в різних браузерах та операційних системах). + +Атрибут `accept` не перевіряє типи вибраних файлів; цей атрибут підказує браузерам, як підвести користувачів до вибору відповідних типів файлів. Усе ж можливо (в більшості випадків) вимкнути при виборі файлу це обмеження і вибрати будь-який бажаний файл, із некоректним типом. + +У зв‘язку з цим слід пересвідчитися, що атрибут `accept` доповнений відповідною валідацією на боці сервера. + +### Примітки + +1. Не можна встановити значення файлового поля зі сценарію, – код типу того, що нижче, не подіє: + + ```js + const input = document.querySelector('input[type=file]'); + input.value = 'foo'; + ``` + +2. Коли за допомогою `` обирається файл, реальний шлях до такого файлу з очевидних міркувань безпеки не показується в атрибуті `value`. Натомість його ім‘я показується із `C:\fakepath\` на початку. Цей виверт має певні історичні підстави, але він підтримується у всіх сучасних браузерах і фактично є [визначеним специфікацією (англ.)](https://html.spec.whatwg.org/multipage/forms.html#fakepath-srsly). + +## Приклади + +У цьому прикладі представлений дещо ускладнений вибір файлу, що користується інформацією про файл, доступною у властивості `HTMLInputElement.files`, а також демонструє кілька кмітливих фокусів. + +> **Примітка:** Повний вихідний код цього прикладу доступний на GitHub: [file-example.html](https://github.com/mdn/learning-area/blob/main/html/forms/file-examples/file-example.html) ([дивіться також у дії](https://mdn.github.io/learning-area/html/forms/file-examples/file-example.html)). Пояснювати CSS не будемо, JavaScript є головною темою. + +Перш за все, погляньмо на HTML: + +```html +
+
+ + +
+
+

Наразі жодні файли не вибрані для завантаження

+
+
+ +
+
+``` + +```css hidden +html { + font-family: sans-serif; +} + +form { + width: 580px; + background: #ccc; + margin: 0 auto; + padding: 20px; + border: 1px solid black; +} + +form ol { + padding-left: 0; +} + +form li, +div > p { + background: #eee; + display: flex; + justify-content: space-between; + margin-bottom: 10px; + list-style-type: none; + border: 1px solid black; +} + +form img { + height: 64px; + order: 1; +} + +form p { + line-height: 32px; + padding-left: 10px; +} + +form label, +form button { + background-color: #7f9ccb; + padding: 5px 10px; + border-radius: 5px; + border: 1px ridge black; + font-size: 0.8rem; + height: auto; +} + +form label:hover, +form button:hover { + background-color: #2d5ba3; + color: white; +} + +form label:active, +form button:active { + background-color: #0d3f8f; + color: white; +} +``` + +Це подібно до того, що ми вже бачили вище, – нічого додати. + +Далі перегляньмо JavaScript. + +У перших рядках сценарію отримуються посилання на саме поле форми, а також елемент {{htmlelement("div")}} із класом `.preview`. Далі – приховується елемент {{htmlelement("input")}}: це необхідно, тому що файлові поля мають тенденцію до потворності, складності в оформленні та неодноманітності в дизайні між різними браузерами. Елемент `input` можна активувати, клацнувши його {{htmlelement("label")}}, тож краще візуально приховати `input` і оформити `label` як кнопку, щоб користувач знав, що для завантаження файлів взаємодіяти треба із `label`. + +```js +const input = document.querySelector('input'); +const preview = document.querySelector('.preview'); + +input.style.opacity = 0; +``` + +> **Примітка:** Для приховування файлового поля використовується {{cssxref("opacity")}}, а не {{cssxref("visibility", "visibility: hidden")}} чи {{cssxref("display", "display: none")}}, тому що допоміжні технології інтерпретують два останні стилі так, ніби файлове поле не є інтерактивним. + +Далі – до поля додається [слухач подій](/uk/docs/Web/API/EventTarget/addEventListener), щоб відстежувати зміни його значення (у цьому випадку це відповідає вибору файлів). Слухач подій викликає самописну функцію `updateImageDisplay()`. + +```js +input.addEventListener('change', updateImageDisplay); +``` + +Кожного виклику функції `updateImageDisplay()`: + +- Для очищення попереднього вмісту `
` із попереднім виглядом використовується цикл {{jsxref("Statements/while", "while")}}. +- Витягується об‘єкт {{domxref("FileList")}}, що містить інформацію про всі вибрані файли, та зберігається у змінній, названій `curFiles`. +- За допомогою порівняння `curFiles.length` із 0 виконується перевірка, чи не було вибрано 0 (нуль) файлів. Якщо є рівність, то в `
` попереднього вигляду виводиться повідомлення про те, що жодні файли не були вибрані. +- Якщо файли _були_ вибрані, то відбувається обхід кожного з них, – із виводом інформації про них у `
` попереднього вигляду. Слід зауважити, що: +- Для перевірки, чи належить файл до коректного типу (наприклад, типів зображень, зазначених в атрибуті `accept`), використовується самописна функція `validFileType()`. +- Якщо він справді належить до коректного типу, то: + + - Його ім‘я та розмір (отримані з `file.name` і `file.size`) виводяться в елемент списку всередині попереднього `
`. Самописна функція `returnFileSize()` повертає приємно відформатовану версію розміру, в байтах, кілобайтах, мегабайтах (усталено браузер звітує про розмір в абсолютних байтах). + - Шляхом виклику {{domxref("URL.createObjectURL", "URL.createObjectURL(curFiles[i])")}}генерується ескіз зображення. Потім – за допомогою створення нового {{htmlelement("img")}} і присвоєння його атрибутові {{htmlattrxref("src", "img")}} ескізу – зображення вставляється в елемент списку. + +- Якщо тип файлу є недійсним, то всередині елемента списку виводиться повідомлення, що сповіщає користувача про необхідність вибрати файл іншого типу. + +```js +function updateImageDisplay() { + while (preview.firstChild) { + preview.removeChild(preview.firstChild); + } + + const curFiles = input.files; + if (curFiles.length === 0) { + const para = document.createElement('p'); + para.textContent = 'Наразі жодні файли не вибрані для завантаження'; + preview.appendChild(para); + } else { + const list = document.createElement('ol'); + preview.appendChild(list); + + for (const file of curFiles) { + const listItem = document.createElement('li'); + const para = document.createElement('p'); + if (validFileType(file)) { + para.textContent = `Ім‘я файлу – ${ + file.name + }, розмір файлу – ${returnFileSize(file.size)}.`; + const image = document.createElement('img'); + image.src = URL.createObjectURL(file); + + listItem.appendChild(image); + listItem.appendChild(para); + } else { + para.textContent = `Ім‘я файлу – ${file.name}: недійсний тип файлу. Оновіть свій вибір.`; + listItem.appendChild(para); + } + + list.appendChild(listItem); + } + } +} +``` + +Самописна функція `validFileType()` приймає як параметр об‘єкт {{domxref("File")}}, а потім використовує {{jsxref("Array.prototype.includes()")}}, щоб перевірити, чи відповідає будь-яке з `fileTypes` значення властивості файлу `type`. Якщо відповідність знайдена, то функція повертає `true`. Якщо не знайдена – `false`. + +```js +// https://webdoky.org/uk/docs/Web/Media/Formats/Image_types +const fileTypes = [ + 'image/apng', + 'image/bmp', + 'image/gif', + 'image/jpeg', + 'image/pjpeg', + 'image/png', + 'image/svg+xml', + 'image/tiff', + 'image/webp', + 'image/x-icon', +]; + +function validFileType(file) { + return fileTypes.includes(file.type); +} +``` + +Функція `returnFileSize()` приймає число (байтів, отримане з властивості `size` відповідного файлу) і перетворює його на приємно відформатований розмір у байтах, кілобайтах, мегабайтах. + +```js +function returnFileSize(number) { + if (number < 1024) { + return number + 'bytes'; + } else if (number >= 1024 && number < 1048576) { + return (number / 1024).toFixed(1) + 'KB'; + } else if (number >= 1048576) { + return (number / 1048576).toFixed(1) + 'MB'; + } +} +``` + +Приклад має наступний вигляд; пограйтеся: + +{{EmbedLiveSample('pryklady', '100%', 200)}} + +## Специфікації + +{{Specifications}} + +## Сумісність із браузерами + +{{Compat}} + +## Дивіться також + +- [Використання файлів у вебзастосунках](/uk/docs/Web/API/File_API/Using_files_from_web_applications) — містить низку інших корисних прикладів, що стосуються `` і [File API](/uk/docs/Web/API/File). +- [Сумісність властивостей CSS](/uk/docs/Learn/Forms/Property_compatibility_table_for_form_controls)