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

Event
=====

Интерфейс **`Event`** представляет собой любое событие, которое происходит в DOM; некоторые из них генерируемые пользователем (клик мышью или нажатие клавиши на клавиатуре), а некоторые - генерируемые API (события, обозначающие завершение процесса анимации, приостановка видео и т.д.). Существует много типов событий, некоторые из них используют интерфейсы, базирующиеся на главном интерфейсе `Event`. `Event` содержит общие свойства и методы для всех событий.

Интерфейсы, основанные на `Event`
---------------------------------

Ниже приведён список интерфейсов, основанных на главном интерфейсе `Event`, а также указаны ссылки на них в документации MDN API. Заметьте, что имена всех интерфейсов оканчиваются на "Event".

* `AnimationEvent`
* `AudioProcessingEvent` (en-US)
* `BeforeInputEvent`
* `BeforeUnloadEvent`
* `BlobEvent` (en-US)
* `ClipboardEvent`
* `CloseEvent` (en-US)
* `CompositionEvent` (en-US)
* `CSSFontFaceLoadEvent`
* `CustomEvent` (en-US)
* `DeviceLightEvent`
* `DeviceMotionEvent` (en-US)
* `DeviceOrientationEvent` (en-US)
* `DeviceProximityEvent`
* `DOMTransactionEvent`
* `DragEvent` (en-US)
* `EditingBeforeInputEvent`
* `ErrorEvent` (en-US)
* `FetchEvent`
* `FocusEvent` (en-US)
* `GamepadEvent`
* `HashChangeEvent` (en-US)
* `IDBVersionChangeEvent` (en-US)
* `InputEvent` (en-US)
* `KeyboardEvent`
* `MediaStreamEvent` (en-US)
* `MessageEvent` (en-US)
* `MouseEvent`
* `MutationEvent` (en-US)
* `OfflineAudioCompletionEvent` (en-US)
* `PageTransitionEvent` (en-US)
* `PointerEvent` (en-US)
* `PopStateEvent` (en-US)
* `ProgressEvent` (en-US)
* `RelatedEvent`
* `RTCDataChannelEvent` (en-US)
* `RTCIdentityErrorEvent`
* `RTCIdentityEvent`
* `RTCPeerConnectionIceEvent` (en-US)
* `SensorEvent`
* `StorageEvent` (en-US)
* `SVGEvent` (en-US)
* `SVGZoomEvent`
* `TimeEvent` (en-US)
* `TouchEvent`
* `TrackEvent` (en-US)
* `TransitionEvent` (en-US)
* `UIEvent` (en-US)
* `UserProximityEvent`
* `WebGLContextEvent` (en-US)
* `WheelEvent` (en-US)
Конструктор
-----------

`Event()`

Создаёт объект `Event` и возвращает его вызывающему.

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

`Event.bubbles` Только для чтения

Логическое значение, указывающее, всплыло ли событие вверх по DOM или нет.

`Event.cancelBubble` (en-US)

Историческое название синонима `Event.stopPropagation()`. Если установить значение в `true` до возврата из обработчика события (Event Handler), то событие не будет распространяться дальше (например, на обработчики для родительских узлов).

`Event.cancelable` Только для чтения

Логическое значение, показывающее возможность отмены события.

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

Логическое значение, показывающее может или нет событие всплывать через границы между shadow DOM (внутренний DOM конкретного элемента) и обычного DOM документа.

`Event.currentTarget` Только для чтения

Ссылка на текущий зарегистрированный объект, на котором обрабатывается событие. Это объект, которому планируется отправка события; поведение можно изменить с использованием перенаправления (*retargeting*).

`Event.deepPath` (en-US)
Non-standard

`Массив` DOM-`узлов`, через которые всплывало событие.

`Event.defaultPrevented` Только для чтения

Показывает, была ли для события вызвана функция `event.preventDefault()`.

`Event.eventPhase` Только для чтения

Указывает фазу процесса обработки события.

`Event.explicitOriginalTarget` (en-US)
Non-standard
 Только для чтения

Явный первоначальный целевой объект события (Mozilla-специфичный). Не может содержать анонимного контента.

`Event.originalTarget` (en-US)
Non-standard
 Только для чтения

Первоначальный целевой объект события до перенаправлений (Mozilla-специфичный). Может быть из анонимного контента.

`Event.returnValue` (en-US)
Non-standard

Нестандартная альтернатива (оставшаяся от старых версий Microsoft Internet Explorer) для `Event.preventDefault()` и `Event.defaultPrevented`.

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

`Логическое значение`, показывающее всплывает ли данное событие через shadow root (внутренний DOM-элемента). Это свойство было переименовано в `composed` (en-US).

`Event.srcElement`
Non-standard

Нестандартный синоним (остался от старых версий Microsoft Internet Explorer) для `Event.target`.

`Event.target` Только для чтения

Ссылка на целевой объект, на котором произошло событие.

`Event.timeStamp` Только для чтения

Время, когда событие было создано (в миллисекундах). По спецификации это время от начала Эпохи (Unix Epoch), но в действительности в разных браузерах определяется по-разному; кроме того, ведётся работа по изменению его на `DOMHighResTimeStamp` тип.

`Event.type` Только для чтения

Название события (без учёта регистра символов).

`Event.isTrusted` Только для чтения

Показывает было или нет событие инициировано браузером (например, по клику мышью) или из скрипта (например, через функцию создания события, такую как event.initEvent (en-US))

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

`Event.createEvent()` (en-US)

Создаёт новое событие, которое затем должно быть проинициализировано вызовом его метода `initEvent()`.

`Event.initEvent()`
Устарело

Инициализация значений созданного с помощью Document.createEvent() (en-US) события. Если событие уже отправлено, то эта функция ничего не делает.

`Event.preventBubble()`
Non-standard

Предотвращает всплытие события. Устаревшая, используйте вместо неё `event.stopPropagation`.

`Event.preventCapture()`
Non-standard

Устаревшая, используйте вместо неё `event.stopPropagation`.

`Event.preventDefault()`

Отменяет событие (если его возможно отменить).

`Event.stopImmediatePropagation()`

Для конкретного события не будет больше вызвано обработчиков. Ни тех, которые привязаны к этому же элементу (на котором работает обработчик, который вызывает этот Event.stopImmediatePropagation()), ни других, которые могли бы вызваться при распространении события позже (например, в фазе перехвата - capture).

`Event.stopPropagation()`

Остановка распространения события далее по DOM.

`Event.getPreventDefault()`
Non-standard

Нестандартная. Возвращает значение `Event.defaultPrevented`. Используйте вместо неё `Event.defaultPrevented`.

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

| Specification |
| --- |
| DOM Standard # interface-event |

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

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

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

* Типы событий: Event reference (en-US)
* Сравнение Event Targets (target и currentTarget и relatedTarget и originalTarget)
* Creating and triggering custom events (en-US)
* Для разработчиков дополнений Firefox:
    + Listening to events in Firefox extensions
    + Listening to events on all tabs
* Mozilla related events in real life at wiki.mozilla.org


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

KeyboardEvent
=============

Объекты **`KeyboardEvent`** описывают работу пользователя с клавиатурой. Каждое событие описывает клавишу; тип события (`keydown`, `keypress` или `keyup`) определяет произведённый тип действия.

