Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

some fix of File and FileList interface #30720

Merged
merged 10 commits into from
Dec 2, 2023
19 changes: 12 additions & 7 deletions files/en-us/web/api/file/file/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,37 +6,42 @@ page-type: web-api-constructor
browser-compat: api.File.File
---

{{APIRef("File")}}
{{APIRef("File API")}}{{AvailableInWorkers}}

The **`File()`** constructor creates a new {{domxref("File")}}
object instance.

## Syntax

```js-nolint
new File(bits, name)
new File(bits, name, options)
new File(fileBits, fileName)
new File(fileBits, fileName, options)
```

### Parameters

- `bits`
- `fileBits`
- : An [iterable](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol)
object such as an {{jsxref("Array")}}, having {{jsxref("ArrayBuffer")}}s,
{{jsxref("TypedArray")}}s, {{jsxref("DataView")}}s, {{domxref("Blob")}}s, strings,
or a mix of any of such elements, that will be put inside the {{domxref("File")}}.
Note that strings here are encoded as UTF-8, unlike the usual JavaScript UTF-16 strings.
- `name`
- `fileName`
- : A string representing the file name or the path to the file.
- `options` {{optional_inline}}

- : An options object containing optional attributes for the file. Available options are
as follows:

- `type`
- `type` {{optional_inline}}
- : A string representing the MIME type of the
content that will be put into the file. Defaults to a value of `""`.
- `lastModified`
- `endings` {{optional_inline}}
- : How to interpret newline characters (`\n`) within the contents, if
the data is text. The default value, `transparent`, copies newline
characters into the blob without changing them. To convert newlines to the host
system's native convention, specify the value `native`.
- `lastModified` {{optional_inline}}
- : A number representing the number of milliseconds
between the Unix time epoch and when the file was last modified. Defaults to a
value of {{jsxref("Date.now()")}}.
Expand Down
22 changes: 4 additions & 18 deletions files/en-us/web/api/file/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ page-type: web-api-interface
browser-compat: api.File
---

{{APIRef("File API")}}
{{APIRef("File API")}}{{AvailableInWorkers}}

The **`File`** interface provides information about files and allows JavaScript in a web page to access their content.

