Storage Access API - Интерфейсы веб API

Storage Access API
==================

The Storage Access API provides a way for embedded, cross-origin content to gain unrestricted access to storage that it would normally only have access to in a first-party context (we refer to this as an origin's *first-party* storage). The API provides methods that allow embedded resources to check whether they currently have access to their first-party storage, and to request access to their first-party storage from the user agent.

Концепции и использование
-------------------------

Most browsers implement a number of storage access policies that restrict access to cookies and site data for embedded, cross-origin resources. These restrictions range from giving embedded resources under each top-level origin a unique storage space to outright blocking of storage access when resources are loaded in a third-party context.

The semantics around third-party cookie blocking policies in particular differ from browser to browser, but the core functionality is similar: cross-origin resources embedded in a third-party context are not given access to the same cookies and site storage that they would have access to when loaded in a first-party context.

These cookie blocking policies are known to break embedded cross-origin content that requires access to its first-party storage. As an example, federated logins often require access to authentication cookies stored in first-party storage, and will require the user to sign in on each site separately (or completely break) if those cookies are not available. In the case of breakage, site owners have often encouraged users to add their site as an exception or to disable the policy entirely. As a consequence, users who wish to continue to interact with embedded content are forced to greatly relax their blocking policy for resources loaded from all embedded origins and possibly across all websites.

The Storage Access API is intended to solve this problem; embedded cross-origin content can request unrestricted access to its first-party storage on a site-by-site basis via the `Document.requestStorageAccess()` (en-US) method, and check whether it already has access via the `Document.hasStorageAccess()` (en-US) method.

In addition, sandboxed `<iframe>` (en-US)s cannot be granted storage access by default for security reasons. The API therefore also adds the `allow-storage-access-by-user-activation` sandbox token (en-US). The embedding website needs to add this to allow storage access requests to be successful, along with `allow-scripts` and `allow-same-origin` to allow it to call the API, and execute in an origin that can have cookies:

```html
<iframe
 sandbox="allow-storage-access-by-user-activation
 allow-scripts
 allow-same-origin">
  ...
</iframe>
```

The API is designed to limit the potential storage exceptions to origins for which the user has shown an intent to interact. This is enforced through the following constraints:

* Access requests are automatically denied unless the embedded content is currently processing a user gesture such as a tap or click. This also prevents embedded content on the page from spamming the browser or user with excessive access requests.
* Origins that have never been interacted with as a first party do not have a notion of first-party storage. From the user's perspective, they only have a third-party relationship with that origin. Access requests are automatically denied if the browser detects that the user hasn't interacted with the embedded content in a first-party context recently (in Firefox, "recently" is "within 30 days").

The browser may decide to involve the user in the decision of whether to grant an incoming storage access request. Specifics regarding the lifetime of a storage grant and the circumstances under which the browser may decide to inform the user are currently being worked through and will be announced once ready.

Подсказки для пользователя
--------------------------

When `requestStorageAccess()` is called by an embedded, cross-origin document, the user agent may choose to involve the user in the decision of whether to grant storage access to the requesting origin. Prompting heuristics currently vary across the two implementers of the Storage Access API — Safari shows prompts for all embedded tracking content that has not previously received storage access, while Firefox only prompts users after a tracking origin has requested storage access on more than a threshold number of sites. See `Document.requestStorageAccess()` (en-US) for more details.

Отличия реализации в Safari
---------------------------

Although the API surface is the same, websites using the Storage Access API should expect differences in the level and extent of storage access they receive between Firefox and Safari. This is caused by differences in the storage access policies implemented in the two browsers. Design properties unique to Firefox are summarized here:

* If the embedded origin `tracker.example` has already obtained first-party storage access on the top-level origin `foo.example`, and the user visits a page from `foo.example` embedding a page from `tracker.example` again in less than 30 days, the embedded origin will have storage access immediately when loading.
* If a page from top-level origin `foo.example` embeds more than one `<iframe>` (en-US) from `tracker.example`, and one of those `<iframe>`s uses the Storage Access API in order to obtain storage access successfully, all other iframes from `tracker.example` on `foo.example` top-level origins will immediately gain storage access as well, without needing to call `requestStorageAccess()` separately.
* If an embedded page from `tracker.example` has previously successfully obtained storage access on top-level origin `foo.example`, all embedded subresources from `tracker.example` on `foo.example` (e.g. scripts, images, stylesheets, etc.) will load with access to their first-party storage, which means they may send Cookie headers and honor incoming `Set-Cookie` headers.
* In Firefox, when the promise returned from `requestStorageAccess()` is resolved, the embedded page will gain access to its entire first-party storage, not just cookies. This includes access to APIs such as Web Storage, IndexedDB, DOM Cache, and so on.
* In Firefox, the storage access grants are phased out after 30 calendar days passing, whereas in Safari the storage access grants are phased out after 30 days of browser usage passed without user interaction. This is currently a limitation of the Firefox implementation, which we may address in a future version. In Safari, successful use of the storage access API resets this counter.

Документация новой политики доступа к хранилищу Firefox по блокировки отслеживающих кук детально описана (en-US) в разделе предоставления доступа к хранилищу.

Методы Storage Access API
-------------------------

API методы реализованы в интерфейсе `Document`:

`Document.hasStorageAccess()` (en-US)

Returns a `Promise` that resolves with a boolean value indicating whether the document has access to its first-party storage.

`Document.requestStorageAccess()` (en-US)

Returns a `Promise` that resolves if the access to first-party storage was granted, and rejects if access was denied.

**Примечание:** User interaction propagates to the Promise returned by both of these methods, allowing the callers to take actions that require user interaction without requiring a second click from the user. For example, a caller could open a pop-up window from the resolved Promise without triggering Firefox's pop-up blocker.

Расширение <iframe> sandbox
---------------------------

`<iframe>` (en-US) `sandbox` появился новый признак, `allow-storage-access-by-user-activation`, который позволяет изолированному `<iframe>` использовать Storage Access API для запроса доступа к хранилищу.

Спецификации
------------

API на стадии обсуждения — стандартизация не начата. Сейчас вы можете ознакомиться с подробной спецификацией API в блоге Apple Introducing Storage Access API и WHATWG HTML issue 3338 — Proposal: Storage Access API.

Совместимость с браузерами
--------------------------

### api.Document.hasStorageAccess

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Document.requestStorageAccess

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Document.requestStorageAccessFor

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Permissions.permission\_storage-access

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

Использование Storage Access API (en-US)


Blob - Интерфейсы веб API

Blob
====

Объект `Blob` представляет из себя подобный файлу объект с неизменяемыми, необработанными данными; они могут читаться как текст или двоичные данные, либо могут быть преобразованы в `ReadableStream` (en-US), таким образом, его методы могут быть использованы для обработки данных.

Blob-ы могут представлять данные, которые не обязательно должны быть в родном для JavaScript формате. Интерфейс `File` основан на `Blob`, наследует функциональность `Blob` и расширяет его для поддержки файлов на стороне пользователя.

Использование Blob
------------------

Для создания `Blob` не из объектов и данных blob, используйте конструктор `Blob()` . Чтобы создать blob из подмножества данных из другого blob, используйте метод `slice()`. Чтобы получить объект `Blob` для файла на файловой системе пользователя, смотрите документацию на `File`.

API, принимающие объекты `Blob`, также перечислены в документации на `File`.

**Примечание:** Метод `slice()` имеет изначально задаваемую длину как второй аргумент, что используется для указания числа байт копируемых в новый `Blob.` Если указать такие параметры `start + length`, которые превышают размер исходного `Blob`, то возвращаемый `Blob` будет содержать данные от начального индекса (start index) до конца исходного `Blob.`

**Примечание:** Следует помнить ,что метод `slice()` имеет сторонние префиксы в некоторых браузерах: `blob.mozSlice()` для Firefox 12 и ранее, так же `blob.webkitSlice()` в Safari. Старая версия метода `slice()`, без сторонних приставок, имеет другой алгоритм и устарела. Поддержка `blob.mozSlice()` была убрана в Firefox 30.

Конструктор
-----------

`Blob(blobParts[, options])`

Возвращает создаваемый объект Blob, который содержит соединение всех данных в массиве, переданном в конструктор.

Свойства
--------

`Blob.isClosed` Только для чтения
Экспериментальная возможность

Логическое значение, показывающее, вызывался ли метод `Blob.close()` у blob. Закрытый blob не может быть прочитан.

`Blob.size` (en-US) Только для чтения

Размер данных, содержащихся в объекте `Blob`, в байтах.

`Blob.type` (en-US) Только для чтения

Строка с MIME-типом данных, содержащихся в `Blob`. Если тип неизвестен, строка пуста.

Методы
------

`Blob.close()`
Экспериментальная возможность

Закрывает Blob объект, по возможности освобождая занятые им ресурсы.

`Blob.slice([start[, end[, contentType]]])`

Возвращает новый `Blob` объект, содержащий данные в указанном диапазоне байтов исходного `Blob`.

`Blob.stream()` (en-US)

Возвращает `ReadableStream` (en-US), который может использоваться для чтения содержимого `Blob`.

`Blob.text()` (en-US)

Возвращает promise, который исполняется с `USVString` (en-US), содержащей всё содержимое `Blob`, интерпретируемое как текст UTF-8.

Примеры
-------

### Создание Blob

Конструктор `Blob() constructor` может создавать объекты blob из других объектов. Например, чтобы сконструировать blob из строки JSON:

```js
const obj = { hello: "world" };
const blob = new Blob([JSON.stringify(obj, null, 2)], {
  type: "application/json",
});
```

**Предупреждение:** До того как конструктор Blob стал доступен, это могло быть выполнено через устаревший API `BlobBuilder` (en-US):

```js
var builder = new BlobBuilder();
var fileParts = ['<a id="a"><b id="b">hey!</b></a>'];
builder.append(fileParts[0]);
var myBlob = builder.getBlob("text/xml");
```

### Создание URL для содержимого типизированного массива

Следующий код создаёт типизированный массив JavaScript и создаёт новый `Blob`, содержащий данные типизированного массива. Затем вызывается `URL.createObjectURL()` для преобразования blob в URL.

#### HTML

```html
<p>
  This example creates a typed array containing the ASCII codes for the space
  character through the letter Z, then converts it to an object URL. A link to
  open that object URL is created. Click the link to see the decoded object URL.
</p>
```

#### JavaScript

Основной частью этого кода для примера является функция `typedArrayToURL()`, которая создаёт `Blob` из переданного типизированного массива и возвращает объект URL для него. Преобразовав данные в URL объекта, их можно использовать несколькими способами, в том числе, в качестве значения атрибута `src` элементов `<img>` (конечно, при условии, что данные содержат изображение).

```js
function typedArrayToURL(typedArray, mimeType) {
  return URL.createObjectURL(new Blob([typedArray.buffer], { type: mimeType }));
}

const bytes = new Uint8Array(59);

for (let i = 0; i < 59; i++) {
  bytes[i] = 32 + i;
}

const url = typedArrayToURL(bytes, "text/plain");

const link = document.createElement("a");
link.href = url;
link.innerText = "Open the array URL";

document.body.appendChild(link);
```

### Другой пример

```js
var typedArray = GetTheTypedArraySomehow();
var blob = new Blob([typedArray], { type: "application/octet-binary" }); // pass a useful mime type here
var url = URL.createObjectURL(blob);
// url will be something like: blob:d3958f5c-0777-0845-9dcf-2cb28783acaf
// now you can use the url in any context that regular URLs can be used in, for example img.src, etc.
```

### Извлечение данных из Blob

Один из способов прочесть содержимое `Blob` – это использовать `FileReader`. Следующий код читает содержимое `Blob` как типизированный массив.

```js
var reader = new FileReader();
reader.addEventListener("loadend", function () {
  // reader.result contains the contents of blob as a typed array
});
reader.readAsArrayBuffer(blob);
```

Другой способ прочитать содержимое из `Blob` – это использовать `Response`. Следующий код читает содержимое `Blob` как текст:

```js
const text = await new Response(blob).text();
```

Или можно использовать `Blob.text()` (en-US):

```js
const text = await blob.text();
```

Используя другие методы `FileReader`, возможно прочесть содержимое объекта Blob как строку или как URL.

Спецификации
------------

| Specification |
| --- |
| File API # blob-section |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* `BlobBuilder` (en-US)
* `FileReader`
* `File`
* `URL.createObjectURL`
* Components.utils.importGlobalProperties
* Использование файлов в веб-приложениях


AbortSignal - Интерфейсы веб API

AbortSignal
===========

**Экспериментальная возможность:** **Это экспериментальная технология**
Так как спецификация этой технологии ещё не стабилизировалась, смотрите таблицу совместимости по поводу использования в различных браузерах. Также заметьте, что синтаксис и поведение экспериментальной технологии может измениться в будущих версиях браузеров, вслед за изменениями спецификации.

**`AbortSignal`** интерфейс представляет собой объект сигнала, который позволяет вам общаться с DOM запросом (например, Fetch) и прервать его при необходимости с помощью объекта `AbortController`.

Свойства
--------

*AbortSignal также наследует свойства от своего родительского интерфейса, `EventTarget`.*

`AbortSignal.aborted` Только для чтения

Это `Boolean` (en-US), который указывает, отменён ли запрос(ы), с которым связывался сигнал, отменён (`true`) или нет (`false`).

### Обработчики событий

`AbortSignal.onabort` (en-US)

Вызывается когда происходит событие `abort`, т.е. когда DOM запрос(ы), с которым связывался сигнал, отменён.

Методы
------

*AbortSignal наследует методы от родительского интерфейса, `EventTarget`.*

Примеры
-------

В следующем фрагменте мы будем загружать видео используя Fetch API.

Сначала мы создаём контроллер с помощью конструктора `AbortController()`, а затем получаем ссылку на связанный объект `AbortSignal` используя свойство `AbortController.signal`.

Когда fetch запрос инициируется, мы передаём `AbortSignal` в качестве опции внутрь объекта параметров запроса (см. `{signal}` ниже). Это связывает сигнал и контроллер с fetch запросом и позволяет нам прервать его, вызвав `AbortController.abort()`, как показано ниже во втором обработчике событий.

```js
var controller = new AbortController();
var signal = controller.signal;

var downloadBtn = document.querySelector('.download');
var abortBtn = document.querySelector('.abort');

downloadBtn.addEventListener('click', fetchVideo);

abortBtn.addEventListener('click', function() {
  controller.abort();
  console.log('Загрузка прервана');
});

function fetchVideo() {
  ...
  fetch(url, {signal}).then(function(response) {
    ...
  }).catch(function(e) {
    reports.textContent = 'Ошибка загрузки: ' + e.message;
  })
}
```

**Примечание:** Когда `abort()` вызывается, `fetch()` промис отклоняется с `AbortError`.

**Предупреждение:** Текущая версия Firefox отклоняет промис с `DOMException`

Вы можете найти полный рабочий пример на GitHub — см. abort-api (см. как он работает в живую).

Спецификации
------------

| Specification |
| --- |
| DOM Standard # interface-AbortSignal |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Fetch API
* Abortable Fetch by Jake Archibald


HTMLTrackElement - Интерфейсы веб API

HTMLTrackElement
================

**`HTMLTrackElement`**

Свойства
--------

*Наследует свойства своего родителя, `HTMLElement`.*

`HTMLTrackElement.kind`

Тип данных `DOMString`, так как отображает значение HTML-атрибута `kind`. Показывает, как будет использоваться текстовый трек. Возможные значения: `subtitles`, `captions`, `descriptions`, `chapters`, `metadata` (субтитры, подписи, описания, главы или метаданные).

`HTMLTrackElement.src` (en-US)

Тип данных `DOMString`, так как отображает значение HTML-атрибута `src`. Указывает адрес файла текстового трека.

`HTMLTrackElement.srclang`

Тип данных `DOMString`, так как отображает значение HTML-атрибута `srclang`. Указывает язык текстового трека.

`HTMLTrackElement.label`

Тип данных `DOMString` , так как отображает значение HTML-атрибута `label`. Определяет видимый пользователю заголовок трека.

`HTMLTrackElement.default`

Тип данных `Boolean` (en-US), отображает значение HTML-атрибута `default`. Указывает, что это текстовый трек по умолчанию, если пользовательские настройки не определят другой трек, как более уместный.

`HTMLTrackElement.readyState` Только для чтения

Возвращает значение типа `unsigned short`, которое показывает доступность трека для чтения:

| Константа | Значение | Описание |
| --- | --- | --- |
| `NONE` | 0 | Показывает, что метки текстового трека не получены. |
| `LOADING` | 1 | Показывает, что текстовый трек загружается, и пока не было обнаружено фатальных ошибок. Дополнительные метки могут быть добавлены в трек парсером. |
| `LOADED` | 2 | Указывает, что текстовая дорожка загружена без фатальных ошибок. |
| `ERROR` | 3 | Указывает, что текстовый трек был получен, но когда пользовательский агент попытался его использовать, произошла какая-то ошибка. Некоторые или все метки, вероятно, отсутствуют и не будут получены. |

`HTMLTrackElement.track` Только для чтения

Возвращает `TextTrack` (en-US) is the track element's text track data.

| `track` Только для чтения  | `TextTrack` (en-US) | The track element's text track data. |
| --- | --- | --- |

Методы
------

*Нет специфичных методов; наследует методы из родительского элемента, `HTMLElement`.*

Спецификации
------------

| Specification |
| --- |
| HTML Standard # htmltrackelement |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* The HTML element implementing this interface: `<track>`.


Pointer Lock API - Интерфейсы веб API

Pointer Lock API
================

**Pointer lock** **API**(прежнее название Mouse Lock API) обеспечивает методы ввода, основанные на движении мыши , а не только абсолютно позиционированых координатах курсора в окне. Это даёт вам доступ к необработанным движениям мыши, прикрепляет курсор мыши к любому элементу в окне браузера, предоставляет возможность вычислять координаты мыши не ограниченной областью окна проекции, и скрывает курсор из поля зрения. Это идеальное решение для 3D игр, например.

Более того, API полезно для любых приложений, которые используют данные мыши для управления движениями, вращения объектов и изменения записей. Например пользователь может управлять наклоном просто двигая мышь, не нажимая ни на какие кнопки. Сами кнопки освобождаются под другие задачи. Примерами могут послужить программы для просмотра карт или спутниковой съёмки.

Блокировка указателя позволяет вам получить доступ к данным мыши, даже если курсор ушёл за границы экрана или браузера. Например, ваши пользователи могут продолжать вращать или управлять 3D моделью движением мыши бесконечно. Без блокировки вращение или управление останавливается, как только курсор достигает края браузера или экрана. Геймеры теперь могут нажимать кнопки и водить курсором взад и вперёд, не боясь покинуть игровое поле и случайно переключится на другое приложение.

Основные концепции
------------------

Pointer lock is related to mouse capture. Mouse capture provides continued delivery of events to a target element while a mouse is being dragged, but it stops when the mouse button is released. Pointer lock is different from mouse capture in the following ways:

* It is persistent: Pointer lock does not release the mouse until an explicit API call is made or the user uses a specific release gesture.
* It is not limited by browser or screen boundaries.
* It continues to send events regardless of mouse button state.
* It hides the cursor.
Обзор методов/свойств
---------------------

Этот раздел содержит краткое описание каждого свойства и метода, связанного со спецификацией блокировки указателя.

### requestPointerLock()

The Pointer lock API, similar to the Fullscreen API (en-US), extends DOM elements by adding a new method, `requestPointerLock`, which is vendor-prefixed for now. You would currently declare it something like this, for example if you wanted to request pointer lock on a `canvas` element.:

```js
canvas.requestPointerLock =
  canvas.requestPointerLock ||
  canvas.mozRequestPointerLock ||
  canvas.webkitRequestPointerLock;

canvas.requestPointerLock();
```

### pointerLockElement and exitPointerLock()

The Pointer lock API also extends the `Document` interface, adding both a new property and a new method. The new property is used for accessing the currently locked element (if any), and is named `pointerLockElement` (en-US), which is vendor-prefixed for now. The new method on `Document` is `exitPointerLock` (en-US) and, as the name implies, it is used to exit Pointer lock.

The `pointerLockElement` (en-US) property is useful for determining if any element is currently pointer locked (e.g., for doing a boolean check) and also for obtaining a reference to the locked element, if any.

Here is an example of using `pointerLockElement`:

```js
if (
  document.pointerLockElement === canvas ||
  document.mozPointerLockElement === canvas ||
  document.webkitPointerLockElement === canvas
) {
  console.log("The pointer lock status is now locked");
} else {
  console.log("The pointer lock status is now unlocked");
}
```

The `Document.exitPointerLock` (en-US) method is used to exit pointer lock, and like `requestPointerLock`, works asynchronously using the `pointerlockchange (en-US)` and `pointerlockerror (en-US)` events, which you'll see more about below.

```js
document.exitPointerLock =
  document.exitPointerLock ||
  document.mozExitPointerLock ||
  document.webkitExitPointerLock;

// Attempt to unlock
document.exitPointerLock();
```

pointerlockchange event
-----------------------

When the Pointer lock state changes—for example, when calling `requestPointerLock`, `exitPointerLock` (en-US), the user pressing the ESC key, etc.—the `pointerlockchange (en-US)` event is dispatched to the `document`. This is a simple event and contains no extra data.

```js
if ("onpointerlockchange" in document) {
  document.addEventListener("pointerlockchange", lockChangeAlert, false);
} else if ("onmozpointerlockchange" in document) {
  document.addEventListener("mozpointerlockchange", lockChangeAlert, false);
} else if ("onwebkitpointerlockchange" in document) {
  document.addEventListener("webkitpointerlockchange", lockChangeAlert, false);
}

function lockChangeAlert() {
  if (
    document.pointerLockElement === canvas ||
    document.mozPointerLockElement === canvas ||
    document.webkitPointerLockElement === canvas
  ) {
    console.log("The pointer lock status is now locked");
    // Do something useful in response
  } else {
    console.log("The pointer lock status is now unlocked");
    // Do something useful in response
  }
}
```

pointerlockerror event
----------------------

When there is an error caused by calling `requestPointerLock` or `exitPointerLock` (en-US), the `pointerlockerror (en-US)` event is dispatched to the `document`. This is a simple event and contains no extra data.

```js
document.addEventListener("pointerlockerror", lockError, false);
document.addEventListener("mozpointerlockerror", lockError, false);
document.addEventListener("webkitpointerlockerror", lockError, false);

function lockError(e) {
  alert("Pointer lock failed");
}
```

**Примечание:** The above events are currently prefixed with `moz` in Firefox and `webkit` in Chrome.

Extensions to mouse events
--------------------------

The Pointer lock API extends the normal `MouseEvent` interface with movement attributes.

```webidl
partial interface MouseEvent {
    readonly attribute long movementX;
    readonly attribute long movementY;
};
```

**Примечание:** The movement attributes are currently prefixed as `.mozMovementX` and `.mozMovementY` in Firefox, and`.webkitMovementX` and `.webkitMovementY` in Chrome.

Two new parameters to mouse events—`movementX` (en-US) and `movementY` (en-US)—provide the change in mouse positions. The values of the parameters are the same as the difference between the values of `MouseEvent` properties, `screenX` and `screenY` (en-US), which are stored in two subsequent `mousemove (en-US)` events, `eNow` and `ePrevious`. In other words, the Pointer lock parameter `movementX = eNow.screenX - ePrevious.screenX`.

### Locked state

When Pointer lock is enabled, the standard `MouseEvent` properties `clientX`, `clientY`, `screenX`, and `screenY` (en-US) are held constant, as if the mouse is not moving. The `movementX` (en-US) and `movementY` (en-US) properties continue to provide the mouse's change in position. There is no limit to `movementX` (en-US) and `movementY` (en-US) values if the mouse is continuously moving in a single direction. The concept of the mouse cursor does not exist and the cursor cannot move off the window or be clamped by a screen edge.

### Unlocked state

The parameters `movementX` (en-US) and `movementY` (en-US) are valid regardless of the mouse lock state, and are available even when unlocked for convenience.

When the mouse is unlocked, the system cursor can exit and re-enter the browser window. If that happens, `movementX` (en-US) and `movementY` (en-US) could be set to zero.

Simple example walkthrough
--------------------------

We've written a simple pointer lock demo to show you how to use it to set up a simple control system (see source code). The demo looks like this:

![A red circle on top of a black background.](/ru/docs/Web/API/Pointer_Lock_API/pointer-lock.png)

This demo uses JavaScript to draw a ball on top of an `<canvas>` element. When you click the canvas, pointer lock is then used to remove the mouse pointer and allow you to move the ball directly using the mouse. Let's see how this works.

Set initial x and y positions on the canvas:

```js
var x = 50;
var y = 50;
```

The `canvasDraw()` function draws the ball in the current x and y positions, but it also includes `if()` statements to check whether the ball has gone off the edges of the canvas. If so, it makes the ball wrap around to the opposite edge.

```js
function canvasDraw() {
  if (x > canvas.clientWidth + 20) {
    x = 0;
  }

  if (y > canvas.clientHeight + 20) {
    y = 0;
  }

  if (x < -20) {
    x = canvas.clientWidth;
  }

  if (y < -20) {
    y = canvas.clientHeight;
  }

  ctx.fillStyle = "black";
  ctx.fillRect(0, 0, canvas.clientWidth, canvas.clientHeight);
  ctx.fillStyle = "#f00";

  ctx.beginPath();
  ctx.arc(x, y, 20, 0, degToRad(360), true);
  ctx.fill();
}
```

The pointer lock methods are currently prefixed, so next we'll fork them for the different browser implementations.

```js
canvas.requestPointerLock =
  canvas.requestPointerLock ||
  canvas.mozRequestPointerLock ||
  canvas.webkitRequestPointerLock;
// pointer lock object forking for cross browser

document.exitPointerLock =
  document.exitPointerLock ||
  document.mozExitPointerLock ||
  document.webkitExitPointerLock;
//document.exitPointerLock();
```

Now we set up an event listener to run the requestPointerLock() method on the canvas when it is clicked, which initiates pointer lock.

```js
canvas.onclick = function () {
  canvas.requestPointerLock();
};
```

Now for the dedicated pointer lock event listener: `pointerlockchange`. When this occurs, we run a function called `lockChangeAlert()` to handle the change.

```js
// pointer lock event listener

// Hook pointer lock state change events for different browsers
document.addEventListener("pointerlockchange", lockChangeAlert, false);
document.addEventListener("mozpointerlockchange", lockChangeAlert, false);
document.addEventListener("webkitpointerlockchange", lockChangeAlert, false);
```

This function checks the pointLockElement property to see if it is our canvas. If so, it attached an event listener to handle the mouse movements with the `canvasLoop()` function. If not, it removes the event listener again.

```js
function lockChangeAlert() {
  if (
    document.pointerLockElement === canvas ||
    document.mozPointerLockElement === canvas ||
    document.webkitPointerLockElement === canvas
  ) {
    console.log("The pointer lock status is now locked");
    document.addEventListener("mousemove", canvasLoop, false);
  } else {
    console.log("The pointer lock status is now unlocked");
    document.removeEventListener("mousemove", canvasLoop, false);
  }
}
```

A tracker is set up to write out the X and Y values to the screen, for reference.

```js
var tracker = document.createElement("p");
var body = document.querySelector("body");
body.appendChild(tracker);
tracker.style.position = "absolute";
tracker.style.top = "0";
tracker.style.right = "10px";
tracker.style.backgroundColor = "white";
```

The `canvasLoop()` function first forks the `movementX` and `movementY` properties, as they are also prefixed currently in some browsers. It then adds those property's values to x and y, and reruns `canvasDraw()` with those new values so the ball position is updated. Finally, we use `requestAnimationFrame()` to run the loop again and again.
```

function canvasLoop(e) {
  var movementX = e.movementX ||
      e.mozMovementX          ||
      e.webkitMovementX       ||
      0;

  var movementY = e.movementY ||
      e.mozMovementY      ||
      e.webkitMovementY   ||
      0;

  x += movementX;
  y += movementY;

  canvasDraw();

  var animation = requestAnimationFrame(canvasLoop);

  tracker.innerHTML = "X position: " + x + ', Y position: ' + y;
}
```

iframe limitations
------------------

Pointer lock can only lock one iframe at a time. If you lock one iframe, you cannot try to lock another iframe and transfer the target to it; Pointer lock will error out. To avoid this limitation, first unlock the locked iframe, and then lock the other.

While iframes work by default, "sandboxed" iframes block Pointer lock. The ability to avoid this limitation, in the form of the attribute/value combination `<iframe sandbox="allow-pointer-lock">`, is expected to appear in Chrome soon.

Specifications
--------------

| Specification |
| --- |
| Pointer Lock 2.0  |

Совместимость с браузерами
--------------------------

### api.Document.exitPointerLock

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.Element.requestPointerLock

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `MouseEvent`


HTMLImageElement - Интерфейсы веб API

HTMLImageElement
================

Интерфейс **`HTMLImageElement`** предоставляет специальные свойства и методы (расширяя обычный интерфейс `HTMLElement` ) для управления вёрсткой и отображением элемента `<img>`.

Свойства
--------

*Наследует свойства родителя, `HTMLElement`.*

| Имя | Тип | Описание |
| --- | --- | --- |
| `align` | `DOMString` | Указывает расположение картинки зависящее от окружающего контента. Возможные значения: `"left"`, `"right"`, `"justify"`, и `"center"`. |
| `alt` | `DOMString` | Повторяет атрибут HTML `alt` указывающий на запасной контекст картинки. |
| `border` | `DOMString` | Ширина рамки вокруг картинки. Устарело и вместо него следует использовать свойство CSS `border`. |
| `complete` Только для чтения  | `Boolean` (en-US) | Возвращает true, если браузер закончил загрузку картинки с ошибкой или успешно. Также возвращает true, когда не установлено значение `src` (en-US), во всех остальных случаях - false. |
| `crossOrigin` | `DOMString` | Является `DOMString`, с настройками CORS для этого элемента изображения. Дополнительная информация: Атрибуты настроек CORS (en-US). |
| `currentSrc`Только для чтения
Экспериментальная возможность
 | `DOMString` | Возвращает `DOMString` с URL-адресом текущего изображения (что может измениться, например, в ответ на запросы мультимедиа). |
| `height` | `unsigned long` | Отражает атрибут `height` HTML, указывая визуализированную высоту изображения в пикселях CSS. |
| `hspace` | `long` | Space to the left and right of the image. |
| `isMap` | `Boolean` (en-US) | Reflects the `ismap` HTML attribute, indicating that the image is part of a server-side image map. |
| `longDesc` | `DOMString` | URI of a long description of the image. |
| `lowSrc` | `DOMString` | A reference to a low-quality (but faster to load) copy of the image. |
| `name` | `DOMString` |  |
| `naturalHeight` Только для чтения  | `unsigned long` | Intrinsic height of the image in CSS pixels, if it is available; otherwise, `0`. |
| `naturalWidth` Только для чтения  | `unsigned long` | Intrinsic width of the image in CSS pixels, if it is available; otherwise, `0`. |
| `src` | `DOMString` | Reflects the `src` HTML attribute, containing the URL of the image. |
| `srcset`
Экспериментальная возможность
 |  |  |
| `useMap` | `DOMString` | Reflects the `usemap` HTML attribute, containing a partial URL of a map element. |
| `vspace` | `long` | Space above and below the image. |
| `width` | `unsigned long` | Reflects the `width` HTML attribute, indicating the rendered width of the image in CSS pixels. |
| `x` Только для чтения
Non-standard
 | `long` | The horizontal offset from the nearest layer. (Mimic an old Netscape 4 behavior) |
| `y` Только для чтения
Non-standard
 | `long` | The vertical offset from the nearest layer. (Mimic an old Netscape 4 behavior) |

Методы
------

*Наследует методы родителя, `HTMLElement`.*

`HTMLImageElement.Image()`

The `Image()` constructor, taking two optional `unsigned` `long`, the width and the height of the resource, creates an instance of `HTMLImageElement` not inserted in a DOM tree.

Пример
------

```js
var img1 = new Image(); // Конструктор HTML5
img1.src = "image1.png";
img1.alt = "alt";
document.body.appendChild(img1);

var img2 = document.createElement("img"); // Используем HTMLImageElement
img2.src = "image2.jpg";
img2.alt = "alt text";
document.body.appendChild(img2);

// выбираем первое изображение на странице
alert(document.images[0].src);
```

Спецификации
------------

| Specification |
| --- |
| HTML Standard # htmlimageelement |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Элемент HTML, реализующий этот интерфейс: `<img>`


File and Directory Entries API - Интерфейсы веб API

File and Directory Entries API
==============================

**Не стандартно:** Эта возможность не является стандартной и стандартизировать её пока никто не собирается. Не используйте её на сайтах, смотрящих во внешний мир: она будет работать не у всех пользователей. Также могут присутствовать большие несовместимости между реализациями и её поведение может в будущем измениться.

API доступа к файлам и директориям имитирует локальную файловую систему, в которой веб-приложения могут перемещаться и получать доступ к файлам. Вы можете разрабатывать приложения, которые читают, записывают и создают файлы и/или каталоги в виртуальной изолированной файловой системе.

**Примечание:** Поскольку это нестандартный API, спецификация которого в настоящее время не входит в стандарт, важно помнить, что не все браузеры реализуют его, а те, которые поддерживают, могут реализовывать только небольшие его части. Дополнительные сведения в разделе Browser compatibility

Существуют два очень похожих API в зависимости от того, хотите ли вы асинхронного или синхронного поведения. Синхронный API предназначен для использования внутри `Worker` и будет возвращать желаемые значения. Асинхронный API не будет блокировать выполнение кода, а API не будет возвращать значения; вместо этого вам нужно будет предоставить колбэк-функцию для обработки одного или нескольких ответов.

**Предупреждение:** Firefox реализация File System API очень ограничена: не поддерживается создание файлов. Доступ к файлам осуществляется только через `<input>` элемент (см. так же `HTMLInputElement` (en-US)) или путём перетаскивания файла/папки (drag and drop). Firefox также не реализует синхронный API. Внимательно проверьте совместимость браузера для любой части API, которую вы используете. ( см. Поддержка File System API в Firefox (en-US))

Получение доступа к файловой системе
------------------------------------

Есть два способа получить доступ к файловой системе, определённым в текущем проекте спецификации:

* При обработке события `drop (en-US)` вы можете вызвать `DataTransferItem.webkitGetAsEntry()` (en-US) что бы получить `FileSystemEntry` (en-US) для "брошенного" элемента. Если результат не `null`, то это брошенный файл или каталог, и вы можете использовать вызовы файловой системы для работы с ним.
* Свойство `HTMLInputElement.webkitEntries` (en-US) позволяет получить объект `FileSystemFileEntry` (en-US) для выбранного файла, но только если они перетаскиваются в средство выбора файлов ( баг 1326031 ). Если `HTMLInputElement.webkitdirectory` (en-US) является `true`, то `<input>` работает для выбора директорий, и вы можете получить объект `FileSystemDirectoryEntry` (en-US) для каждой выбранной директории.
Асинхронный API
---------------

Асинхронный API следует использовать для большинства операций, чтобы доступ к файловой системе не блокировал весь браузер, если он используется в основном потоке. Он включает в себя следующие интерфейсы:

`FileSystem` (en-US)

Представляет файловую систему.

`FileSystemEntry` (en-US)

Базовый интерфейс, представляющий одну запись в файловой системе. Это реализуется другими интерфейсами, которые представляют файлы или каталоги.

`FileSystemFileEntry` (en-US)

Представляет отдельный файл в файловой системе.

`FileSystemDirectoryEntry` (en-US)

Представляет отдельный каталог в файловой системе.

`FileSystemDirectoryReader` (en-US)

Созданный путём вызова `FileSystemDirectoryEntry.createReader()` (en-US), этот интерфейс предоставляет функции, которые позволяют вам читать содержимое каталога.

`FileSystemFlags` (en-US)

Определяет набор значений, которые используются при указании флагов опций при вызове определённых методов в File System API.

`FileError`

Представляет ошибку, которая возникает при вызовах асинхронной файловой системы.

Также есть две глобальные функции (которые в настоящее время не являются частью спецификации и реализуются только в Google Chrome). Они доступны внутри объекта `Window` и реализованы в `LocalFileSystem` (en-US): `requestFileSystem()` и `resolveLocalFileSystemURL()`.

Синхронный API
--------------

Синхронный API следует использовать только в `Worker`-ах; эти вызовы блокируются до тех пор, пока не закончат своё выполнение, и просто возвращают результаты вместо использования колбэков. Использование их в основном потоке заблокирует браузер, что непослушно. В противном случае интерфейсы ниже отражают интерфейсы асинхронного API.

`FileSystemSync` (en-US)

Представляет файловую систему.

`FileSystemEntrySync` (en-US)

Базовый интерфейс, представляющий одну запись в файловой системе. Это реализуется другими интерфейсами, которые представляют файлы или каталоги. `EntrySync`

`FileSystemFileEntrySync`

Представляет отдельный файл в файловой системе.

`FileSystemDirectoryEntrySync`

Представляет отдельный каталог в файловой системе.

`FileSystemDirectoryReaderSync`

Созданный путём вызова `FileSystemDirectoryEntrySync.createReader()`, этот интерфейс предоставляет функции, которые позволяют вам читать содержимое каталога.

`FileException` (en-US)

Представляет ошибку, которая возникает при вызовах синхронной файловой системы.

Также есть две глобальные функции (которые в настоящее время не являются частью спецификации и реализуются только в Google Chrome). Они доступны в объекте `Worker` и реализованы в`LocalFileSystemSync` (en-US): `requestFileSystemSync()` и `resolveLocalFileSystemSyncURL()`.

Другие интерфейсы
-----------------

`LocalFileSystem` (en-US)

Предоставляет вам доступ к изолированной файловой системе.

`LocalFileSystemSync` (en-US) `LockedFile` (en-US)

Предоставляет инструменты для работы с данным файлом со всеми необходимыми блокировками.

Спецификации
------------

| Specification |
| --- |
| File and Directory Entries API # api-domfilesystem |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Introduction to the File and Directory Entries API
* File and Directory Entries API support in Firefox (en-US)


HTMLDocument - Интерфейсы веб API

HTMLDocument
============

HTMLDocument - это абстрактный интерфейс DOM (en-US), который обеспечивает доступ к специальным свойствам и методам, не представленным по умолчанию в регулярном (XML) документе.

Его методы и свойства включены в страницу `document` и перечислены отдельно в их собственном разделе на вышеупомянутой связанной странице DOM.

Спецификация
------------

* http://www.w3.org/TR/DOM-Level-2-HTM...ml#ID-26809268


BatteryManager - Интерфейсы веб API

BatteryManager
==============

Интерфейс `BatteryManager` позволяет взаимодействовать с Battery Status API (en-US) и предоставляет доступ к информации об уровне заряда батареи устройства. Метод `navigator.getBattery()` возвращает промис, содержащий интерфейс `BatteryManager`.

EventTarget

BatteryManagerСвойства экземпляра
-------------------

`BatteryManager.charging` (en-US) Только для чтения

Значение с булевым типом, заряжается сейчас батарея или нет.

`BatteryManager.chargingTime` (en-US) Только для чтения

Число оставшихся секунд до полной зарядки, или 0, если устройство заряжено.

`BatteryManager.dischargingTime` (en-US) Только для чтения

Число оставшихся секунд до полной разрядки устройства.

`BatteryManager.level` (en-US) Только для чтения

Число между 0.0 и 1.0, показывающее уровень заряда батареи устройства.

Методы
------

*Наследует методы родительского интерфейса*: `EventTarget`.

События
-------

`chargingchange` (en-US)

Вызывается при обновлении состояния процесса зарядки батареи (свойство `charging` (en-US)).

`chargingtimechange` (en-US)

Вызывается при обновлении времени до полной зарядки батареи (свойство `chargingTime` (en-US)).

`dischargingtimechange` (en-US)

Вызывается при обновлении времени до разрядки батареи (свойство `dischargingTime` (en-US)).

`levelchange` (en-US)

Вызывается при обновление уровня заряда батареи (свойство `level` (en-US)).

Спецификации
------------

| Specification |
| --- |
| Battery Status API # the-batterymanager-interface |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Battery Status API (en-US)
* `navigator.getBattery`


Storage - Интерфейсы веб API

Storage
=======

`Интерфейс Storage` из Web Storage API предоставляет доступ для session storage или local storage для конкретного домена, позволяя вам к примеру добавлять, изменять или удалять сохранённые элементы данных.

Если вы хотите управлять session storage для домена, вы вызываете `Window.sessionStorage` метод; Если вы хотите управлять local storage домена, вы вызываете `Window.localStorage`.

Свойства
--------

`Storage.length` Только для чтения

Возвращает число, представляющее количество элементов в объекте `Storage`.

Методы
------

`Storage.key()`

Приняв число n, метод вернёт имя n-ного ключа в Storage

`Storage.getItem()`

Приняв имя ключа, метод вернёт для него значение.

`Storage.setItem()`

Приняв имя ключа и значение, метод добавит этот ключ в Storage или обновит его значение, если ключ уже существовал.

`Storage.removeItem()`

Приняв имя ключа, метод удалит этот ключ из Storage

`Storage.clear()`

При вызове метод удалит все ключи из Storage.

Примеры
-------

В данном примере мы получаем доступ к объекту Storage вызывая localStorage. Для начала мы проверяем содержит ли local storage элементы данных используя `!localStorage.getItem('bgcolor')`. Если да, мы вызываем функцию `setStyles()` которая получает элементы данных используя `localStorage.getItem()` и использует их значения для обновления стилей на странице. Если нет, мы вызывает другую функцию, `populateStorage()`, которая использует `localStorage.setItem()` что бы установить значения для элементов, потом вызываем `setStyles()`.

```js
if (!localStorage.getItem("bgcolor")) {
  populateStorage();
} else {
  setStyles();
}

function populateStorage() {
  localStorage.setItem("bgcolor", document.getElementById("bgcolor").value);
  localStorage.setItem("font", document.getElementById("font").value);
  localStorage.setItem("image", document.getElementById("image").value);

  setStyles();
}

function setStyles() {
  var currentColor = localStorage.getItem("bgcolor");
  var currentFont = localStorage.getItem("font");
  var currentImage = localStorage.getItem("image");

  document.getElementById("bgcolor").value = currentColor;
  document.getElementById("font").value = currentFont;
  document.getElementById("image").value = currentImage;

  htmlElem.style.backgroundColor = "#" + currentColor;
  pElem.style.fontFamily = currentFont;
  imgElem.setAttribute("src", currentImage);
}
```

**Примечание:** Если хотите увидеть данный пример в работе, посмотрите наше Web Storage Demo.

Спецификации
------------

| Specification |
| --- |
| HTML Standard # storage |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

Используя Web Storage API


SpeechSynthesisUtterance - Интерфейсы веб API

SpeechSynthesisUtterance
========================

**Экспериментальная возможность:** **Это экспериментальная технология**
Так как спецификация этой технологии ещё не стабилизировалась, смотрите таблицу совместимости по поводу использования в различных браузерах. Также заметьте, что синтаксис и поведение экспериментальной технологии может измениться в будущих версиях браузеров, вслед за изменениями спецификации.

The **`SpeechSynthesisUtterance`** interface of the Web Speech API represents a speech request. It contains the content the speech service should read and information about how to read it (e.g. language, pitch and volume.)

Конструктор
-----------

`SpeechSynthesisUtterance.SpeechSynthesisUtterance()` (en-US)

Возвращает новый экземпляр объекта `SpeechSynthesisUtterance`

Свойства
--------

*`SpeechSynthesisUtterance` ещё наследует свойства из его своего родительского интерфейса `EventTarget`.*

`SpeechSynthesisUtterance.lang` (en-US)

Получает и устанавливает язык высказывания.

`SpeechSynthesisUtterance.pitch` (en-US)

Получает и устанавливает высоту, на которой произносится высказывание

`SpeechSynthesisUtterance.rate` (en-US)

Получает и устанавливает скорость, с которой будет произноситься высказывание.

`SpeechSynthesisUtterance.text` (en-US)

Получает и устанавливает текст, который будет синтезироваться при произнесении высказывания.

`SpeechSynthesisUtterance.voice` (en-US)

Получает и устанавливает голос, который будет использоваться для произнесения речи.

`SpeechSynthesisUtterance.volume` (en-US)

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

### Обработчики событий

`SpeechSynthesisUtterance.onboundary` (en-US)

Срабатывает, когда произнесённое высказывание достигает границы слова или предложения.

`SpeechSynthesisUtterance.onend` (en-US)

Срабатывает, когда произнесение произнесено.

`SpeechSynthesisUtterance.onerror` (en-US)

Срабатывает, когда возникает ошибка, которая препятствует успешному произнесению высказывания.

`SpeechSynthesisUtterance.onmark` (en-US)

Срабатывает, когда произнесённое высказывание достигает названного тега метки «SSML».

`SpeechSynthesisUtterance.onpause` (en-US)

Срабатывает, когда высказывание приостановлено.

`SpeechSynthesisUtterance.onresume` (en-US)

Срабатывает, когда приостановленное высказывание возобновляется.

`SpeechSynthesisUtterance.onstart` (en-US)

Срабатывает, когда произнесение произнесено.

Examples
--------

В нашей базовой Демо-версия синтезатора речи, мы сначала получаем ссылку на контроллер SpeechSynthesis, используя `window.speechSynthesis`. После определения некоторых необходимых переменных мы получаем список доступных голосов, используя `SpeechSynthesis.getVoices()` (en-US), и заполнить меню выбора с ними, чтобы пользователь мог выбрать, какой голос он хочет.

Внутри обработчика `inputForm.onsubmit` мы останавливаем отправку формы с помощью preventDefault(), используйте `constructor` (en-US) для создания нового экземпляра высказывания, содержащего текст из текста `<input>`, установите `voice` (en-US)на голос, выбранный в элементе `<select>` и начните высказывание через `SpeechSynthesis.speak()` (en-US) метод.

```js
var synth = window.speechSynthesis;

var inputForm = document.querySelector("form");
var inputTxt = document.querySelector("input");
var voiceSelect = document.querySelector("select");

var voices = synth.getVoices();

for (i = 0; i < voices.length; i++) {
  var option = document.createElement("option");
  option.textContent = voices[i].name + " (" + voices[i].lang + ")";
  option.setAttribute("data-lang", voices[i].lang);
  option.setAttribute("data-name", voices[i].name);
  voiceSelect.appendChild(option);
}

inputForm.onsubmit = function (event) {
  event.preventDefault();

  var utterThis = new SpeechSynthesisUtterance(inputTxt.value);
  var selectedOption = voiceSelect.selectedOptions[0].getAttribute("data-name");
  for (i = 0; i < voices.length; i++) {
    if (voices[i].name === selectedOption) {
      utterThis.voice = voices[i];
    }
  }
  synth.speak(utterThis);
  inputTxt.blur();
};
```

Specifications
--------------

| Specification |
| --- |
| Web Speech API # speechsynthesisutterance |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Web Speech API


HTMLScriptElement - Интерфейсы веб API

HTMLScriptElement
=================

HTML-элементы `<script>` предоставляют **`HTMLScriptElement`** интерфейс, который предоставляет специальные свойства и методы для манипулирования поведением и выполнением `<script>` элементов (за пределами унаследованного `HTMLElement` интерфейса).

JavaScript файлы должны обслуживаться с `application/javascript` MIME type, но браузеры снисходительны и блокируют их только, если скрипты обслуживаются с типом изображение (`image/*`), типом видео (`video/*`), типом аудио (`audio/*`), или `text/csv`. Если скрипт заблокирован, его элемент получает событие `error (en-US)`; в противном случае, он получает событие `success (en-US)`.

Свойства
--------

*Наследует свойства от своего родителя, `HTMLElement`.*

| Имя | Тип | Описание |
| --- | --- | --- |
| `type` | `DOMString` |
 Представляет тип MIME сценария. Он отражает атрибут
 `type`.
  |
| `src` | `DOMString` |
 Получает и отдаёт URL внешнего скрипта. Он отражает атрибут
 `src`.
  |
| `event` | `DOMString` |
 Старый, способ регистрации обработчиков событий на элементы в
 HTML-документе.
  |
| `charset` | `DOMString` |
 Представляет кодировку символов внешнего скрипта. Он отражает атрибут
 `charset`.
  |
| `async` | `Boolean` (en-US) |
 Атрибуты `async` и `defer`
булевы (en-US)
 атрибуты, которые контролируют как скрипт должен выполняться.
 **Атрибуты `defer` и `async` не должны быть
указаны, если атрибут `src` отсутствует.**

Существует три возможных режима выполнения:1. Если атрибут `async` представлен, то скрипт будет
 выполняться асинхронно по мере загрузки.
2. Если атрибут `async` отсутствует, но представлен атрибут
 `defer`, то скрипт будет выполняться когда
 страница полностью загружена (en-US).
3. Если ни один атрибут не представлен, то скрипт извлекается и
 выполняется незамедлительно, блокируя дальнейший парсинг страницы.

 Атрибут `defer` может быть указан с атрибутом
 `async`, тогда устаревшие браузеры, которые поддерживают
 только `defer` (но не `async`) откатятся к
 поведению `defer` взамен дефолтного поведения блокировки.

**Примечание:** Точные детали обработки для этих
 атрибутов комплексны, включая множество различных аспектов HTML, и
 разбросаны по всей спецификации.
 Эти алгоритмы
 описывают основную идею, но они основаны на правилах синтаксического
 анализа для `<script>`
открывающих
 и
 закрывающих
 тэгах в HTML,
 во внешнем контенте, и вXML; правиле для метода
 `document.write()` (en-US); обработке
 сценариев; и так далее.
  |
| `defer` | `Boolean` (en-US) |
| `crossOrigin`
Экспериментальная возможность
 | `DOMString` | `DOMString`, отражающий
 настройку CORS для элементов скрипта. Для скриптов из других
 источников, он контролирует,
 будет ли раскрыта информация об ошибке.
  |
| `text` | `DOMString` |
 IDL атрибут `text` объединяет и возвращает содержимое всех
 `Text` нод (en-US) внутри
 элемента `<script>` (игнорируя другие ноды,
 такие как комментарии) в древовидном порядке. При установке, он
 действует также, как и IDL атрибут
 `textContent` (en-US).

**Примечание:** При вставке с использованием метода
 `document.write()` (en-US), элементы `<script>` выполняются (обычно
 синхронно), когда при вставке используются
 `innerHTML` (en-US)
 или
 `outerHTML` (en-US), они вообще не выполняются.
  |
| `noModule` | `Boolean` (en-US) |
 Это булево свойство выполняет остановку выполнения скрипта в браузере,
 поддерживающим
 ES2015 модули
 — используется для запуска резервных скриптов, которые не поддерживают
 JavaScript модули.
  |
| `referrerPolicy` | `DOMString` | `DOMString`, который отражает HTML атрибут
 `referrerpolicy`
 указывающий, какой реферер использовать при извлечении скриптов и
 выборках, выполненных сценариев.
  |

Методы
------

*Нет специальных методов; наследует методы от родителей, `HTMLElement`.*

Примеры
-------

### Динамическое импортирование скриптов

Давайте создадим функцию. которая импортирует новый скрипт в документ, создавая ноду `<script>` *непосредственно перед* `<script>`, в котором размещается следующий код (через `document.currentScript`). Эти скрипты будут выполняться **асинхронно**. Для получения подробной информации смотрите свойства `defer` и `async`.

```js
function loadError(oError) {
  throw new URIError(
    "The script " + oError.target.src + " didn't load correctly.",
  );
}

function prefixScript(url, onloadFunction) {
  var newScript = document.createElement("script");
  newScript.onerror = loadError;
  if (onloadFunction) {
    newScript.onload = onloadFunction;
  }
  document.currentScript.parentNode.insertBefore(
    newScript,
    document.currentScript,
  );
  newScript.src = url;
}
```

Следующая функция, вместо добавления новых скриптов непосредственно перед элементом `document.currentScript`, добавляет их как потомков тега `<head>`.

```js
function loadError(oError) {
  throw new URIError(
    "The script " + oError.target.src + " didn't load correctly.",
  );
}

function affixScriptToHead(url, onloadFunction) {
  var newScript = document.createElement("script");
  newScript.onerror = loadError;
  if (onloadFunction) {
    newScript.onload = onloadFunction;
  }
  document.head.appendChild(newScript);
  newScript.src = url;
}
```

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

```js
affixScriptToHead("myScript1.js");
affixScriptToHead("myScript2.js", function () {
  alert('The script "myScript2.js" has been correctly loaded.');
});
```

Спецификации
------------

| Specification |
| --- |
| HTML Standard # htmlscriptelement |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* HTML-элемент `<script>`
* HTML-элемент `<noscript>`
* `document.currentScript`
* Web Workers (фрагменты кода, похожие на скрипты, но выполняемые в другом глобальном контексте)
* Ryan Grove's <script> and <link> node event compatibility chart


HTMLLinkElement - Интерфейсы веб API

HTMLLinkElement
===============

Интерфейс **`HTMLLinkElement`** представляет справочную информацию для внешних ресурсов и отношение этих ресурсов к документу и наоборот (соответствует элементу `<link>`; не путать с `<a>`, который представлен элементом `HTMLAnchorElement`). Этот объект наследует все свойства и методы интерфейса `HTMLElement`.

Свойства
--------

*Наследует свойства от своего родителя, `HTMLElement`, и `LinkStyle` (en-US).*

`HTMLLinkElement.as` (en-US)

Это `DOMString` представляющий тип контента загружаемый по HTML ссылке.

`HTMLLinkElement.crossOrigin` (en-US)
Экспериментальная возможность

Is a `DOMString` that corresponds to the CORS setting for this link element. See CORS settings attributes (en-US) for details.

`HTMLLinkElement.disabled`

Is a `Boolean` which represents whether the link is disabled; currently only used with style sheet links.

`HTMLLinkElement.href`

Is a `DOMString` representing the URI for the target resource.

`HTMLLinkElement.hreflang` (en-US)

Is a `DOMString` representing the language code for the linked resource.

`HTMLLinkElement.media`

Is a `DOMString` representing a list of one or more media formats to which the resource applies.

`HTMLLinkElement.referrerPolicy` (en-US)
Экспериментальная возможность

Is a `DOMString` that reflects the `referrerpolicy` HTML attribute indicating which referrer to use.

`HTMLLinkElement.rel` (en-US)

Is a `DOMString` representing the forward relationship of the linked resource from the document to the resource.

`HTMLLinkElement.relList` (en-US) Только для чтения

Is a `DOMTokenList` that reflects the `rel` HTML attribute, as a list of tokens.

`HTMLLinkElement.sizes` Только для чтения

Is a `DOMSettableTokenList` that reflects the `sizes` HTML attribute, as a list of tokens.

`LinkStyle.sheet` (en-US) Только для чтения

Returns the `StyleSheet` object associated with the given element, or `null` if there is none.

`HTMLLinkElement.type`

Is a `DOMString` representing the MIME type of the linked resource.

### Устаревшие свойства

`HTMLLinkElement.charset`

Is a `DOMString` representing the character encoding for the target resource.

`HTMLLinkElement.rev`

Is a `DOMString` representing the reverse relationship of the linked resource from the resource to the document.

**Примечание:** Currently the W3C HTML 5.2 spec states that `rev` is no longer obsolete, whereas the WHATWG living standard still has it labeled obsolete. Until this discrepancy is resolved, you should still assume it is obsolete.

`HTMLLinkElement.target`

Is a `DOMString` representing the name of the target frame to which the resource applies.

Методы
------

*Не имеет методов; наследует методы от своего родителя, `HTMLElement`, и `LinkStyle` (en-US).*

Спецификации
------------

| Specification |
| --- |
| HTML Standard # htmllinkelement |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Элемент HTML, реализующий этот интерфейс: `<link>`.


WebSockets - Интерфейсы веб API

WebSockets
==========

**Веб-сокеты** это продвинутая технология, позволяющая открыть постоянное двунаправленное сетевое соединение между браузером пользователя и сервером. С помощью его API вы можете отправить сообщение на сервер и получить ответ без выполнения http запроса, причём этот процесс будет событийно-управляемым.

Документация
------------

Writing WebSocket client applications

Учебник описывающий как написать WebSocket клиента работающего в браузере.

Справочник по WebSocket (en-US)

A reference to the client-side WebSocket API.

(TBD) Writing WebSocket servers (en-US)

A guide to writing server-side code to handle the WebSocket protocol.

Tools
-----

* Socket.IO: A powerful cross-platform WebSocket API for Node.js.
* WebSocket-Node: A WebSocket server API implementation for Node.js.
* A more extensive list of frameworks and libraries here
Related Topics
--------------

* AJAX, JavaScript
Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* RFC 6455 - The WebSocket Protocol
* WebSocket API Specification
* Server-Sent Events (en-US)
* WebSocket.us - a community-run, not-for-profit site about WebSocket


Использование геолокации - Интерфейсы веб API

Использование геолокации
========================

**Secure context:** This feature is available only in secure contexts (en-US) (HTTPS), in some or all supporting browsers.

**Geolocation API** позволяет пользователю предоставлять своё местоположение web-приложению, если пользователь согласится предоставить его. Из соображений конфиденциальности, у пользователя будет запрошено разрешение на предоставление информации о местоположении.

Концепты и использование
------------------------

Вы часто хотите получать информацию о местоположении пользователя в своём веб приложении, например, для отображения участка на карте, либо для того, чтобы показывать информацию, основанную на местоположении посетителя.

API геолокации может быть вызвано через `Navigator.geolocation`; это заставит браузер пользователя вывести уведомление с запросом для доступа к текущему местоположению. Если его одобрят, то браузер сможет предоставить доступ ко всем возможностям по работе с информацией о местонахождении (например, GPS).

Тогда разработчику станут доступны несколько разных способов получения соответствующей информации:

* `Geolocation.getCurrentPosition()`: возвратит местоположение устройства
* `Geolocation.watchPosition()` (en-US): зарегистрирует функцию-обработчик, которая будет вызываться автоматически каждый раз, когда местоположение изменится, возвращая новые данные.

В обоих случая, методы принимают три аргумента:

* Обязательную колбэк-функцию при успехе: если удалось получить местоположение пользователя, то функция вызовется с объектом `GeolocationPosition` как одним параметром, предоставляющим доступ к данным о месторасположении.
* Необязательную колбэк-функцию при ошибке: если не удалось получить позицию, то колбэк-функция вызовется с объектом `GeolocationPositionError` как одним параметром, содержащим информацию о том, что пошло не так.
* Необязательный объект `PositionOptions` (en-US), который содержит надстройки получения данных о местоположении.
Интерфейсы
----------

`Geolocation`

Главный класс этого API — содержит методы для получения текущего местоположения пользователя, наблюдает за его изменениями и удаляет функции-наблюдатели.

`GeolocationPosition`

Предоставляет месторасположение пользователя. Экземпляр `GeolocationPosition`, полученный при успешном вызове одного из методов `Geolocation`, внутри колбэк-функции при успехе, содержит метку времени плюс экземпляр объекта `GeolocationCoordinates`.

`GeolocationCoordinates`

Предоставлять координаты пользователя; Экземпляр `GeolocationCoordinates` содержит широту, долготу и прочую важную подобную информацию.

`GeolocationPositionError`

`GeolocationPositionError` возвращается при неуспешном вызове методов, содержащихся в `Geolocation`, внутри колбэк-функции при ошибке, содержит код ошибки и сообщение.

`Navigator.geolocation`

Точка входа в API. Возвращает экземпляр объекта `Geolocation`, из которого становятся доступны все функции и методы.

Словари
-------

`PositionOptions` (en-US)

Предоставляет объект, содержащий опции, которые можно передать как параметр в `Geolocation.getCurrentPosition()` и `Geolocation.watchPosition()` (en-US).

Спецификации
------------

| Specification |
| --- |
| Geolocation API # geolocation\_interface |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### Доступность

Так как местоположение, основанное на WiFi, часто предоставляется Google, API местоположения может быть не доступен в Китае. Вы можете использовать местных провайдеров, таких как Baidu, Autonavi или Tencent. Эти сервисы используют IP-адрес пользователя и/или приложение для предоставления наиболее точной позиции.

Смотрите также
--------------

* Использование API местоположения (en-US)
* API местоположения на w3.org
* Кто изменил моё местоположение? (Hacks блог)


SpeechGrammar - Интерфейсы веб API

SpeechGrammar
=============

**Экспериментальная возможность:** **Это экспериментальная технология**
Так как спецификация этой технологии ещё не стабилизировалась, смотрите таблицу совместимости по поводу использования в различных браузерах. Также заметьте, что синтаксис и поведение экспериментальной технологии может измениться в будущих версиях браузеров, вслед за изменениями спецификации.

Интерфейс **`SpeechGrammar`** Web Speech API представляет собой набор слов или шаблонов слов, которые мы хотим, чтобы служба распознавания распознавала.

Грамматика определяется с использованием JSpeech Grammar Format (**JSGF**.) Другие форматы также могут поддерживаться в будущем.

Конструктор
-----------

`SpeechGrammar.SpeechGrammar()` (en-US)

Создаёт новый объект `SpeechGrammar` .

Свойства
--------

`SpeechGrammar.src` (en-US)

Устанавливает и возвращает строку, содержащую грамматику, внутри экземпляра объекта `SpeechGrammar` .

`SpeechGrammar.weight` (en-US) Необязательный

Устанавливает и возвращает вес объекта `SpeechGrammar` .

Примеры
-------

```js
var grammar =
  "#JSGF V1.0; grammar colors; public <color> = aqua | azure | beige | bisque | black | blue | brown | chocolate | coral | crimson | cyan | fuchsia | ghostwhite | gold | goldenrod | gray | green | indigo | ivory | khaki | lavender | lime | linen | magenta | maroon | moccasin | navy | olive | orange | orchid | peru | pink | plum | purple | red | salmon | sienna | silver | snow | tan | teal | thistle | tomato | turquoise | violet | white | yellow ;";
var recognition = new SpeechRecognition();
var speechRecognitionList = new SpeechGrammarList();
speechRecognitionList.addFromString(grammar, 1);
recognition.grammars = speechRecognitionList;

console.log(speechRecognitionList[0].src); // должно вернуть то же, что и содержимое переменной gramar
console.log(speechRecognitionList[0].weight); // должно вернуть 1 - столько же, сколько указано в 4-й строчке.
```

Спецификации
------------

| Specification |
| --- |
| Web Speech API # speechreco-speechgrammar |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Web Speech API


HTMLAreaElement - Интерфейсы веб API

HTMLAreaElement
===============

**`HTMLAreaElement`** интерфейс предоставляющий специальные свойства и методы (помимо тех, постоянных объектов `HTMLElement` интерфейса, также доступных ему по наследству) для манипуляции расположением и представлением пространством элементов.

Свойства
--------

*Наследует свойства от его родителя, `HTMLElement`, и реализует те из `URLUtils`.*

`HTMLAreaElement.accessKey`

Это `DOMString` содержащий единственный символ, который переключает фокус ввода для управления.

`HTMLAreaElement.alt`

Это `DOMString` которое отображает `alt` HTML атрибут, содержащий альтернативный текст для элемента.

`HTMLAreaElement.coords`

Это `DOMString` который отображает `coords` HTML атрибут, содержащий координаты активного участка региона.

`HTMLAreaElement.download`
Экспериментальная возможность

Это `DOMString` показывает что связанный ресурс предназначен для загрузки, а не для отображения в браузере. Значение представляет собой предполагаемое имя файла. Если имя не является допустимым именем файла в данной ОС, браузер будет адаптировать его.

`URLUtils.hash`

Это `DOMString` содержащий идентификатор фрагмента (включая начальный hash mark (#)), если таковые имеются, в указанном URL.

`URLUtils.host`

Это `DOMString` содержащий имя хоста и порт (если это не порт по умолчанию) в указанном URL.

`URLUtils.hostname`

Это `DOMString` содержащий имя хоста в указанном URL.

`URLUtils.href`

Это `DOMString` содержание которого отображает `href` HTML атрибут, содержащий действительный URL связанного с ним ресурса.

`HTMLAreaElement.hreflang`

Это `DOMString` содержание которого отображает `hreflang` HTML атрибут, показывающий язык связанного с ним ресурса.

`HTMLAreaElement.media`

Это `DOMString` содержание которого отображает `media` HTML атрибут, показывающий целевое media, связанного с ним ресурса.

`HTMLAreaElement.noHref`

Это `Boolean` (en-US) флаг показывающий, если зона неактивна (`true`) или активна (`false`).

`URLUtils.password`

Это `DOMString` содержащий пароль указанный перед именем домена.

`URLUtils.origin` Только для чтения

Возвращает `DOMString` содержащий изначальный URL, то есть его схема, его домен, его порт.

`URLUtils.pathname`

Это `DOMString` содержащий составную часть пути имени, если таковые имеются в указанном URL.

`URLUtils.port`

Это `DOMString` содержащий компонент порта , если таковой имеется в указанном URL.

`URLUtils.protocol`

Это `DOMString` содержащий компоненту протокола (в том числе двоеточия `':'`), в указанном URL.

`HTMLAreaElement.referrer` (en-US)
Экспериментальная возможность

Это `DOMString` который отображает `referrer` HTML атрибут, показывающий какой referrer используется когда извлекается связанны с ним ресурс.

`HTMLAreaElement.rel` (en-US)

Это `DOMString` который отображает `rel` HTML атрибут,показывая отношения текущего документа со связанным с ним ресурсом.

`HTMLAreaElement.relList` (en-US) Только для чтения

Возвращает `DOMTokenList` который отображает `rel` HTML атрибут, показывая отношения текущего документа к связанному с ним ресурса, как список токенов.

`HTMLAreaElement.search` (en-US)

Это `DOMString` содержащий найденный элемент (включая начальный знак вопроса`'?'`), если таковой имеется, в указанном URL.

`HTMLAreaElement.shape`

Это `DOMString` который отображается `shape` HTML атрибут, включающий вид активного участка, ограниченный известными значениями.

`HTMLAreaElement.tabIndex`

Как `long` содержащий положение элемента в порядке табуляции.

`HTMLAreaElement.target` (en-US)

Это `DOMString` которое отображает `target` HTML атрибут, включая контекст просмотра, в котором открыт связанный с ним ресурс.

`HTMLAreaElement.type`

Это `DOMString` которое отображает `type` HTML атрибут, показывающий MIME тип связанного с ним ресурса.

`URLUtils.username`

Это `DOMString` содержащий имя пользователя. определённое перед доменным именем.

Методы
------

*наследует методы от его родителя, `HTMLElement` и реализует те из `URLUtils`.*

`URLUtils.toString()`

Возвращает `DOMString` содержащий весь URL скрипта, выполняемого в `Worker`. Это синоним для `URLUtils.href`.

Спецификации
------------

| Specification |
| --- |
| HTML Standard # htmlareaelement |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* HTML-элемент реализующий этот интерфейс: `<area>`.


Worker - Интерфейсы веб API

Worker
======

Интерфейс **`Worker`** из Web Workers API является представителем фоновой задачи, которая легко может быть создана и может передавать сообщения обратно создателю. Создание worker - это вызов конструктора `Worker()` и задание скрипта, выполняемого в потоке worker.

Workers могут, в свою очередь, порождать новые workers, если эти workers расположены в одном каталоге с родительской страницей (Примечание: вложенные workers в настоящее время не поддерживаются в Blink). Кроме того, workers могут использовать `XMLHttpRequest` для network I/O, при условии, что атрибуты `responseXML` и `channel` `XMLHttpRequest` всегда возвращают `null`.

Не все интерфейсы и функции могут быть использованы в скрипте, ассоциированном с `Worker`.

В Firefox, если вы хотите использовать workers в расширениях и хотели бы иметь доступ к js-ctypes, вам нужно использовать объект `ChromeWorker`.

Свойства
--------

*Наследует свойства родителя, `EventTarget`, и поддерживает свойства из `AbstractWorker` (en-US).*

### Обработчики событий

`AbstractWorker.onerror` (en-US)

`EventListener` (en-US) вызываемый каждый раз, когда из воркера приходит `ErrorEvent` (en-US) с типом `error`. Это событие унаследовано от `AbstractWorker` (en-US).

`Worker.onmessage`

`EventListener` (en-US) вызываемый каждый раз, когда из воркера приходит `MessageEvent` (en-US) с типом `message` — то есть когда сообщение было отправлено воркером в родительский документ с помощью `DedicatedWorkerGlobalScope.postMessage` (en-US). Сообщение передаётся в свойстве объекта события `data` (en-US).

Конструкторы
------------

`Worker()`

Создаёт dedicated web worker, выполняющий скрипт, расположенный по указанному URL. Воркеры также могут быть созданы с использованием Blobs.

Методы
------

*Наследует методы своего родителя, `EventTarget`, а также реализует методы `AbstractWorker` (en-US).*

`Worker.postMessage()`

Отправляет сообщение — которое может являться `любым` JavaScript объектом — во внутреннюю область видимости воркера.

`Worker.terminate()`

Немедленно завершает выполнение воркера. Не даёт воркеру возможности завершить выполняемые операции; просто сразу останавливается. Экземпляры ServiceWorker не поддерживают этот метод.

Пример
------

Представленный фрагмент кода показывает создание объекта `Worker` с помощью конструктора `Worker()`, а также его использование:

```js
var myWorker = new Worker("worker.js");

first.onchange = function () {
  myWorker.postMessage([first.value, second.value]);
  console.log("Message posted to worker");
};
```

For a full example, see ourBasic dedicated worker example (run dedicated worker).

Спецификации
------------

| Specification |
| --- |
| HTML Standard # dedicated-workers-and-the-worker-interface |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using web workers
* Functions available to workers
* Другие типы воркеров: `SharedWorker` и ServiceWorker (en-US).
* Non-standard, Gecko-specific workers: `ChromeWorker`, used by extensions.


WindowTimers.setTimeout() - Интерфейсы веб API

WindowTimers.setTimeout()
=========================

Краткое изложение
-----------------

Вызов функции или выполнение фрагмента кода после указанной задержки.

Синтаксис
---------
```

var timeoutID = window.setTimeout(func, [, delay, param1, param2, ...]);
var timeoutID = window.setTimeout(code [, delay]);
```

где

* `timeoutID -` это *числовой* ID, который может быть использован позже с `window.clearTimeout()` (en-US).
* `func -` это функция (en-US), которую требуется вызвать после `delay` миллисекунд.
* `code` - в альтернативном варианте применения это строка, содержащая код, который вы хотите выполнить после `delay` миллисекунд (использовать этот метод **не рекомендуется** по тем же причинам, что и eval() (en-US))
* `delay` Необязательный - задержка в миллисекундах (тысячных долях секунды), после которой будет выполнен вызов функции. Реальная задержка может быть больше; см. Notes ниже.

Необходимо принять во внимание, что передача дополнительных параметров функции в первом варианте не работает в Internet Explorer 9 и ниже. Для использования этой функциональности в таких браузерах, необходимо использовать код для совместимости (см. раздел Аргументы колбэк-функции).

**Предупреждение:** **Important:** Prior to Gecko 13, Gecko passed an extra parameter to the callback routine, indicating the "actual lateness" of the timeout in milliseconds. This non-standard parameter is no longer passed.

Пример
------

В следующем примере на веб странице создаются две простые кнопки, к которым привязываются действия setTimeout и clearTimeout. Нажатие на первую кнопку установит таймаут, который вызовет диалоговое окно через две секунды. Также будет сохранён id для clearTimeout. Таймаут также может быть отменён по нажатию на вторую кнопку.

### HTML Content

```html
<p>Live Example</p>
<button onclick="delayedAlert();">Show an alert box after two seconds</button>
<p></p>
<button onclick="clearAlert();">Cancel alert before it happens</button>
```

### JavaScript Content

```js
var timeoutID;

function delayedAlert() {
  timeoutID = window.setTimeout(slowAlert, 2000);
}

function slowAlert() {
  alert("That was really slow!");
}

function clearAlert() {
  window.clearTimeout(timeoutID);
}
```

Смотрите также `пример clearTimeout()` (en-US).

Аргументы колбэк-функции
------------------------

Если вам нужно передать аргумент в вашу callback функцию, но нужно, чтобы это работало в Internet Explorer 9 и ниже, который не поддерживает передачу дополнительных параметров (ни с `setTimeout()` или `setInterval()`), то вы можете прописать специальный код для *совместимости с IE,* вставив этот код в начало ваших скриптов, который включит функцию передачи стандартных параметров HTML5 в Internet Explorer для обоих таймеров.

```js
/\*\
|\*|
|\*| IE-specific polyfill which enables the passage of arbitrary arguments to the
|\*| callback functions of JavaScript timers (HTML5 standard syntax).
|\*|
|\*| https://developer.mozilla.org/ru/docs/DOM/window.setInterval
|\*|
|\*| Syntax:
|\*| var timeoutID = window.setTimeout(func, delay, [param1, param2, ...]);
|\*| var timeoutID = window.setTimeout(code, delay);
|\*| var intervalID = window.setInterval(func, delay[, param1, param2, ...]);
|\*| var intervalID = window.setInterval(code, delay);
|\*|
\\*/

if (document.all && !window.setTimeout.isPolyfill) {
  var __nativeST__ = window.setTimeout;
  window.setTimeout = function (
    vCallback,
    nDelay /\*, argumentToPass1, argumentToPass2, etc. \*/,
  ) {
    var aArgs = Array.prototype.slice.call(arguments, 2);
    return \_\_nativeST\_\_(
      vCallback instanceof Function
        ? function () {
            vCallback.apply(null, aArgs);
          }
        : vCallback,
      nDelay,
    );
  };
  window.setTimeout.isPolyfill = true;
}

if (document.all && !window.setInterval.isPolyfill) {
  var __nativeSI__ = window.setInterval;
  window.setInterval = function (
    vCallback,
    nDelay /\*, argumentToPass1, argumentToPass2, etc. \*/,
  ) {
    var aArgs = Array.prototype.slice.call(arguments, 2);
    return \_\_nativeSI\_\_(
      vCallback instanceof Function
        ? function () {
            vCallback.apply(null, aArgs);
          }
        : vCallback,
      nDelay,
    );
  };
  window.setInterval.isPolyfill = true;
}
```

Правка только для IE
--------------------

If you want a completely unobtrusive hack for every other mobile or desktop browser, including IE 9 and below, you can either use JavaScript conditional comments:

```js
/\*@cc\_on
 // conditional IE < 9 only fix
 @if (@\_jscript\_version <= 6)
 (function(f){
 window.setTimeout =f(window.setTimeout);
 window.setInterval =f(window.setInterval);
 })(function(f){return function(c,t){var a=[].slice.call(arguments,2);return f(function(){c.apply(this,a)},t)}});
 @end
@\*/
```

Или используйте очень чистый подход, основанный на условном свойстве IE HTML:

```html
<!--[if lte IE 9
 ]><script>
 (function (f) {
 window.setTimeout = f(window.setTimeout);
 window.setInterval = f(window.setInterval);
 })(function (f) {
 return function (c, t) {
 var a = [].slice.call(arguments, 2);
 return f(function () {
 c.apply(this, a);
 }, t);
 };
 });
 </script><!
[endif]-->
```

Another possibility is to use an anonymous function to call your callback, but this solution is a bit more expensive. Example:

```js
var intervalID = setTimeout(function () {
  myFunc("one", "two", "three");
}, 1000);
```

Yet another possibility is to use function's bind (en-US). Example:

```js
setTimeout(function (arg1) {}.bind(undefined, 10));
```

Проблема с "`this`"
-------------------

Когда вы передаёте метод в `setTimeout()` (или в любую другую функцию, если на то пошло), то вызов будет осуществлён с неправильным значением `this`. Эта проблема разъясняется детально в JavaScript reference (en-US).

### Объяснение

Code executed by `setTimeout()` is run in a separate execution context to the function from which it was called. As a consequence, the `this` keyword for the called function will be set to the `window` (or `global`) object; it will not be the same as the `this` value for the function that called `setTimeout`. See the following example:

```js
myArray = ["zero", "one", "two"];
myArray.myMethod = function (sProperty) {
  alert(arguments.length > 0 ? this[sProperty] : this);
};

myArray.myMethod(); // prints "zero,one,two"
myArray.myMethod(1); // prints "one"
setTimeout(myArray.myMethod, 1000); // prints "[object Window]" after 1 second
setTimeout(myArray.myMethod, 1500, "1"); // prints "undefined" after 1.5 seconds
// let's try to pass the 'this' object
setTimeout.call(myArray, myArray.myMethod, 2000); // error: "NS\_ERROR\_XPC\_BAD\_OP\_ON\_WN\_PROTO: Illegal operation on WrappedNative prototype object"
setTimeout.call(myArray, myArray.myMethod, 2500, 2); // same error
```

Как видите, нет способов передать объект `this` в колбэк-функцию..

### Возможное решение

A possible way to solve the "`this`" problem is to replace the two native `setTimeout()` or `setInterval()` global functions with two *non-native* ones which will enable their invocation through the `Function.prototype.call` method. The following example shows a possible replacement:

```js
// Enable the passage of the 'this' object through the JavaScript timers

var __nativeST__ = window.setTimeout,
  __nativeSI__ = window.setInterval;

window.setTimeout = function (
  vCallback,
  nDelay /\*, argumentToPass1, argumentToPass2, etc. \*/,
) {
  var oThis = this,
    aArgs = Array.prototype.slice.call(arguments, 2);
  return \_\_nativeST\_\_(
    vCallback instanceof Function
      ? function () {
          vCallback.apply(oThis, aArgs);
        }
      : vCallback,
    nDelay,
  );
};

window.setInterval = function (
  vCallback,
  nDelay /\*, argumentToPass1, argumentToPass2, etc. \*/,
) {
  var oThis = this,
    aArgs = Array.prototype.slice.call(arguments, 2);
  return \_\_nativeSI\_\_(
    vCallback instanceof Function
      ? function () {
          vCallback.apply(oThis, aArgs);
        }
      : vCallback,
    nDelay,
  );
};
```

**Примечание:** These two replacements will also enable the HTML5 standard passage of arbitrary arguments to the callback functions of timers in IE. So they can be used as polyfills also. See the Callback arguments paragraph.

Новая тестируемая особенность:

```js
myArray = ["zero", "one", "two"];
myArray.myMethod = function (sProperty) {
  alert(arguments.length > 0 ? this[sProperty] : this);
};

setTimeout(alert, 1500, "Hello world!"); // the standard use of setTimeout and setInterval is preserved, but...
setTimeout.call(myArray, myArray.myMethod, 2000); // prints "zero,one,two" after 2 seconds
setTimeout.call(myArray, myArray.myMethod, 2500, 2); // prints "two" after 2.5 seconds
```

Это не нативные решения *ad hoc* для этой проблемы.

**Примечание:** JavaScript 1.8.5 introduces the `Function.prototype.bind()` (en-US) method, which lets you specify the value that should be used as `this` for all calls to a given function. This lets you easily bypass problems where it's unclear what this will be, depending on the context from which your function was called.

Замечания
---------

Отложенное выполнение кода можно отменить, используя `window.clearTimeout()` (en-US). Если функция должна вызываться неоднократно (например, каждые N миллисекунд), необходимо использовать `window.setInterval()` (en-US).

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

### Passing string literals

Передача строки вместо функции в `setTimeout()` сопряжена с теми же опасностями, что и использование `eval.`

```js
// Правильно
window.setTimeout(function () {
  alert("Hello World!");
}, 500);

// Неправильно
window.setTimeout('alert("Hello World!");', 500);
```

String literals are evaluated in the global context, so local symbols in the context where `setTimeout()` was called will not be available when the string is evaluated as code.

### Минимальная/ максимальная задержка и вложенность таймаута

Historically browsers implement `setTimeout()` "clamping": successive `setTimeout()` calls with `delay` smaller than the "minimum delay" limit are forced to use at least the minimum delay. The minimum delay, `DOM_MIN_TIMEOUT_VALUE`, is 4 ms (stored in a preference in Firefox: `dom.min_timeout_value`), with a `DOM_CLAMP_TIMEOUT_NESTING_LEVEL` of 5ms.

In fact, 4ms is specified by the HTML5 spec and is consistent across browsers released in 2010 and onward. Prior to Gecko 5.0, the minimum timeout value for nested timeouts was 10 ms.

In addition to "clamping", the timeout can also fire later when the page (or the OS/browser itself) is busy with other tasks.

To implement a 0 ms timeout in a modern browser, you can use `window.postMessage()` as described here.

Browsers including Internet Explorer, Chrome, Safari, and Firefox store the delay as a 32-bit signed Integer internally. This causes an Integer overflow when using delays larger than 2147483647, resulting in the timeout being executed immediately.

Спецификации
------------

| Specification |
| --- |
| HTML Standard # dom-settimeout-dev |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Также интересно
---------------

* JavaScript timers
* Timer.jsm
* `window.setInterval` (en-US)
* `window.requestAnimationFrame`
* *Daemons* management


ValidityState - Интерфейсы веб API

ValidityState
=============

Baseline 2023
-------------

Newly availableSince March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
Интерфейс **`ValidityState`** представляет *состояния валидности*, в которых может находиться элемент при валидации ограничений. Вместе они помогают понять, по какой именно причине значение элемента не прошло валидацию.

Свойства
--------

Если свойство возвращает `true`, значит оно отражает причину, по которой значение не прошло валидацию. Исплючением является лишь свойство `valid`, которое возвращает `true`, когда значение элемента соответствует всем ограничениям.

`badInput` Только для чтения

`Boolean` `true`, если пользователь ввёл значение, которое браузер не может преобразовать.

`customError` Только для чтения

`Boolean`, указывающий, было ли установлено кастомное сообщение валидации путём вызова метода `setCustomValidity()` (en-US) с непустой строкой в аргументе.

`patternMismatch` Только для чтения

`Boolean` `true`, если значение не соответствует шаблону, указанному в атрибуте `pattern`. `false`, если значение соответствует этому шаблону. Если `true`, элемент соответствует CSS-псевдоклассу `:invalid`.

`rangeOverflow` Только для чтения

`Boolean` `true`, если значение больше максимума, заданного в атрибуте `max`. `false`, если значение меньше или равно ему. Если `true`, элемент соответствует CSS-псевдоклассам `:invalid` и `:out-of-range`.

`rangeUnderflow` Только для чтения

`Boolean` `true`, если значение меньше минимума, заданного в атрибуте `min`. `false`, если значение больше или равно ему. Если `true`, элемент соответствует CSS-псевдоклассам `:invalid` и `:out-of-range`.

`stepMismatch` Только для чтения

`Boolean` `true`, если значение не соответствует правилам, заданным в атрибуте `step` (то есть, не делится без остатка на значение шага). `false`, если соответствует этим правилам. Если `true`, элемент соответствует CSS-псевдоклассам `:invalid` и `:out-of-range`.

`tooLong` Только для чтения

`Boolean` `true`, если значение превышает лимит, указанный в атрибуте `maxlength` объектов `HTMLInputElement` (en-US) или `HTMLTextAreaElement` (en-US). `false`, если длина меньше или равна максимальной длине. ***Примечание:** Данное свойство никогда не будет `true` в Gecko, потому что значению элемента не разрешается быть больше `maxlength`.* Если `true`, элемент соответствует CSS-псевдоклассам `:invalid` и `:out-of-range`.

`tooShort` Только для чтения

`Boolean` `true`, если длина значения не достигает минимума, указанного в атрибуте `minlength` объектов `HTMLInputElement` (en-US) и `HTMLTextAreaElement` (en-US). `false`, если длина больше или равна ему. Если `true`, элемент соответствует CSS-псевдоклассам `:invalid` и `:out-of-range`.

`typeMismatch` Только для чтения

`Boolean` `true`, если значение не соответствует требуемому синтаксису (когда для `type` задано значение `email` или `url`). `false`, если синтаксис корректный. Если `true`, элемент соответствует CSS-псевдоклассу `:invalid`.

`valid` Только для чтения

`Boolean` `true`, если элемент соответствует всем ограничениям валидации и, следовательно, считается валидным. `false`, если не соответствует любому ограничению. Если `true`, элемент соответствует CSS-псевдоклассу `:valid`; иначе — псевдоклассу `:invalid`.

`valueMissing` (en-US) Только для чтения

`Boolean` `true`, если у элемента есть атрибут `required`, но сам элемент заполнен не был. `false`, если элемент был заполнен. Если `true`, элемент соответствует CSS-псевдоклассу `:invalid`.

Спецификации
------------

| Specification |
| --- |
| HTML Standard # the-constraint-validation-api:validitystate-3 |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Также смотрите
--------------

* Руководство: Валидация ограничений (en-US)
* Учебник: Валидация форм


Текст - Интерфейсы веб API

Текст
=====

Интерфейс **`Text`** представляет собой текстовое содержание (элемента) `Element` или `Attr`. Если элемент не имеет разметки внутри собственного содержимого, то он интерпретируется как a single child (implementing) `Text` ,который содержит текст элемента. Однако, если элемент содержит разметку, он разбивается на information items и `Text` nodes ,которые образуют его дочерние элементы.

Новые документы имеют единственный(одиночный) `Text` node для каждого блока текста. Со временем, могут быть созданы новые `Text` nodes, по мере того, как изменяется содержимое документа. Метод `Node.normalize()` производит слияние смежных объектов `Text` обратно в a single node для каждого блока текста.

EventTarget

Node

CharacterData

TextКонструктор
-----------

`Text()` (en-US)
Экспериментальная возможность

Возвращает `Text` node с параметром, который представляет собой его текстовое содержимое.

Свойства
--------

*Inherits properties from its parent, `CharacterData`.*

`Text.isElementContentWhitespace` Только для чтения

Возвращает флаг `Boolean` (en-US), сигнализирующий, содержит ли (или нет) text node только пробел(ы).

`Text.wholeText` (en-US) Только для чтения

Возвращает `DOMString`, который содержит все `Text` nodes логически примыкающие к этому `Node`, соединённые как в документе.

`Text.assignedSlot` (en-US) Только для чтения

Возвращает объект `HTMLSlotElement`, связанный с этим элементом.

### Свойства (included) от Slotable

*Интерфейс `Text` включает следующее свойство, определяемое при смешивании `Slotable` (en-US).*

`Slotable.assignedSlot` (en-US) Только для чтения

Возвращает `HTMLSlotElement`, представляющий `<slot>`, в который вставлен данный узел.

Методы
------

*Наследует родительские методы, `CharacterData`.*

`Text.replaceWholeText` (en-US)

Заменяет текст текущего узла и всех логически прилегающих узлов указанным текстом(with the specified text).

`Text.splitText` (en-US)

Разбивает узел на два узла с заданным отступом.

Спецификации
------------

| Specification |
| --- |
| DOM Standard # interface-text |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотри(те) также
----------------

* The DOM interfaces index.


URLSearchParams - Интерфейсы веб API

URLSearchParams
===============

**`URLSearchParams`** интерфейс определяет служебные методы для работы со строкой запроса URL.

Объект, реализующий `URLSearchParams`, может непосредственно использоваться в структуре `for...of`, например, следующие две строки идентичны:
```

for (var p of mySearchParams);
for (var p of mySearchParams.entries());
```

**Примечание:** Эта возможность доступна в Web Workers

Конструктор
-----------

`URLSearchParams()` (en-US)

Конструктор возвращает объект `URLSearchParams`.

Свойства
--------

*Наследование свойств отсутствует.*

Методы
------

*Отсутствует наследование методов.*

`URLSearchParams.append()` (en-US)

Добавляет указанную пару key/value в качестве нового параметра поиска.

`URLSearchParams.delete()`

Удаляет заданный параметр поиска и связанное с ним значение из списка всех параметров поиска.

`URLSearchParams.entries()` (en-US)

Возвращает `iterator`, позволяющий пройти через все пары key/value, содержащиеся в этом объекте.

`URLSearchParams.get()` (en-US)

Возвращает первое значение, связанное с заданным параметром поиска.

`URLSearchParams.getAll()` (en-US)

Возвращает все значения ассоциации с заданным параметром поиска.

`URLSearchParams.has()` (en-US)

Возвращает `Boolean`, указывающий, существует ли такой параметр поиска.

`URLSearchParams.keys()` (en-US)

Возвращает `iterator`, позволяющий пройти все ключи пары key/value, содержащиеся в этом объекте.

`URLSearchParams.set()` (en-US)

Устанавливает значение, связанное с заданным параметром поиска, с заданным значением. Если было несколько значений, удалите остальные.

`URLSearchParams.toString()` (en-US)

Возвращает строку, содержащую строку запроса, подходящую для использования в URL-адресе.

`URLSearchParams.values()` (en-US)

Возвращает `iterator`, позволяющий пройти через все значения пар key/value, содержащихся в этом объекте.

Пример
------

```js
var paramsString = "q=URLUtils.searchParams&topic=api";
var searchParams = new URLSearchParams(paramsString);

// Итерируем параметры поиска.
for (let p of searchParams) {
  console.log(p);
}

searchParams.has("topic") === true; // true
searchParams.get("topic") === "api"; // true
searchParams.getAll("topic"); // ["api"]
searchParams.get("foo") === null; // true
searchParams.append("topic", "webdev");
searchParams.toString(); // "q=URLUtils.searchParams&topic=api&topic=webdev"
searchParams.set("topic", "More webdev");
searchParams.toString(); // "q=URLUtils.searchParams&topic=More+webdev"
searchParams.delete("topic");
searchParams.toString(); // "q=URLUtils.searchParams"
```

Спецификации
------------

| Specification |
| --- |
| URL Standard # urlsearchparams |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Other URL-related interfaces: `URL`, `URLUtils`.
* Google Developers: Easy URL manipulation with URLSearchParams