**Примечание:** `KeyboardEvent` сообщит только о том, что на клавише произошло событие. Когда вам нужно обрабатывать ввод текста, то вместо него используйте "`HTML5 input"` (en-US)-событие. Например, если пользователь вводит текст рукописным способом, предположим с планшета, то события клавиш могут не возникать.

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

`KeyboardEvent()` (en-US)

Создаёт объект `KeyboardEvent`.

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

*Этот интерфейс также наследует методы от своих родителей: `UIEvent` (en-US) и `Event`.*

`KeyboardEvent.getModifierState()` (en-US)

Возвращает `Boolean`, показывающий, что использовалась клавиша-модификатор, такая как

`Alt`

,

`Shift`

,

`Ctrl`

или

`Meta`

, которая была нажата, когда создалось событие.

`KeyboardEvent.initKeyEvent()` (en-US)
Устарело

Инициализирует объект `KeyboardEvent`. Этот метод реализован только в движке Gecko (остальные использовали метод `KeyboardEvent.initKeyboardEvent()` (en-US)), и он не должен в дальнейшем использоваться. Новый стандартный способ - это использование конструктора `KeyboardEvent()` (en-US).

`KeyboardEvent.initKeyboardEvent()` (en-US)
Устарело

Инициализирует объект `KeyboardEvent`. Этот метод никогда не был реализован в движке Gecko (вместо него использовался `KeyboardEvent.initKeyEvent()` (en-US)), и он не должен в дальнейшем использоваться. Новый стандартный способ - это использование конструктора `KeyboardEvent()` (en-US).

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

*Этот интерфейс также наследует свойства от своих родителей: `UIEvent` (en-US) and `Event`.*

`KeyboardEvent.altKey` Только для чтения

Возвращает `Boolean`, которое `true`, если клавиша

`Alt`

(

`Option`

или

`⌥`

в OS X) была активна, когда возникло событие.

`KeyboardEvent.char`
Non-standard

Устарело
Только для чтения

Возвращает `DOMString`, представляющий символьное значение клавиши. Если клавиша соответствует печатному символу, то это значение будет непустой Unicode-строкой, содержащей этот символ. Если клавиша не имеет печатного представления, то значение будет пустой строкой.

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

**Предупреждение:** Эта функция была удалена из событий "DOM Level 3 Events". Она поддерживается только IE9+ и Microsoft Edge.

`KeyboardEvent.charCode` (en-US)
Устарело
Только для чтения

Возвращает `Number`, представляющий Unicode-номер клавиши; этот атрибут использовался только с событием `keypress`. Для клавиш, чей `char`-атрибут содержит несколько символов, то значением этого атрибута будет Unicode-значение первого символа. В Firefox 26 этот атрибут возвращал коды для печатных символов.

**Предупреждение:** Это нерекомендуемый к эксплуатации атрибут; по возможности вам нужно использовать вместо него `KeyboardEvent.key`.

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

Возвращает `DOMString` с кодом клавиши, представленного события.

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

Возвращает `Boolean`, которое `true`, если клавиша

`Ctrl`

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

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

Возвращает `Boolean`, которое `true`, если событие возникло между "после-`compositionstart`" и "до-`compositionend`".

`KeyboardEvent.key` Только для чтения

Возвращает `DOMString`, представляющее значение клавиши, на которой возникло событие.

`KeyboardEvent.keyCode` (en-US)
Устарело
 Только для чтения

Возвращает `Number`, представляющее системный и зависящий от конкретной реализации числовой код, идентифицирующий немодифицированное значение нажатой клавиши.

**Предупреждение:** Это нерекомендуемый к эксплуатации атрибут; по возможности вам нужно использовать вместо него `KeyboardEvent.key`.

`KeyboardEvent.keyIdentifier` (en-US)
Non-standard

Устарело
Только для чтения

Это свойство нестандартное, и его использование не рекомендуется в пользу `KeyboardEvent.key`. Это часть устаревшего "DOM Level 3 Events".

`KeyboardEvent.keyLocation`
Non-standard

Устарело
Только для чтения

Это нестандартный нерекомендуемый синоним для `KeyboardEvent.location` (en-US). Это часть устаревшего "DOM Level 3 Events".

`KeyboardEvent.locale` Только для чтения

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

**Примечание:** Это не описание языка ввода текста. Пользователь может использовать одну раскладку клавиатуры для ввода на разных языках.

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

Возвращает `Number`, представляющее расположение клавиши на клавиатуре или другом устройстве ввода.

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

Возвращает `Boolean`, которое `true`, если клавиша

`Meta`

(на клавиатуре Mac - клавиша

`⌘ Command`

; на Windows-клавиатуре - клавиша "Windows"

`⊞`

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

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

Возвращает `Boolean`, которое `true`, если клавиша была нажата до тех пор, пока её ввод не начал автоматически повторяться.

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

Возвращает `Boolean`, которое `true`, если клавиша

`Shift`

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

`KeyboardEvent.which`
Устарело
 Только для чтения

Возвращает `Number`, представляющее зависящее от конкретной реализации значение системного кода нажатой клавиши, который представляет собой немодифицируемое значение; это обычно то же, что свойство `keyCode`.

**Предупреждение:** Это нерекомендуемый к эксплуатации атрибут; по возможности вам нужно использовать вместо него `KeyboardEvent.key`.

Примечания
----------

Особенности событий `keydown`, `keypress` и `keyup`. Для большинства клавиш Gecko обрабатывает последовательность событий так:

1. Когда клавиша сначала нажата, то отправляется событие `keydown`.
2. Если клавиша не является модификатором, то отправляется событие `keypress`.
3. Когда пользователь отпускает клавишу, то отправляется событие `keyup`.
### Особые случаи

Некоторые клавиши переключают подсветку индикаторов, такие как `Caps Lock`, `Num Lock` и `Scroll Lock`. На Windows и Linux эти клавиши создают только лишь события `keydown` и `keyup`.

**Примечание:** В Linux Firefox 12 и более ранних также обрабатывается событие `keypress`.

Но в связи с ограничениями Mac OS X модель событий клавиши `Caps Lock` включает в себя только `keydown`. События `Num Lock` поддерживались на старых ноутбуках (2007 года и старше), но затем Mac OS X их перестала поддерживать, даже на внешних клавиатурах. На совсем старых MacBooks клавиша `Num Lock` вообще не генерирует никаких событий. Движок Gecko не поддерживает клавишу `Scroll Lock`, если это внешняя клавиатура с клавишей `F14`. В некоторых старых версиях Firefox эта клавиша генерирует событие `keypress`; это являлось нестабильным поведением и описано в Firefox bug 602812.

### Обработка автоповтора нажатой клавиши

Когда клавиша нажата и удерживается, то начинается автоповтор. Результатом этого будет последовательность событий аналогичная следующей:

1. `keydown`
2. `keypress`
3. `keydown`
4. `keypress`
5. <<повтор до тех пор, пока пользователь не отпустит клавишу>>
6. `keyup`

Это то, что должно произойти в соответствии со спецификацией DOM Level 3. Однако, есть несколько предостережений относительно этого, описанных ниже.

#### Автоповтор на некоторых GTK-средах, таких как Ubuntu 9.4

В некоторых GTK-средах автоповтор обрабатывается автоматически нативными функциями как событие key-up, и у Gecko нет способа отличить серию одиночных нажатий от автоповтора. На таких платформах автоповтор генерирует следующую последовательность событий:

1. `keydown`
2. `keypress`
3. `keyup`
4. `keydown`
5. `keypress`
6. `keyup`
7. <<повтор, пока пользователь не отпустит клавишу>>
8. `keyup`

В этих средах, к сожалению, нет возможности сказать веб-контенту, произошёл автоповтор или клавиша была нажата несколько раз.

#### Обработка автоповтора на системах до Gecko 5.0

До Gecko 5.0 обработка событий клавиатуры была различна на разных платформах.

Windows

Поведение автоповтора такое же как в Gecko 4.0 и более поздних.

Mac

После первого события `keydown` только отправляются события `keypress` до тех пор, пока не произойдёт событие `keyup`; внутриинтервальные события `keydown` не отправляются.

Linux

Поведение событий зависит от конкретной платформы. Они могут иметь как Windows-тип и Mac-тип, так и свои собственные модели поведения.

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

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

```html
<!doctype html>
<html>
  <head>
    <script>
 "use strict";

 document.addEventListener(
 "keydown",
 (event) => {
 const keyName = event.key;

 if (keyName === "Control") {
 // not alert when only Control key is pressed.
 return;
 }

 if (event.ctrlKey) {
 // Хотя event.key это не 'Control' (например, нажата клавиша 'a'),
 // то всё же event.ctrlKey может быть true, если ударживается клавиша Ctrl.
 alert(`Combination of ctrlKey + ${keyName}`);
 } else {
 alert(`Key pressed ${keyName}`);
 }
 },
 false,
 );

 document.addEventListener(
 "keyup",
 (event) => {
 const keyName = event.key;

 // Как только пользователь отпустит клавишу Ctrl, то она больше не будет активной.
 // Поэтому event.ctrlKey = false.
 if (keyName === "Control") {
 alert("Control key was released");
 }
 },
 false,
 );
 </script>
  </head>

  <body></body>