Expand All @@ -24,6 +24,8 @@ See [Using files from web applications](/en-US/docs/Web/API/File_API/Using_files

## Instance properties

_The `File` interface also inherits properties from the {{DOMxRef("Blob")}} interface._

- {{DOMxRef("File.lastModified")}} {{ReadOnlyInline}}
- : Returns the last modified time of the file, in millisecond since the UNIX epoch (January 1st, 1970 at Midnight).
- {{DOMxRef("File.lastModifiedDate")}} {{Deprecated_Inline}} {{ReadOnlyInline}} {{Non-standard_Inline}}
Expand All @@ -33,25 +35,9 @@ See [Using files from web applications](/en-US/docs/Web/API/File_API/Using_files
- {{DOMxRef("File.webkitRelativePath")}} {{ReadOnlyInline}}
- : Returns the path the URL of the {{DOMxRef("File")}} is relative to.

`File` implements {{DOMxRef("Blob")}}, so it also has the following properties available to it:

- {{DOMxRef("Blob.size")}} {{ReadOnlyInline}}
- : Returns the size of the file in bytes.
- {{DOMxRef("Blob.type")}} {{ReadOnlyInline}}
- : Returns the [MIME](/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) type of the file.

## Instance methods

_The `File` interface doesn't define any methods, but inherits methods from the {{DOMxRef("Blob")}} interface:_

- {{DOMxRef("Blob.slice()")}}
- : Returns a new `Blob` object containing the data in the specified range of bytes of the source `Blob`.
- {{DOMxRef("Blob.stream()")}}
- : Transforms the `File` into a {{DOMxRef("ReadableStream")}} that can be used to read the `File` contents.
- {{DOMxRef("Blob.text()")}}
- : Transforms the `File` into a stream and reads it to completion. It returns a promise that resolves with a string (text).
- {{DOMxRef("Blob.arrayBuffer()")}}
- : Transforms the `File` into a stream and reads it to completion. It returns a promise that resolves with an {{jsxref("ArrayBuffer")}}.
_The `File` interface also inherits methods from the {{DOMxRef("Blob")}} interface._

## Specifications

Expand Down
6 changes: 3 additions & 3 deletions files/en-us/web/api/file/lastmodified/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ page-type: web-api-instance-property
browser-compat: api.File.lastModified
---

{{APIRef("File")}}
{{APIRef("File API")}}{{AvailableInWorkers}}

The **`File.lastModified`** read-only property provides the
The **`lastModified`** read-only property of the {{domxref("File")}} interface provides the
last modified date of the file as the number of milliseconds since the Unix
epoch (January 1, 1970 at midnight). Files without a known last modified date return the
current date.
Expand Down Expand Up @@ -80,7 +80,7 @@ console.log(fileWithoutDate.lastModified); // returns current time

## Reduced time precision

To offer protection against timing attacks and [fingerprinting](/en-US/docs/Glossary/Fingerprinting), the precision of
To offer protection against timing attacks and {{glossary("fingerprinting")}}, the precision of
`someFile.lastModified` might get rounded depending on browser settings.
In Firefox, the `privacy.reduceTimerPrecision` preference is enabled by
default and defaults to 20us in Firefox 59; in 60 it will be 2ms.
Expand Down
6 changes: 3 additions & 3 deletions files/en-us/web/api/file/lastmodifieddate/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ status:
browser-compat: api.File.lastModifiedDate
---

{{APIRef("File API")}}{{Deprecated_Header}}{{Non-standard_Header}}
{{APIRef("File API")}}{{AvailableInWorkers}}{{Deprecated_Header}}{{Non-standard_Header}}

The **`File.lastModifiedDate`** read-only property returns the last modified date of the file. Files without a known last modified date return the current date.
The **`lastModifiedDate`** read-only property of the {{domxref("File")}} interface returns the last modified date of the file. Files without a known last modified date return the current date.

## Value

Expand All @@ -32,7 +32,7 @@ for (const file of fileInput.files) {

## Reduced time precision

To offer protection against timing attacks and [fingerprinting](/en-US/docs/Glossary/Fingerprinting), the precision of `someFile.lastModifiedDate.getTime()` might get rounded depending on browser settings.
To offer protection against timing attacks and {{glossary("fingerprinting")}}, the precision of `someFile.lastModifiedDate.getTime()` might get rounded depending on browser settings.

In Firefox, the `privacy.reduceTimerPrecision` preference is enabled by default and defaults to 20us in Firefox 59; in 60 it will be 2ms.

Expand Down
4 changes: 2 additions & 2 deletions files/en-us/web/api/file/name/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ page-type: web-api-instance-property
browser-compat: api.File.name
---

{{APIRef("File API")}}
{{APIRef("File API")}}{{AvailableInWorkers}}

Returns the name of the file represented by a {{domxref("File")}} object. For security
The **`name`** read-only property of the {{domxref("File")}} interface returns the name of the file represented by a {{domxref("File")}} object. For security
reasons, the path is excluded from this property.

## Value
Expand Down
4 changes: 2 additions & 2 deletions files/en-us/web/api/file/webkitrelativepath/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ page-type: web-api-instance-property
browser-compat: api.File.webkitRelativePath
---

{{APIRef("File API")}}
{{APIRef("File API")}}{{AvailableInWorkers}}

The **`File.webkitRelativePath`** is a read-only property that
The **`webkitRelativePath`** read-only property of the {{domxref("File")}} interface
contains a string which specifies the file's path relative to the
directory selected by the user in an {{HTMLElement("input")}} element with its
[`webkitdirectory`](/en-US/docs/Web/HTML/Element/input#webkitdirectory) attribute set.
Expand Down
14 changes: 7 additions & 7 deletions files/en-us/web/api/filelist/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,17 @@ page-type: web-api-interface
browser-compat: api.FileList
---

{{APIRef("File API")}}
{{APIRef("File API")}}{{AvailableInWorkers}}

An object of this type is returned by the `files` property of the HTML {{HTMLElement("input")}} element; this lets you access the list of files selected with the `<input type="file">` element. It's also used for a list of files dropped into web content when using the drag and drop API; see the [`DataTransfer`](/en-US/docs/Web/API/DataTransfer) object for details on this usage.
The **`FileList`** interface represents an object of this type returned by the `files` property of the HTML {{HTMLElement("input")}} element; this lets you access the list of files selected with the `<input type="file">` element. It's also used for a list of files dropped into web content when using the drag and drop API; see the {{domxref("DataTransfer")}} object for details on this usage.

All `<input>` element nodes have a `files` attribute of type `FileList` on them which allows access to the items in this list. For example, if the HTML includes the following file input:

```html
<input id="fileItem" type="file" />
```

The following line of code fetches the first file in the node's file list as a [`File`](/en-US/docs/Web/API/File) object:
The following line of code fetches the first file in the node's file list as a {{domxref("File")}} object:

```js
const file = document.getElementById("fileItem").files[0];
Expand All @@ -25,12 +25,12 @@ const file = document.getElementById("fileItem").files[0];

## Instance properties

- {{DOMxRef("FileList/length", "length")}} {{ReadOnlyInline}}
- {{DOMxRef("FileList.length", "length")}} {{ReadOnlyInline}}
- : A read-only value indicating the number of files in the list.

## Instance methods

- {{DOMxRef("FileList/item", "item()")}} {{ReadOnlyInline}}
- {{DOMxRef("FileList.item()", "item()")}}
- : Returns a {{domxref("File")}} object representing the file at the specified index in the file list.

## Example
Expand Down Expand Up @@ -84,5 +84,5 @@ fileInput.addEventListener("change", () => {
## See also

- [Using files from web applications](/en-US/docs/Web/API/File_API/Using_files_from_web_applications)
- [`File`](/en-US/docs/Web/API/File)
- [`FileReader`](/en-US/docs/Web/API/FileReader)
- {{domxref("File")}}
- {{domxref("FileReader")}}
6 changes: 3 additions & 3 deletions files/en-us/web/api/filelist/item/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ page-type: web-api-instance-method
browser-compat: api.FileList.item
---

{{APIRef("File API")}}
{{APIRef("File API")}}{{AvailableInWorkers}}

The **`item()`** method of the {{domxref("FileList")}} API returns a {{domxref("File")}} object representing the file at the specified index in the file list.
The **`item()`** method of the {{domxref("FileList")}} interface returns a {{domxref("File")}} object representing the file at the specified index in the file list.

## Syntax

Expand All @@ -23,7 +23,7 @@ item(index)

### Return value

A [`File`](/en-US/docs/Web/API/File) object representing the requested file.
A {{domxref("File")}} object representing the requested file.

## Examples

Expand Down
4 changes: 2 additions & 2 deletions files/en-us/web/api/filelist/length/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ page-type: web-api-instance-property
browser-compat: api.FileList.length
---

{{APIRef("File API")}}
{{APIRef("File API")}}{{AvailableInWorkers}}

The read-only {{domxref("FileList")}} **`length`** property returns the number of files in the `FileList`.
The **`length`** read-only property of the {{domxref("FileList")}} interface returns the number of files in the `FileList`.

## Value

Expand Down