diff --git a/4-binary/04-file/article.md b/4-binary/04-file/article.md index 964cdd44f..20878b650 100644 --- a/4-binary/04-file/article.md +++ b/4-binary/04-file/article.md @@ -1,6 +1,6 @@ # File and FileReader -A [File](https://www.w3.org/TR/FileAPI/#dfn-file) object inhereits from `Blob`, but is extended with filesystem-related capabilities. +A [File](https://www.w3.org/TR/FileAPI/#dfn-file) object inherits from `Blob` and is extended with filesystem-related capabilities. There are two ways to obtain it. @@ -10,14 +10,18 @@ First, there's a constructor, similar to `Blob`: new File(fileParts, fileName, [options]) ``` -- **`fileParts`** -- is an array of Blob/BufferSource/String value, same as `Blob`. +- **`fileParts`** -- is an array of Blob/BufferSource/String values. - **`fileName`** -- file name string. - **`options`** -- optional object: - - **`lastModified`** -- a timestamp (integer date) of last modification. + - **`lastModified`** -- the timestamp (integer date) of last modification. -Second, more often we get a file from `` or drag'n'drop or other browser interfaces. Then the file gets these from OS. +Second, more often we get a file from `` or drag'n'drop or other browser interfaces. In that case, the file gets this information from OS. -For instance: +As `File` inherits from `Blob`, `File` objects have the same properties, plus: +- `name` -- the file name, +- `lastModified` -- the timestamp of last modification. + +That's how we can get a `File` object from ``: ```html run @@ -38,9 +42,9 @@ The input may select multiple files, so `input.files` is an array-like object wi ## FileReader -[FileReader](https://www.w3.org/TR/FileAPI/#dfn-filereader) is an object with the sole purpose of reading from `Blob` (and hence `File` too) objects. +[FileReader](https://www.w3.org/TR/FileAPI/#dfn-filereader) is an object with the sole purpose of reading data from `Blob` (and hence `File` too) objects. -It's event based, as reading from disk may take time. +It delivers the data using events, as reading from disk may take time. The constructor: @@ -50,9 +54,9 @@ let reader = new FileReader(); // no arguments The main methods: -- **`readAsArrayBuffer(blob)`** -- read the data as `ArrayBuffer` -- **`readAsText(blob, [encoding])`** -- read the data as a string (encoding is `utf-8` by default) -- **`readAsDataURL(blob)`** -- encode the data as base64 data url. +- **`readAsArrayBuffer(blob)`** -- read the data in binary format `ArrayBuffer`. +- **`readAsText(blob, [encoding])`** -- read the data as a text string with the given encoding (`utf-8` by default). +- **`readAsDataURL(blob)`** -- read the binary data and encode it as base64 data url. - **`abort()`** -- cancel the operation. The choice of `read*` method depends on which format we prefer, how we're going to use the data. @@ -66,7 +70,7 @@ As the reading proceeds, there are events: - `progress` -- occurs during reading. - `load` -- no errors, reading complete. - `abort` -- `abort()` called. -- `error` -- error has occured. +- `error` -- error has occurred. - `loadend` -- reading finished with either success or failure. When the reading is finished, we can access the result as: @@ -101,28 +105,28 @@ function readFile(input) { ``` ```smart header="`FileReader` for blobs" -As mentioned in the chapter , `FileReader` works for any blobs, not just files. +As mentioned in the chapter , `FileReader` can read not just files, but any blobs. -So we can use it to convert a blob to another format: +We can use it to convert a blob to another format: - `readAsArrayBuffer(blob)` -- to `ArrayBuffer`, - `readAsText(blob, [encoding])` -- to string (an alternative to `TextDecoder`), - `readAsDataURL(blob)` -- to base64 data url. ``` -```smart header="`FileReaderSync` is available for workers only" +```smart header="`FileReaderSync` is available inside Web Workers" For Web Workers, there also exists a synchronous variant of `FileReader`, called [FileReaderSync](https://www.w3.org/TR/FileAPI/#FileReaderSync). Its reading methods `read*` do not generate events, but rather return a result, as regular functions do. -That's only inside a Web Worker though, because delays and hang-ups in Web Workers are less important, they do not affect the page. +That's only inside a Web Worker though, because delays in synchronous calls, that are possible while reading from files, in Web Workers are less important. They do not affect the page. ``` ## Summary -`File` object inherit from `Blob`. +`File` objects inherit from `Blob`. -In addition to `Blob` methods and properties, `File` objects also have `fileName` and `lastModified` properties, plus the internal ability to read from filesystem. We usually get `File` objects from user input, like `` or drag'n'drop. +In addition to `Blob` methods and properties, `File` objects also have `name` and `lastModified` properties, plus the internal ability to read from filesystem. We usually get `File` objects from user input, like `` or Drag'n'Drop events (`ondragend`). `FileReader` objects can read from a file or a blob, in one of three formats: - String (`readAsText`). @@ -131,4 +135,4 @@ In addition to `Blob` methods and properties, `File` objects also have `fileName In many cases though, we don't have to read the file contents. Just as we did with blobs, we can create a short url with `URL.createObjectURL(file)` and assign it to `` or ``. This way the file can be downloaded or shown up as an image, as a part of canvas etc. -And if we're going to send a `File` over a network, that's also easy, as network API like `XMLHttpRequest` or `fetch` natively accepts `File` objects. +And if we're going to send a `File` over a network, that's also easy: network API like `XMLHttpRequest` or `fetch` natively accepts `File` objects.