</html>
```

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

| Specification |
| --- |
| UI Events # interface-keyboardevent |

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

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

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

* `KeyboardEvent.code` (en-US).
* `KeyboardEvent.key`.
* `KeyboardEvent.getModifierState` (en-US)


Уведомление - Интерфейсы веб API

Уведомление
===========

Интерфейс `Notification` из Notifications API используется для настройки и отображения уведомлений на рабочий стол пользователя.

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

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

`Notification()` (en-US)

Создаёт новый экземпляр объекта `Notification`.

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

### Собственные свойства

Следующие свойства доступны только для самого объекта `Notification`.

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

Строка, показывающая текущие права доступа для отображения уведомлений. Возможные значения:

* `denied` - Пользователь отказался от отображения уведомлений.
* `granted` - Пользователь дал согласие на отображение уведомлений.
* `default` - Выбор пользователя неизвестен, и поэтому браузер будет действовать так, как если бы значение было `denied`
### Свойства экземпляра

Следующие свойства доступны только для экземпляров объекта `Notification`.

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

Массив действий уведомления, указывается в опциях как параметр конструктора.

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

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

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

Основное тело (текст) уведомления, указывается в опциях как параметр конструктора.

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

Возвращает структурированную копию содержания уведомления.

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

Направление текста уведомления, указывается в опциях как параметр конструктора.

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

Код языка уведомления, указывается в опциях как параметр конструктора.

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

Идентификатор (ID) уведомления, если есть, указывается в опциях как параметр конструктора.

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

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

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

URL изображения, которое должно быть изображено в уведомлении, указывается в опциях как параметр конструктора.

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

Определяет, должен ли пользователь снова быть уведомлен, если новое уведомление заменяет предыдущее.

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

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

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

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

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

Указывает время, в которое уведомление создано, либо применимо (в прошлом, настоящем или будущем).

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

Заголовок уведомления, указывается в опциях как параметр конструктора.

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

Задаёт шаблон вибрации для устройств с вибро.

#### Не поддерживаемые свойства

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

`Notification.noscreen` Только для чтения

Определяет, должно ли срабатывание уведомления включать дисплей устройства или нет.

`Notification.sticky` Только для чтения

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

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

`Notification.onclick` (en-US)

Обработчик события `click (en-US)`. Срабатывает каждый раз, когда пользователь кликает по уведомлению.

`Notification.onerror` (en-US)

Обработчик события `error (en-US)`. Срабатывает каждый раз, когда уведомление сталкивается с ошибкой.

#### Устаревшие обработчики событий

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

`Notification.onclose` (en-US)

Обработчик события `close`. Срабатывает при закрытии уведомления пользователем.

`Notification.onshow` (en-US)

Обработчик события `show`. Срабатывает при отображении уведомления.

`Notification.sound` Только для чтения

Определяет звуковой файл для воспроизведения при уведомлении, по умолчанию установлен системный звук.

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

### Собственные методы

Следующие методы доступны только для самого объекта `Notification`.

`Notification.requestPermission()` (en-US)

Запрашивает разрешение у пользователя показывать уведомления.

### Методы экземпляра

Следующие методы доступны только для экземпляров объекта `Notification`, либо через его `прототип`. Объект `Notification` также наследует методы интерфейса `EventTarget`.

`Notification.close()` (en-US)

Программно закрывает уведомление.

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

Базовый HTML:

```html
<button onclick="notifyMe()">Notify me!</button>
```

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

```js
function notifyMe() {
  // Проверка поддержки браузером уведомлений
  if (!("Notification" in window)) {
    alert("This browser does not support desktop notification");
  }

  // Проверка разрешения на отправку уведомлений
  else if (Notification.permission === "granted") {
    // Если разрешено, то создаём уведомление
    var notification = new Notification("Hi there!");
  }

  // В противном случае, запрашиваем разрешение
  else if (Notification.permission !== "denied") {
    Notification.requestPermission(function (permission) {
      // Если пользователь разрешил, то создаём уведомление
      if (permission === "granted") {
        var notification = new Notification("Hi there!");
      }
    });
  }

  // В конечном счёте, если пользователь отказался от получения
  // уведомлений, то стоит уважать его выбор и не беспокоить его
  // по этому поводу.
}
```

В большинстве случаев вам не надо быть столь многословными. Например в нашем демо Emogotchi (исходный код), мы просто запускаем `Notification.requestPermission` (en-US) несмотря ни на что, чтобы быть уверенными, что мы сможем получить разрешение на отправку уведомлений (тут используется синтаксис новейшего promise-based метода):

```js
Notification.requestPermission().then(function (result) {
  console.log(result);
});
```

Затем мы запускаем простую функцию `spawnNotification()`, когда мы хотим вывести уведомление, передающую аргументы для указания тела, иконки и заголовка, которые нам нужны, а затем она создаёт необходимый объект параметров `options` и запускает уведомление с помощью конструктора `Notification()` (en-US).

```js
function spawnNotification(body, icon, title) {
  var options = {
    body: body,
    icon: icon,
  };
  var n = new Notification(title, options);
}
```

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

| Specification |
| --- |
| Notifications API Standard # api |

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

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

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

* Using the Notifications API (en-US)


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

EventTarget
===========

**`EventTarget`** - это интерфейс, реализуемый объектами, которые могут генерировать события и могут иметь подписчиков на эти события.

Наиболее частые генераторы событий - `Element`, `document`, и `window`, но другие объекты так же могут использоваться в качестве источников событий , например `XMLHttpRequest`, `AudioNode`, `AudioContext`, и другие.

Многие источники событий (включая элементы, документ и окно) также поддерживают установку обработчиков событий (en-US) с помощью on`...` свойств и атрибутов.

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

`EventTarget.addEventListener()`

Регистрирует обработчик событий указанного типа на объекте.

`EventTarget.removeEventListener()`

Удаляет обработчик события.

`EventTarget.dispatchEvent()`

Генерирует событие на объекте `EventTarget`.

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

| Specification |
| --- |
| DOM Standard # interface-eventtarget |

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

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

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

* Event reference (en-US) - доступные события на платформе.
* Event developer guide
* `Event` interface


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

CharacterData
=============

Абстрактный интерфейс **`CharacterData`** представляет собой объект `Node`, который содержит символы. "Абстрактность" интерфейса означает то, что не существует объектов типа `CharacterData`: интерфейс **`CharacterData`** реализуется посредством других интерфейсов, таких как `Text`, `Comment`, или `ProcessingInstruction` (en-US), которые не являются абстрактными.

EventTarget

Node

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

*Наследует свойства родителя, `Node`, реализуется с помощью `ChildNode` и `NonDocumentTypeChildNode` (en-US)интерфейсов.*

`CharacterData.data` (en-US)

- это `DOMString`, представляющая(ий) текстовые данные, которые содержит этот объект (DOMString).

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

Возвращает an `unsigned long` и отображает размер строки, содержащейся в `CharacterData.data`.

`NonDocumentTypeChildNode.nextElementSibling` Только для чтения

Возвращает `Element` следующий сразу после указанного `Element` элемента в дочернем списке своего родителя, или `null` если указанный элемент - последний в списке.

`NonDocumentTypeChildNode.previousElementSibling` Только для чтения

Возвращает `Element` непосредственно до указанного элемента в дочернем списке своего родительского элемента, или `null` если указанный элемент - первый в списке.

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

*Наследует методы родителя, `Node`, и реализует(ся) (через) (`ChildNode` *и `NonDocumentTypeChildNode` (en-US)интерфейсы*.*

`CharacterData.appendData()` (en-US)

Добавляет указанную `DOMString` к строке `CharacterData.data`; после выполненияданные содержат объединённый(элемент) `DOMString`.

`CharacterData.deleteData()` (en-US)

Удаляет указанное количество символов, начиная с указанного отступа, из строки `CharacterData.data`; после выполнения метода, данные(`data)` содержат урезанный `DOMString`.

`CharacterData.insertData()` (en-US)

Inserts the specified characters, at the specified offset, in the `CharacterData.data` string; when this method returns, `data` contains the modified `DOMString`.

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

Удаляет объект из its parent children списка.

`CharacterData.replaceData()` (en-US)

Заменяет указанное количество символов, начиная с указанного отступа, с указанным `DOMString`; после выполнения метода, данные(`data)` содержат изменений `DOMString`.

`CharacterData.substringData()` (en-US)

Возвращает `DOMString`, содержащую(ий) часть `CharacterData.data` указанной длины и начиная с указанного отступа.

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

| Specification |
| --- |
| DOM Standard # interface-characterdata |

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

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

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

* The DOM interfaces index.


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

MediaStream Recording API
=========================

**MediaStream Recording API**, иногда просто называемый *Media Recording API* или *MediaRecorder API*, тесно связан с Media Capture and Streams API (en-US) и WebRTC API. MediaStream Recording API делает возможным захват данных, сгенерированных `MediaStream` или `HTMLMediaElement` объектом для анализа, обработки или сохранения на дисковое пространство. С ним так же удивительно легко работать.

Базовая концепция
-----------------

MediaStream Recording API состоит из единого интерфейса, `MediaRecorder`, который делает всю работу, принимая данные из `MediaStream` и доставляя их обработчику. Данные поставляются с помощью серии `dataavailable` событий, уже в том формате, который был указан, когда `MediaRecorder` был создан. Процесс записи потока прост:

1. Установите `MediaStream` или `HTMLMediaElement` (в виде `<audio>` или `<video>` элемента), чтобы тот служил в качестве источника медиа-данных.
2. Установите `MediaRecorder.ondataavailable` обработчик событий для `dataavailable` событий; он будет вызываться каждый раз, как данные будут доступны.
3. Создайте `MediaRecorder` объект, указав исходный поток и любые опции по желанию (такие как MIME-тип контейнера или желаемый битрейт его треков).
4. Как только исходная медиа запустится и будет достигнута точка, где вы будете готовы записать видео, вызовите `MediaRecorder.start()` для начала записи.
5. Ваш `dataavailable` обработчик будет вызываться каждый раз, как появляются данные, готовые для выполнения вами над ними ожидаемых операций; событие имеет дата-атрибут, чьё значение `Blob`, который содержит медиа-данные. Вы можете принудительно вызвать `dataavailable` событие, доставляя тем самым последние данные, чтобы вы могли отфильтровать их, сохранить и тд.
6. Запись останавливается автоматически, когда исходное медиа закончит проигрываться.
7. Вы можете остановить запись в любое время, вызвав `MediaRecorder.stop()` (en-US).

Вы можете так же использовать свойства MediaRecorder объекта для определения состояния процесса записи и его `pause()` (en-US) и `resume()` (en-US) методы, чтобы остановить и возобновить запись исходной медиа.

Если вам нужно или вы хотите проверить, поддерживается ли определённый MIME-тип, это так же возможно. Просто вызовите `MediaRecorder.isMimeTypeSupported()`.

Чтобы узнать больше о MediaStream Recording API, смотрите Using the MediaStream Recording API, который показывает, как использовать API для записи аудио клипов. Другая статья, Recording a media element, описывает, как получить поток из `<audio>` или `<video>` элементов и использовать захватывающие потоки (в этом случае, запись и сохранение их на локальный диск).

Ссылки
------

`BlobEvent` (en-US)
`MediaRecorder`Спецификации
------------

| Specification |
| --- |
| MediaStream Recording  |

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

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

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

* Using the MediaStream Recording API
* Recording a media element
* simpl.info MediaStream Recording demo, by Sam Dutton
* `navigator.mediaDevices.getUserMedia()` (en-US)
* HTML5's Media Recorder API in Action on Chrome and Firefox
* TutorRoom: HTML5 video capture/playback/download using getUserMedia and the MediaRecorder API (source on GitHub)
* FingerSpell: Sign Language Fingerspelling practice using getUserMedia and the MediaRecorder API to create and download recordings, MediaRecorder API supported desktop browsers only (source on GitHub)
* Simple video recording demo
* Advanced media stream recorder sample


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

CSSRule
=======

Интерфейс **CSSRule** представляет собой одно правило CSS. Есть несколько типов правил, перечисленных в разделе Type constants ниже.

Интерфейс CSSRule определяет общие свойства для всех правил, в то время как свойства характерные только для определённых типов правил указаны в более специализированных интерфейсах для соответствующих типов этих правил.

Ссылки на CSSRule вы можете получить на странице `CSSStyleSheet` список cssRules.

Общие свойства для всех экземпляров CSSRule
-------------------------------------------

`CSSRule.cssText` (en-US)

Represents the textual representation of the rule, e.g. "`h1,h2 { font-size: 16pt }`" or "`@import 'url'`". To access or modify parts of the rule (e.g. the value of "font-size" in the example) use the properties on the specialized interface for the rule's type.

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

Returns the containing rule, otherwise `null`. E.g. if this rule is a style rule inside an `@media` block, the parent rule would be that `CSSMediaRule` (en-US).

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

Returns the `CSSStyleSheet` object for the style sheet that contains this rule

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

One of the Type constants indicating the type of CSS rule.

Константы
---------

### Типы констант

The `CSSRule` interface specifies integer constants that can be used in conjunction with a `CSSRule`'s `type` (en-US) property to discern the rule type (and therefore, which specialized interface it implements). The relationships between these constants and the interfaces are:

| Type | Value | Rule-specific interface | Comments and examples |
| --- | --- | --- | --- |
| `CSSRule.STYLE_RULE` | `1` | `CSSStyleRule` (en-US) | The most common kind of rule: `selector { prop1: val1; prop2: val2; }` |
| `CSSRule.IMPORT_RULE` | `3` | `CSSImportRule` (en-US) | An `@import` (en-US) rule. (Until the documentation is completed, see the interface definition in the Mozilla source code: nsIDOMCSSImportRule.) |
| `CSSRule.MEDIA_RULE` | `4` | `CSSMediaRule` (en-US) |  |
| `CSSRule.FONT_FACE_RULE` | `5` | `CSSFontFaceRule` (en-US) |  |
| `CSSRule.PAGE_RULE` | `6` | `CSSPageRule` (en-US) |  |
| `CSSRule.KEYFRAMES_RULE` | `7` | `CSSKeyframesRule` (en-US)
Экспериментальная возможность
 |  |
| `CSSRule.KEYFRAME_RULE` | `8` | `CSSKeyframeRule` (en-US)
Экспериментальная возможность
 |  |
| *Reserved for future use* | `9` |  | Should be used to define color profiles in the future |
| `CSSRule.NAMESPACE_RULE` | `10` | `CSSNamespaceRule` (en-US)
Экспериментальная возможность
 |  |
| `CSSRule.COUNTER_STYLE_RULE` | `11` | `CSSCounterStyleRule` (en-US)
Экспериментальная возможность
 |  |
| `CSSRule.SUPPORTS_RULE` | `12` | `CSSSupportsRule` (en-US) |  |
| `CSSRule.DOCUMENT_RULE` | `13` | `CSSDocumentRule`
Экспериментальная возможность
 |  |
| `CSSRule.FONT_FEATURE_VALUES_RULE` | `14` | `CSSFontFeatureValuesRule` (en-US) |  |
| `CSSRule.VIEWPORT_RULE` | `15` | `CSSViewportRule`
Экспериментальная возможность
 |  |
| `CSSRule.REGION_STYLE_RULE` | `16` | `CSSRegionStyleRule`
Экспериментальная возможность
 |  |
| `CSSRule.UNKNOWN_RULE` | `0` | `CSSUnknownRule` |  |
| `CSSRule.CHARSET_RULE` | `2` | `CSSCharsetRule` | (Removed in most browsers.) |

An up-to-date informal list of constants can be found on the CSSWG Wiki.

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

| Specification |
| --- |
| CSS Object Model (CSSOM) # the-cssrule-interface |

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

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

See also
--------

* Using dynamic styling information (en-US)


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

XMLHttpRequest
==============

`XMLHttpRequest` это API, который предоставляет клиенту функциональность для обмена данными между клиентом и сервером. Данный API предоставляет простой способ получения данных по ссылке без перезагрузки страницы. Это позволяет обновлять только часть веб-страницы не прерывая пользователя. `XMLHttpRequest используется в AJAX запросах и особенно в single-page приложениях.`

XMLHttpRequest изначально был разработан Microsoft и позже заимствован Mozilla, Apple, и Google. Сейчас он стандартизирован WHATWG. Несмотря на своё название, `XMLHttpRequest` может быть использован для получения любых типов данных, не только XML, и поддерживает протоколы помимо HTTP (включая `file` и ftp).

Чтобы начать работать с `XMLHttpRequest`, выполните этот код:
```

var myRequest = new XMLHttpRequest();
```

более детальное описание создание объекта, можно увидеть в разделе Using XMLHttpRequest.

Список методов объекта
----------------------

| `XMLHttpRequest(JSObject objParameters);` |
| --- |
| `void abort();` |
| `DOMString getAllResponseHeaders();` |
| `DOMString? getResponseHeader(DOMString header);` |
| `void open(DOMString method, DOMString url, optional boolean async, optional DOMString? user, optional DOMString? password);` |
| `void overrideMimeType(DOMString mime);` |
| `void send();` `void send(ArrayBufferView data);` `void send(Blob data);` `void send(Document data);` `void send(DOMString? data);` `void send(FormData data);` |
| `void setRequestHeader(DOMString header, DOMString value);` |
| Нестандартные методы |
| `[noscript] void init(in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsPIDOMWindow ownerWindow);` |
| `[noscript] void openRequest(in AUTF8String method, in AUTF8String url, in boolean async, in AString user, in AString password);` |
| `void sendAsBinary(in DOMString body);`
Устарело
 |

Поля объекта
------------

| Attribute | Type | Description |
| --- | --- | --- |
| `onreadystatechange` | `Function?` |
 Callback - функция, которая вызывается всякий раз, когда поле
 `readyState меняет своё значение`. Callback выполняется в
 потоке работы приложения.

**Внимание:** Он не должен использоваться в синхронных
 запросах, и не должен выполняться из нативного кода (? must not be
 used from native code).
  |
| `readyState` | `unsigned short` | Состояние запроса:

|  |  |  |
| --- | --- | --- |
| Значение | Состояние | Описание |
| `0` | `UNSENT` | Клиент создан. Метод `open()` ещё не вызван. |
| `1` | `OPENED` |
 Вызван метод open`()`. В этом состоянии можно
 добавить заголовки через метод `setRequestHeader()`;
 вызов метода `send()` отправит запрос.
  |
| `2` | `HEADERS_RECEIVED` |
 Вызван метод `send()`, получены заголовки и код
 ответа (200, 404, 501 и проч.).
  |
| `3` | `LOADING` |
 Загрузка; если значение `responseType` равно "text"
 или пустой строке, то `responseText` содержит
 частичные данные.
  |
| `4` | `DONE` | Операция завершена. Все данные получены. |

 |
| `response` | varies |
 Тело сущности запроса. Согласно полю
 `responseType`, может быть
 `ArrayBuffer`, `Blob`, `Document`, JavaScript объектом (для "json"),
 или строкой. Равно `null` если запрос не завершён или
 окончен с ошибкой.
  |
| `responseText` Только для чтения  | `DOMString` |
 Ответ на запрос в виде строки или `null` в случае если запрос
 не успешен или ответ ещё не получен.
  |
| `responseType` | `XMLHttpRequestResponseType` | Может использоваться для определения типа ответа.

|  |  |
| --- | --- |
| Value | Data type of `response` property |
| `""` (пустая строка) | String (строка, дефолтное значение) |
| `"arraybuffer"` | `ArrayBuffer` |
| `"blob"` | `Blob` |
| `"document"` | `Document` |
| `"json"` |
 JavaScript объект, полученный путём парсинга JSON строки,
 полученной с сервера.
  |
| `"text"` | String (строка) |
| `"moz-blob"` |
 Firefox - велосипед, который позволяет работать с
 частично-полученными данными `Blob` при
 помощи событий прогресса (progressing events). Эта штука
 позволяет работать с ответом от сервера, до того как он получен
 полностью.
  |
| `"moz-chunked-text"` |
 Похоже на поле `"text"`, но только находится в
 потоке(streaming). Это значит, что значение доступно только в
 промежуток времени между событиями прогресса (`"progress"`
 event), и содержит данные которые пришли из последнего события
 прогресса.

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

Работает только в Firefox. |
| `"moz-chunked-arraybuffer"` |
 Похоже на поле `"arraybuffer"`, но только находится
 в потоке(streaming). Это значит, что значение доступно только
 в промежуток времени между событиями прогресса (`"progress"`
 event), и содержит данные которые пришли из последнего события
 прогресса.

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

Работает только в Firefox. |

**Note:** Starting with Gecko 11.0
 , as well as WebKit build 528,
 these browsers no longer let you use the
 `responseType` attribute when performing synchronous
 requests. Attempting to do so throws an
 `NS_ERROR_DOM_INVALID_ACCESS_ERR` exception. This change
 has been proposed to the W3C for standardization.
  |
| `responseXML` Только для чтения  | `Document?` |
 Ответ является объектом DOM
 `Document`, или
 `null в случае если запрос окончился ошибкой, или ответ не получен
полностью, или если ответ невозможно распарсить как` XML или HTML. Ответ парсится как если бы это был
 `text/xml` stream. Когда значение
 `responseType` равно `"document"` и запрос
 выполнен асинхронно, ответ парсится как `text/html` stream.

**Примечание:** Если сервер не работает с заголовком (не
 присылает в ответе) "Content-type: `text/xml"`, то можно
 использовать метод
 `overrideMimeType() для того чтобы парсить получаемый ответ как` XML.
  |
| `status` Только для чтения  | `unsigned short` |
 Статус ответа на запрос. Равен кодам HTTP (200 - успешно, 404 не
 найдено, 301 - перенесено навсегда).
  |
| `statusText` Только для чтения  | `DOMString` |
 Строка статуса ответа. В отличи от поля `status`, эта строка
 включает в себя текст - ("`200 OK`", например).
  |
| `timeout` | `unsigned long` |
 Время в миллисекундах, после которого запрос будет отменён. Значение 0
 (по умолчанию) значит что таймаута не будет. Никогда.

**Примечание:** Вы можете не использовать поле timeout
 для синхронных запросов из owning window.
  |
| `ontimeout` | `Function` | Колбэк-функция которая будет вызвана в случае таймаута. |
| `upload` | `XMLHttpRequestUpload` | Загрузка (upload process) может отслеживаться обработчиком события. |
| `withCredentials` | `boolean` |
 Определяет что cross-site запрос, согласно
 `Access-Control` должен использовать авторизацию (креды для
 логина и пароля) через куки, или заголовок с авторизационными данными.
 По умолчанию false.

**Примечание:** Не влияет на same-site запросы.

**Примечание:** Начиная с Gecko 11.0
 , Gecko больше не позволяет
 использовать поле `withCredentials` при выполнении
 синхронных запросов. Попытка выполнить это выбрасывает
 `NS_ERROR_DOM_INVALID_ACCESS_ERR` исключение.
  |

### Нестандартные свойства

| Attribute | Type | Description |
| --- | --- | --- |
| `channel` Только для чтения  | `nsIChannel` |
 The channel used by the object when performing the request. This is
 `null` if the channel hasn't been created yet. In the case of
 a multi-part request, this is the initial channel, not the different
 parts in the multi-part request.
 **Requires elevated privileges to access.** |
| `mozAnon` Только для чтения  | `boolean` |
 Если значение равно true, запрос отправляется без куки и заголовков
 авторизации.
  |
| `mozSystem` Только для чтения  | `boolean` |
 Если значение равно true, same origin policy не будут использоваться в
 запросе (кроссдоменный запрос не сработает).
  |
| `mozBackgroundRequest` | `boolean` |

 Этот метод не может быть вызван из контекста страницы. Для того
 чтобы воспользоваться им нужны повышенные привелегии (elevated
 privileges).

 Флаг, означающий что запрос от пользователя надо скрыть. Для
 пользователя не появится никаких сообщений и/или оповещений что запрос
 вообще был.

 В случае, если для продолжения запроса нужна какая-то аутентификация,
 и в других случаях было бы отображено оповещение, этот запрос просто
 не сработает.

**Note: Этот флаг должен быть выставлен до вызова метода** `open()`. |
| `mozResponseArrayBuffer`
Только для чтения  | `ArrayBuffer` |
 Массив, в который ляжет ответ от сервера, если ответ приходит в виде
 Javascript массива ([]). В случае, если запрос не удалось завершить, или
 если запрос не был отправлен, то это поле будет null.
  |
| `multipart` | `boolean` |
**This Gecko-only feature was removed in Firefox/Gecko 22.**
 Please use
 Server-Sent Events (en-US),
 Web Sockets, or `responseText` from progress events instead.

 Indicates whether or not the response is expected to be a stream of
 possibly multiple XML documents. If set to `true`, the
 content type of the initial response must be
 `multipart/x-mixed-replace` or an error will occur. All
 requests must be asynchronous.

 This enables support for server push; for each XML document that's
 written to this request, a new XML DOM document is created and the
 `onload` handler is called between documents.

**Note:** When this is set, the
 `onload` handler and other event handlers are not reset
 after the first XMLdocument is loaded, and the
 `onload` handler is called after each part of the response
 is received.
  |

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

### XMLHttpRequest()

Конструктор создаёт объект XMLHttpRequest. Он должен быть вызван перед обращением к любому методу класса.

Gecko/Firefox 16 добавляет нестандартные параметры в конструктор, для лучшего взаимодействия с режимом инкогнито, (смотри Bug 692677). Установка флага `mozAnon` в значение `true` создаёт сущность `AnonXMLHttpRequest()` описанную в XMLHttpRequest спецификации, но не реализованную не в одном из браузеров (информация сентября 2012).
```

XMLHttpRequest (
  JSObject objParameters
);
```

##### Параметры (нестандартные)

`objParameters`

Вы можете использовать два флага:

`mozAnon`

Boolean: Использование этого флага уберёт из запроса заголовки origin, и user credentials. Кроме этого, куки не будут отправлены в запросе, если только они не будут добавлены к запросу специально, через метод setRequestHeader.

`mozSystem`

Boolean: Если выставить этот флаг в значение `true` то это позволит делать cross-доменные запросы без необходимости получения специальных заголовков со стороны сервера (CORS). Для использования этого флага необходимо использовать дополнительный флаг\* `mozAnon: true`, поскольку для отправки запроса на другой домен, нельзя использовать куки и креды пользователя. Этот флаг работает только с привилегированными (одобренными) приложениями; он не сработает с произвольно загруженными страницами.\*

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

### abort()

Отменяет запрос, если он был отправлен.

### getAllResponseHeaders()
```

DOMString getAllResponseHeaders();
```

Возвращает все заголовки ответа как строку, или `null` если ответ не был получен. Для multypart запросов возвращает заголовки текущей части запроса, а не всего канала.

### getResponseHeader()
```

DOMString? getResponseHeader(DOMString header);
```

Возвращает значение указанного заголовка из полученного ответа, или `null` в случает если ответ не получен, или такого заголовка в ответе нет. Возвращаемая строка имеет кодировку UTF.

**Примечание:** `Примечание: Если в ответе есть заголовки с одни названием, то значения этих заголовков будут объеденены в одну строку, разделённую запятой и пробелом.`

### open()

Инициализирует запрос. Этот метод может (и должен) быть вызван из JavaScript-кода; если необходимо вызвать запрос из нативного кода, то нужно использовать метод `openRequest()`.

**Примечание:** Вызов этого метода из активного запроса (если метод `open() или` `openRequest() уже были вызваны`) эквивалентно вызову метода `abort()`.
```

void open(
   DOMString method,
   DOMString url,
   optional boolean async,
   optional DOMString user,
   optional DOMString password
);
```

###### Параметры

`method`

HTTP метод отправки сообщения - "GET", "POST", "PUT", "DELETE", и проч.. Ignored for non-HTTP(S) URLs.

`url`

URL адрес, на который будет отправлено сообщение.

`async`

Необязательный boolean параметр, по умолчанию равный `true`. Определяет, будет ли запрос отправлен асинхронно. Если значение равно `false`, метод `send()` вернёт ответ в общем потоке работы приложения (иначе говоря, приложение зависнет на некоторое время), в противном случае, ответ может быть получен только при помощи определённых обработчиков событий. В случае, если используется отправка `multipart` запроса, то этот атрибут **должен** быть `true`, или будет выброшено исключение.

**Примечание:** Начиная с Gecko 30.0, синхронные запросы объявлены как deprecated, в силу того что все пользователи недовольны тем, что приложение "зависает".

`user`

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

`password`

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

### overrideMimeType()

Переопределяет MIME тип, получаемый от сервера. Это может быть использовано, например, для того чтобы получить и распарсить данные в формате text/xml, даже, если сервер сообщает что это не так. Этот метод должен быть вызван перед вызовом метода `send()`.
```

void overrideMimeType(DOMString mimetype);
```

### send()

Отправляет запрос. Если запрос асинхронный (а по умолчанию это так), этот метод вернёт значение сразу после того как метод вызван.

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

Если запрос синхронный, то метод вернёт значение только после того, как придёт запрос от сервера.

**Примечание:** все необходимые обработчики событий должны быть установлены перед вызовом `send()`.

**Примечание:** Лучше не использовать параметр ArrayBuffer. Сейчас он не входит в спецификацию `XMLHttpRequest`. Вместо него можно использовать ArrayBufferView (смотри таблицу совместимости для различных версий).
```

void send();
void send(ArrayBuffer data);
void send(ArrayBufferView data);
void send(Blob data);
void send(Document data);
void send(DOMString? data);
void send(FormData data);
```

###### Примечания

Если тип *data* - `Document`, то он будет сериализован перед отправкой. Firefox до версии 3 всегда отправляет такой запрос в кодировке UTF-8; Firefox 3 отправляет данные в той кодировке, которая указаны в `body.xmlEncoding`, или UTF-8 если такой информации нет.

If it's an `nsIInputStream`, it must be compatible with `nsIUploadChannel`'s `setUploadStream()` method. In that case, a Content-Length header is added to the request, with its value obtained using `nsIInputStream`'s `available()` method. Any headers included at the top of the stream are treated as part of the message body. The stream's MIMEtype should be specified by setting the Content-Type header using the `setRequestHeader()` method prior to calling `send()`.

The best way to send binary content (like in files upload) is using an ArrayBufferView (en-US) or Blobs (en-US) in conjuncton with the `send()` method. However, if you want to send a stringifiable (en-US) raw data, use the `sendAsBinary()` (en-US) method instead, or the `StringView` Non native typed arrays superclass.

### setRequestHeader()

Устанавливает значение заголовка HTTP-запроса. Вы должны вызвать `setRequestHeader()` после `open()`, но перед `send()`. Если данный метод вызывается несколько раз с одним и тем же заголовком, все значения объединяются в один заголовок запроса.
```

void setRequestHeader(
   DOMString header,
   DOMString value
);
```

###### Параметры

`header`

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

`value`

Значение, заданное как тело заголовка.

### Нестандартные методы

#### init()

Инициализирует объект для использования с C++ кодом.

**Предупреждение:** **Внимание:** Этот метод ***нельзя*** вызывать из JavaScript.
```

[noscript] void init(
   in nsIPrincipal principal,
   in nsIScriptContext scriptContext,
   in nsPIDOMWindow ownerWindow
);
```

##### Параметры

`principal`

Принцип, используемый для запроса; не должен быть `null`.

`scriptContext`

Контекст скрипта, используемого для запроса; не должен быть `null`.

`ownerWindow`

Окно, связанное с запросом; может быть `null`.

#### openRequest()

Инициализирует запрос. Этот метод должен использоваться из собственного кода; для инициализации запроса из кода JavaScript вместо этого используйте используйте `open()` метод. Смотрите документацию для `open()`.

#### sendAsBinary()
Устарело

Вариант метода `send()` который посылает бинарные данные.

**Примечание:** Этот нестандартный метод считается устарелым по состоянию на Gecko 31, и со временем будет удалён. Взамен может использоваться стандарт метода `send(Blob data).`
```

void sendAsBinary(
   in DOMString body
);
```

Данный метод используется в сочетании с методом `readAsBinaryString,` который присутствует в `FileReader` (en-US) API, и позволяет прочитать и **загрузить** файл любого типа (en-US) и превратить необработанные данные в JSON-строку (en-US).

##### Параметры

`body`

Тело запроса в виде DOMstring. Эти данные конвертированы в строку с однобайтовыми символами с помощью усечения (удаления байта с высоким порядком в каждом символе).

##### `sendAsBinary()` polyfill

Since `sendAsBinary()` is an experimental feature, here is **a polyfill** for browsers that *don't* support the `sendAsBinary()` method but support typed arrays (en-US).

```js
/\*\
|\*|
|\*| :: XMLHttpRequest.prototype.sendAsBinary() Polyfill ::
|\*|
|\*| https://developer.mozilla.org/ru/docs/DOM/XMLHttpRequest#sendAsBinary()
|\*|
\\*/

if (!XMLHttpRequest.prototype.sendAsBinary) {
  XMLHttpRequest.prototype.sendAsBinary = function (sData) {
    var nBytes = sData.length,
      ui8Data = new Uint8Array(nBytes);
    for (var nIdx = 0; nIdx < nBytes; nIdx++) {
      ui8Data[nIdx] = sData.charCodeAt(nIdx) & 0xff;
    }
    /\* send as ArrayBufferView...: \*/
    this.send(ui8Data);
    /\* ...or as ArrayBuffer (legacy)...: this.send(ui8Data.buffer); \*/
  };
}
```

**Примечание:** It's possible to build this polyfill putting two types of data as argument for `send()`: an `ArrayBuffer` (en-US) (`ui8Data.buffer` – the commented code) or an `ArrayBufferView` (en-US) (`ui8Data`, which is a typed array of 8-bit unsigned integers (en-US) – uncommented code). However, on Google Chrome, when you try to send an `ArrayBuffer`, the following warning message will appear: `ArrayBuffer is deprecated in XMLHttpRequest.send(). Use ArrayBufferView instead.` Another possible approach to send binary data is the `StringView` Non native typed arrays superclass in conjunction with the `send()` method.

Notes
-----

* By default, Firefox 3 limits the number of `XMLHttpRequest` connections per server to 6 (previous versions limit this to 2 per server). Some interactive web sites may keep an `XMLHttpRequest` connection open, so opening multiple sessions to such sites may result in the browser hanging in such a way that the window no longer repaints and controls don't respond. This value can be changed by editing the `network.http.max-persistent-connections-per-server` preference in `about:config`.
* From Gecko 7.0 headers set by setRequestHeader are sent with the request when following a redirect. Previously these headers would not be sent.
* `XMLHttpRequest` is implemented in Gecko using the `nsIXMLHttpRequest`, `nsIXMLHttpRequestEventTarget`, and `nsIJSXMLHttpRequest` interfaces.
* When a request reaches its timeout value, a "timeout" event is raised.

#### Events

`onreadystatechange` as a property of the `XMLHttpRequest` instance is supported in all browsers.

Since then, a number of additional event handlers were implemented in various browsers (`onload`, `onerror`, `onprogress`, etc.). These are supported in Firefox. In particular, see `nsIXMLHttpRequestEventTarget` and Using XMLHttpRequest.

More recent browsers, including Firefox, also support listening to the `XMLHttpRequest` events via standard `addEventListener` APIs in addition to setting `on*` properties to a handler function.

Permissions
-----------

When using System XHR via the `mozSystem` property, for example for Firefox OS apps, you need to be sure to add the `systemXHR` permission into your manifest file. System XHR can be used in privileged or certified apps.

```js
"permissions": {
    "systemXHR":{}
}
```

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

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

See also
--------

* MDN articles about XMLHttpRequest:
    + AJAX - Getting Started
    + Using XMLHttpRequest
    + HTML in XMLHttpRequest
    + `FormData`
* XMLHttpRequest references from W3C and browser vendors:
    + W3C: XMLHttpRequest (base features)
    + W3C: XMLHttpRequest (latest editor's draft with extensions to the base functionality, formerly XMLHttpRequest Level 2
    + Microsoft documentation
    + Apple developers' reference
* "Using the XMLHttpRequest Object" (jibbering.com)
* XMLHttpRequest - REST and the Rich User Experience
* HTML5 Rocks - New Tricks in XMLHttpRequest2
* Thread on the naming convention of `XMLHttpRequest`
* `Chrome scope availability` - how to access from JSM modules etc which do not have access to DOM
    + Components.utils.importGlobalProperties
    + nsIXMLHttpRequest [en-US]


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

BroadcastChannel
================

Baseline 2022
-------------

Newly availableSince March 2022, 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
Интерфейс **`BroadcastChannel`** представляет собой именованный канал, на который можно подписаться из любого контекста просмотра данного источника. Это позволяет настроить коммуникацию между разными документами (в разных окнах, вкладках, фреймах и т.д.) одного источника. Сообщения распространяются с помощью события `message`, выстреливающего для всех объектов `BroadcastChannel`, слушающих этот канал.

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

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

`BroadcastChannel()` (en-US)

Создаёт объект, связанный с именованным каналом.

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

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

`BroadcastChannel.name` (en-US)

Возвращает `DOMString`, имя канала.

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

`BroadcastChannel.onmessage` (en-US)

`event handler` свойство, определяющее функцию, которая будет запущена, когда произойдёт вызов события `message` на этом объекте.

`BroadcastChannel.onmessageerror` (en-US)

`event handler`, который вызывается, когда приходит `MessageEvent` (en-US) типа `MessageError` — когда приходит сообщение, которое не может быть десереализовано.

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

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

`BroadcastChannel.postMessage()`

Отправляет сообщение любого типа объекта всем объектам `BroadcastChannel`, прослушивающим данный канал.

`BroadcastChannel.close()` (en-US)

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

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

| Specification |
| --- |
| HTML Standard # broadcasting-to-other-browsing-contexts |

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

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

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

* Another, more heavyweight, way of communicating between browser contexts: `ServiceWorker`.
* Broadcast Channel API overview (en-US)


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

XMLSerializer
=============

`XMLSerializer` может быть использован для конвертации веток DOM-дерева или дерева целиком в текст. `XMLSerializer` доступен непривилегированным скриптам.

Для получения более подробной информации об `XMLSerializer` в расширениях для браузера Firefox, пожалуйста обратитесь к документации `nsIDOMSerializer`.

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

`XMLSerializer.serializeToString()`

Возвращает сериализованное дерево или ветку в виде строки

`XMLSerializer.serializeToStream()`
Non-standard

Устарело

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

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

```js
var s = new XMLSerializer();
var d = document;
var str = s.serializeToString(d);
alert(str);
```

The next example uses XMLSerializer with insertAdjacentHTML() (en-US) to insert a newly created DOM Node into the Document's body. Because insertAdjacentHTML() (en-US) accepts a string and not a Node for its second parameter, XMLSerializer is used to first convert the node into a string.

```js
var inp = document.createElement("input");
var XMLS = new XMLSerializer();
var inp_xmls = XMLS.serializeToString(inp); // Конвертируем DOM-элемент в строку

// Вставляет вновь созданный элемент в тело документа
document.body.insertAdjacentHTML("afterbegin", inp_xmls);
```

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

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

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

* Parsing and serializing XML
* XMLHttpRequest
* DOMParser


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

WebVR API
=========

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

WebVR обеспечивает поддержку для использования устройств виртуальной реальности — например, шлемы виртуальной реальности, таких как Oculus Rift или HTC Vive — для веб-приложений, позволяя разработчикам передавать информацию о местоположении и движения с дисплея в движение вокруг 3D-сцены. Это имеет множество интересных приложений, от виртуальных туров продукта и интерактивных обучающих приложений до захватывающих игр от первого лица.

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

Любые VR-устройства, подключённые к вашему компьютеру, будут возвращены методом `Navigator.getVRDisplays()`; каждое из которых будет представлено `VRDisplay` (en-US) объектом.

![Sketch of a person in a chair with wearing goggles labelled "Head mounted display (HMD)" facing a monitor with a webcam labelled "Position sensor"](/ru/docs/Web/API/WebVR_API/hw-setup.png)

`VRDisplay` (en-US) является центральным интерфейсом в API WebVR - с помощью его свойств и методов вы получить доступ к функциям:

* Получить полезную информацию, чтобы мы могли идентифицировать дисплей, какие возможности он имеет, контроллеры, связанные с ним и многое другое.
* Получить `frame data` для каждого кадра контента, который вы хотите представить на дисплее, и отправьте эти кадры для отображения с постоянной скоростью.
* Начать и прекратить подачу на дисплей.

Типичное (простое) WebVR приложение будет работать так:

1. `Navigator.getVRDisplays()` используется для получения ссылки на ваш VR-дисплей.
2. `VRDisplay.requestPresent()` используется для начала представления на дисплей VR.
3. Выделенный `VRDisplay.requestAnimationFrame()` WebVR's используется для запуска цикла рендеринга приложения с правильной частотой обновления для отображения.
4. Внутри цикла рендеринга берутся данные, необходимые для отображения текущего кадра (`VRDisplay.getFrameData()` (en-US)), дважды нарисуйте отображаемую сцену - один раз для просмотра в каждом глазу, затем отправьте отображаемый вид на дисплей, чтобы показать пользователю (`VRDisplay.submitFrame()` (en-US)).

Кроме того, WebVR 1.1 добавляет ряд событий `Window` объекту, чтобы JavaScript мог реагировать на изменения состояния дисплея.

**Примечание:** вы можете найти намного больше о том, как работает API в Using the WebVR API и WebVR Concepts (en-US) статьях.

### Использование контроллеров: Объединение WebVR с API-интерфейсом геймпада

Многие аппаратные настройки WebVR оснащены контроллерами, которые сочетаются с гарнитурой. Они могут быть использованы в WebVR приложениях через Gamepad API, и, в частности, Gamepad расширения API, которые добавляют API функции для доступа к позе контроллера (en-US), haptic actuators (en-US), и многое другое.

**Примечание:** Наша Using VR controllers with WebVR (en-US) статья объясняет основы использования VR-контроллеров в приложениях WebVR.

WebVR Интерфейс
---------------

`VRDisplay` (en-US)

Представляет любое устройство VR, поддерживаемое этим API. VRDisplay включает в себя общую информацию, такую как идентификаторы устройств и описания, а также методы для начала представления сцены VR, получения параметров глаз и возможностей отображения и других важных функций.

`VRDisplayCapabilities`

описывает возможности `VRDisplay` (en-US) — его функции могут использоваться для тестирования возможностей устройства VR, например, может ли он возвращать информацию о местоположении.

`VRDisplayEvent`

Возвращает объект события (event) связанного с WebVR-событием (см. window object extensions , перечисленных ниже).

`VRFrameData`

Представляет всю информацию, необходимую для создания одного кадра сцены VR; созданный от `VRDisplay.getFrameData()` (en-US).

`VRPose` (en-US)

Представляет состояние позиции на заданной временной отметке (которая включает в себя ориентацию, положение, скорость и ускорение).

`VREyeParameters` (en-US)

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

`VRFieldOfView` (en-US)

Представляет поле зрения, определённое четырьмя различными значениями степени, описывающими представление из центральной точки.

`VRLayerInit` (en-US)

Представляет слой, который должен быть представлен в `VRDisplay` (en-US).

`VRStageParameters` (en-US)

Представляет значения, описывающие область сцены для устройств, поддерживающих опыт в помещении.

### Расширения для других интерфейсов

WebVR API расширяет следующие API, добавляя перечисленные функции.

#### Геймпад

`Gamepad.displayId` Только для чтения

*Возвращает `VRDisplay.displayId` (en-US) связанного с `VRDisplay` (en-US) — `VRDisplay` , которым геймпад управляет отображаемой сценой.*

#### Навигатор

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

Возвращает массив, содержащий каждый `VRDisplay` (en-US) объект, который в настоящее время отображается (`VRDisplay.ispresenting` (en-US) является `true`).

`Navigator.getVRDisplays()`

Возвращает промис, который преобразуется в массив `VRDisplay` (en-US) объектов, представляющих любые доступные VR-дисплеи, подключённые к компьютеру.

#### Window события

`Window.onvrdisplaypresentchange` (en-US)

Представляет обработчик событий, который будет выполняться, при изменении состояния отображения VR-дисплея — т.е. идёт от отображения до неотображения, или наоборот (когда `vrdisplaypresentchange` событие срабатывает).

`Window.onvrdisplayconnect` (en-US)

Представляет обработчик событий, который будет запускаться, когда к компьютеру подключён совместимый VR-дисплей (когда `vrdisplayconnect` событие срабатывает).

`Window.onvrdisplaydisconnect` (en-US)

Представляет обработчик событий, который будет запускаться, когда совместимый VR-дисплей был отключён от компьютера (когда `vrdisplaydisconnect` событие срабатывает).

`Window.onvrdisplayactivate` (en-US)

Представляет обработчик событий, который будет выполняться, когда дисплей может быть представлен (когда `vrdisplayactivate`событие срабатывает), например, HMD (Head Mounted Display) был перемещён, чтобы вывести его из режима ожидания, или проснулся, будучи перемещённым.

`Window.onvrdisplaydeactivate` (en-US)

Представляет обработчик событий, который будет запускаться, когда дисплей больше не будет отображаться (когда `vrdisplaydeactivate` событие срабатывает), например, HMD (Head Mounted Display) перешёл в режим ожидания или спящий режим из-за периода бездействия.

#### Невыполненные window события

Следующие события перечислены в спецификации, but do not currently seem to be implemented anywhere as yet.

`Window.onvrdisplayblur` (en-US)

Представляет обработчик событий, который будет выполняться, когда презентация на дисплей была приостановлена по какой-то причине в браузере, ОС или оборудованием VR (когда `vrdisplayblur` событие срабатывает) — например, в то время как пользователь взаимодействует с системным меню или браузером, чтобы предотвратить отслеживание или потерю опыта.

`Window.onvrdisplayfocus` (en-US)

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

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

Вы можете найти несколько примеров в этих местах:

* webvr-tests — очень простые примеры для сопровождения MDM WebVR документации.
* Carmel starter kit — простые, хорошо прокомментированные примеры, которые идут вместе с Carmel,браузером WebVR от Facebook's .
* WebVR.info samples — несколько более подробных примеров плюс исходный код
* WebVR.rocks Firefox demos — демонстрация примеров
* A-Frame homepage — примеры использования A-Frame
Совместимость с браузерами
--------------------------

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

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

* vr.mozilla.org — Основная посадочная площадка Mozilla для WebVR с демонстрационными материалами, утилитами и другой информацией.
* A-Frame — Веб-платформа с открытым исходным кодом для создания опыта VR.
* webvr.info — Актуальная информация о WebVR, настройке браузера и сообществе.
* threejs-vr-boilerplate — Полезный стартовый шаблон для написания приложений WebVR.
* Web VR polyfill — JavaScript-реализация WebVR.


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

HTMLBaseElement
===============

**`HTMLBaseElement`** интерфейс содержит базовый URI для документа. Этот объект наследует все свойства и методы которые описаны в `HTMLElement` интерфейсе.

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

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

`HTMLBaseElement.href`

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

`HTMLBaseElement.target` (en-US)

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

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

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

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

| Specification |
| --- |
| HTML Standard # htmlbaseelement |

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

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

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

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


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

USB
===

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

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

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

Интерфейс **`USB`** WebUSB API (en-US) представляет атрибуты и методы для поиска и подключения USB устройств из WEB страницы.

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

Нет.

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

`USB.onconnect`

Обработчик событий вызывается всегда, когда ранее сопряжённое устройство подключается.

`USB.ondisconnect`

Обработчик событий вызывается всегда, когда ранее сопряжённое устройство отключается.

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

`USB.getDevices()`

Возвращает `Promise`, который разрешается массивов объектов `USBDevice` (en-US) сопряжённых устройств.

`USB.requestDevice()`

Возвращает `Promise`, который разрешается экземпляром `USBDevice` (en-US), если указанное устройство найдено. Вызов этой функции запускает поток сопряжения агента пользователя.

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

| Specification |
| --- |
| WebUSB API # usb |

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

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


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

Web Crypto API
==============

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

**Web Crypto API** – интерфейс, позволяющий использовать криптографические примитивы для построения систем, манипулировать, хранить секретные ключи без необходимости делать доступными базовые биты ключа для JavaScript.

Интерфейс открывает доступ к следующим примитивам:

* *digest*, the ability to compute a hash of an arbitrary block of data, in order to detect any change in it.
* *mac*, the ability to compute a message authentication code.
* *sign* и *verify*, the ability to digitally sign a document, and to verify a signature.
* *encrypt* и *decrypt*, the ability to encode or decode a document.
* *import* и *export*, the ability to import a key or export a key.
* *key generation*, the ability to create a cryptographically secure key, or key pair, without the use of base key, but using the available entropy of the local system.
* *key wrapping* and *unwrapping*, the ability to transmit, and to receive, a key from a third party, encoded using another key, without exposing the underlying key to JavaScript.
* *random*, способность генерировать криптографически достоверные псевдослучайные числа.

Web Crypto API не решает всех проблем, которые касаются использования криптографии на Web-сайтах или приложениях:

* Она не заменяет "собственной модели безопасности" браузера (когда на некоторых Web-сайтах используются свои собственные ключи).
* Оно не взаимодействует со специальным аппаратным обеспечением (смарт-карты, USB-ключи или генераторы случайных чисел).

**Предупреждение:** **Внимание!**

* Само по себе использование криптографии не делает систему безопасной. Безопасность – это **процесс** постоянной оценки рисков, возникающих в контексте эксплуатации системы. Контекст, как и риски, изменяются с течением времени.
* When dealing with security, the whole **system** must be considered. In the case of the Web Crypto API, Web developers shouldn't consider only the security of the script, but the security of the connection to the server, because using Web Crypto over HTTP is not secure. The overall security can't be stronger than the security of the weakest part of the overall system.

Интерфейсы
----------

Некоторые браузеры реализовали интерфейс `Crypto`, но сделали это недостаточно точно или без должного уровня безопасности. Чтобы избежать конфуза с модулем `Crypto` из пакета Node, методы и свойства интерфейса были перенесены в новый интерфейс: `SubtleCrypto`. Свойство `Crypto.subtle` (en-US) даёт доступ к объекту, реализующему Web Crypto API.

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

Web Crypto API может использоваться для:

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

| Specification |
| --- |
| Web Cryptography API |

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

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


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

HTMLAnchorElement
=================

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

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

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

`HTMLAnchorElement.accessKey`

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

`HTMLAnchorElement.charset`

Это `DOMString` отображает кодировку символов связанного ресурса.

`HTMLAnchorElement.coords`

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

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

Это `DOMString` показывать что связанный ресурс предназначен для загрузки, а не для отображения в браузере. Значение представляет предполагаемое имя файла. Если имя не является допустимым именем файла нижележащей ОС, браузер будет адаптировать его. Значение это URL по схеме `http:`, `file:`, `data:` или даже `blob:` (созданный с помощью `URL.createObjectURL`).

`URLUtils.hash`

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

`URLUtils.host`

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

`URLUtils.hostname`

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

`URLUtils.href`

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

`HTMLAnchorElement.hreflang` (en-US)

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

`HTMLAnchorElement.media`

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

`HTMLAnchorElement.name`

Это `DOMString` отображает имя якоря.

`URLUtils.password`

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

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

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

`URLUtils.pathname`

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

`URLUtils.port`

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

`URLUtils.protocol`

Is a `DOMString` отображающий составную часть протокола, включая двоеточия ('`:`'), ссылающегося URL.

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

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

`HTMLAnchorElement.rel` (en-US)

Это `DOMString` что отображает `rel` HTML атрибут, уточняя взаимоотношения целевого объекта к связанному объекту.

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

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

`HTMLAnchorElement.rev`

Это `DOMString` отображающий как `rev` HTML атрибут, уточняя взаимоотношения связанного объекта к целевому объекту

`URLUtils.search`

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

`HTMLAnchorElement.shape`

Это `DOMString` отображающий вид активной области.

`HTMLAnchorElement.tabindex`

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

`HTMLAnchorElement.target` (en-US)

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

`HTMLAnchorElement.text`

Это `DOMString` является синонимом `Node.textContent` свойства.

`HTMLAnchorElement.type`

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

`URLUtils.username`

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

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

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

`HTMLElement.blur()` (en-US)

Удаляет фокус клавиатуры из текущего элемента.

`HTMLElement.focus()` (en-US)

Даёт фокус клавиатуры на текущий элемент.

`URLUtils.toString()`

Возвращает `DOMString` содержащий весь URl. Это синоним `URLUtils.href`, хотя он не может быть использован для изменения значения.

`blur()` и `focus()` методы наследуемые от `HTMLElement` для HTML5, но они были определены в `HTMLAnchorElement` в DOM Level 2 HTML и более ранней спецификации.

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

| Specification |
| --- |
| HTML Standard # htmlanchorelement |

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

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

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

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


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

Console
=======

Объект **Console** служит для доступа к средствам отладки браузера (например, Web Console (Веб-консоль) в Firefox). Работа с ним отличается в разных браузерах, но эти методы и свойства по факту поддерживаются всеми браузерами.

Доступ к **Console** можно получить через свойство глобального объекта, то есть: `Window` в браузере (в JavaScript), `WorkerGlobalScope` (en-US) — в `workers` это специальный способ доступа через свойство `console`. Он известен как `Window.console`, и на него ссылаются для простоты так: "`console`".

```js
console.log("Failed to open the specified link");
```

Ниже описаны методы, доступные в объекте Console и приведены несколько примеров их использования.

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

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

`console.assert()`

Выводит в консоль (имеется ввиду веб-консоль) сообщение и стек вызова метода, если первый аргумент `false`.

`console.clear()`

Очистка консоли.

`console.count()`

Выводит количество вызовов метода с определённой меткой (передаётся в параметре метода)

`console.countReset()`

Обнуляет значение счётчика с заданным значением.

`console.debug()`

Синоним для `log()`

`console.dir()`
Non-standard

Отображает интерактивный список свойств указанного объекта JavaScript. Этот список позволит вам посмотреть дочерние объекты и их свойства.

`console.dirxml()`
Non-standard

Отображает представление указанного объекта в XML/HTML-виде, если это возможно. Если нет - в виде JavaScript-объекта (как в виде "console.dir()").

`console.error()`

Выводит сообщение об ошибке. Для форматирования вы можете использовать подстановочные символы (маски) с дополнительными параметрами.

`console._exception()`
Non-standard

Устарело

Синоним для `error();`

`console.group()`

Создаёт новую группировку сообщений, сдвигая все следующие выводимые строки вправо на один уровень. Для завершения группы вызовите `groupEnd()`.

`console.groupCollapsed()` (en-US)

Создаёт новую группировку сообщений, сдвигая все следующие сообщения вправо на один уровень; в отличие от `group()` вывод происходи в свёрнутую группу, требующую раскрыть её вручную по кнопке. Для завершения группывызовите `groupEnd()`.

`console.groupEnd()` (en-US)

Выход из текущей группы.

`console.info()`

Информационное сообщение. Для форматирования вы можете использовать подстановочные символы (маски) с дополнительными параметрами.

`console.log()`

Общий метод вывода информации. Для форматирования вы можете использовать подстановочные символы (маски) с дополнительными параметрами.

`console.profile()`
Non-standard

Запускает профайлер, встроенный в браузер (например, Firefox performance tool). Вы можете указать метку профиля (по желанию).

`console.profileEnd()` (en-US)
Non-standard

Останавливает профайлер.Вы можете посмотреть результат в инструментах анализа производительности браузера (например, Firefox performance tool).

`console.table()`

Отображает табличные данные в виде таблицы.

`console.time()`

Запускает таймер с именем из переданного параметра. Можно запустить одновременно до 10,000 таймеров на странице.

`console.timeEnd()`

Останавливает указанный таймер и записывает в лог, сколько прошло секунд от его старта.

`console.timeStamp()`
Non-standard

Ставит маркер в браузерном инструменте измерения производительности Timeline или Waterfall.

`console.trace()`

Вывод трассировки стека.

`console.warn()`

Выводит предупреждающее сообщение. Для форматирования вы можете использовать подстановочные символы (маски) с дополнительными параметрами.

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

### Вывод текста в консоль

Чаще всего Консоль используется для вывода строк текста и других типов данных. Существует четыре категории вывода, которые вы можете создавать, используя функции `console.log()`, `console.info()`, `console.warn()`, `console.error()`. Их вывод стилизован по-разному, и вы можете использовать фильтры, предоставляемые браузером, чтобы видеть только интересующие вас вещи.

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

#### Вывод одного объекта

Простейший способ для вывода одного объекта:

```js
var someObject = { str: "Some text", id: 5 };
console.log(someObject);
```

Вывод будет таким:
```

[09:27:13.475] ({str:"Some text", id:5})
```

#### Вывод нескольких объектов

Вы можете выводить несколько объектов, просто перечисляя их в вызываемой функции:

```js
var car = "Dodge Charger";
var someObject = { str: "Some text", id: 5 };
console.info("My first car was a", car, ". The object is: ", someObject);
```

Вывод будет таким:
```

[09:28:22.711] My first car was a Dodge Charger . The object is:  ({str:"Some text", id:5})
```

#### Преобразование строк с использованием масок

Gecko 9.0 ввёл поддержку подстановочных символов (масок). При передаче строки одному из методов вы можете использовать следующие символы:

| Подстановочный символ | Описание |
| --- | --- |
| %o или %O | Выводит ссылку на JavaScript-объект. Нажатие на ссылку приведёт к открытию инспектора кода. |
| %d или %i | Выведет целое число. Поддерживается форматирование, например, console.log("АБВГД %.2d", 1.1) выведет число как две значащих цифры с лидирующим нулём: АБВГД 01 |
| %s | Выводит строку. |
| %f | Выводит число с плавающей точкой. Поддерживается форматирование, например, console.log("АБВГД %.2f", 1.1) выведет число до двух знаков после запятой: АБВГД 1.10 |

Каждая из масок выбирает следующий аргумент из списка параметров. Пример:
```

for (var i=0; i<5; i++) {
  console.log("Hello, %s. You've called me %d times.", "Bob", i+1);
}
```

Вывод будет таким:
```

[13:14:13.481] Hello, Bob. You've called me 1 times.
[13:14:13.483] Hello, Bob. You've called me 2 times.
[13:14:13.485] Hello, Bob. You've called me 3 times.
[13:14:13.487] Hello, Bob. You've called me 4 times.
[13:14:13.488] Hello, Bob. You've called me 5 times.
```

#### Стилизация вывода консоли

Можно использовать директиву `"%c"` для применения стилей CSS при выводе в консоль. Часть текста до директивы не затрагивается стилем, а часть после - будет стилизована:

```js
console.log(
  "This is %cMy stylish message",
  "color: yellow; font-style: italic; background-color: blue; padding: 2px;",
);
```

![](/ru/docs/Web/API/console/css-styling.png)

**Примечание:** Поддерживается довольно много свойств стилей CSS; но вам необходимо поэкспериментировать и посмотреть, что окажется более полезным.

### Группирование вывода в консоли

Вы можете использовать вложенные группы для организации вывода, визуально комбинируя связанный материал. Для создания вложенного блока вызовите `console.group()`. Метод `console.groupCollapsed()` похожий, но создаёт новый блок свёрнутым, что потребует нажать на кнопку, для своего раскрытия для чтения.

**Примечание:** Свёрнутые группы не поддерживаются пока в Gecko; в настоящее время `метод groupCollapsed()` работает так же как и `group()`.

Для выхода из текущей группы просто вызовите `console.groupEnd()`. Пример:

```js
console.log("This is the outer level");
console.group();
console.log("Level 2");
console.group();
console.log("Level 3");
console.warn("More of level 3");
console.groupEnd();
console.log("Back to level 2");
console.groupEnd();
console.debug("Back to the outer level");
```

Вывод будет таким:

![Демонстрация вложенных групп в консоли Firefox](/ru/docs/Web/API/console/console_groups_demo.png)

### Таймеры

Для расчёта длительности определённых операций в Gecko 10 введена поддержка таймеров в объекте `console`. Для запуска таймера вызовите функцию `console.time()`, при этом в качестве параметра передайте название таймера. Для остановки таймера и для получения прошедшего времени в миллисекундах вызовите `console.timeEnd()`, передав в качестве параметра имя таймера. На странице можно запустить до 10000 таймеров одновременно.

Рассмотрим пример:

```js
console.time("answer time");
alert("Click to continue");
console.timeEnd("answer time");
```

этот код запишет в веб-консоль время необходимое пользователю для того, чтобы закрыть окно `alert`:

![Логирование времени в консоли Firefox](/ru/docs/Web/API/console/console-timelog.png)

Заметьте, что имя таймера отображено и при старте таймера и при его остановке.

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

### Трассировка стека вызова

Консоль также поддерживает вывод трассировки стека; она покажет вам весь путь вызовов функций, пройденный до момента, когда вы вызвали `console.trace()`. Например, такой код:
```

foo();

function foo() {
  function bar() {
    console.trace();
  }
  bar();
}
```

Вывод в консоль будет похож на этот:

![](/ru/docs/Web/API/console/api-trace2.png)

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

* По крайней мере в Firefox, если страница определяет свой объект `console`, то этот объект переопределяет объект `console`, встроенный в Firefox.
* До Gecko 12.0, методы объекта `console` работали только, если открыта панель "Веб-консоль" (Web Console). Начиная с Gecko 12.0, вывод кешируется до тех пор, пока панель Веб-консоль не откроется, и сразу отобразится в ней.
* Стоит отметить, что встроенный в Firefox объект `console` совместим с таким же объектом, предоставляемым плагином Firebug.
Смотрите также
--------------

* Tools
* Веб-консоль - как Веб-консоль в Firefox обрабатывает вызовы API-консоли
* Удалённая отладка- как посмотреть вывод в консоль, когда цель отладки находится на мобильном устройстве
* Отладка приложений в Firefox OS - использование Менеджера приложений для отладки приложений, запущенных на Firefox OS
* On-device console logging - как сделать логирование на устройствах на Firefox OS
### Реализации в браузерах

* Google Chrome DevTools
* Firebug
* Internet Explorer
* Safari