JavaScript свойство Document.cookie

Определение и применение

JavaScript свойство cookie объекта Document получает или задает cookie (небольшой фрагмент данных, отправленный веб-сервером и хранимый на компьютере пользователя), связанных с текущим документом.

Для возможности сохранения cookies после окончания сеанса браузера необходимо дополнительно передать специальный атрибут ;max-age=max-age-in-seconds, значение которого в секундах определяет как долго он должен храниться. Если этот атрибут указан, то браузер сохранит cookie в локальном файле и может удалить его раньше по настройкам приватности, решению пользователя или при очистке данных.

Cookie сопоставляются с хостом или доменом и путём запроса; порт не разделяет cookie так, как он разделяет Web Storage. Без Domain cookie привязана к точному хосту. Путь по умолчанию определяется каталогом текущего URL: cookie со страницы https://basicweb.ru/content/index.php доступна для /content/somepage.php и /content/catalog/otherpage.php, но не для /index.php.

Чтобы cookie подходила ко всем путям на хосте, задайте Path=/. Для Path=/css подходят /css и /css/somepage.html, но не /css-other: учитывается граница каталога. Path не обеспечивает изоляцию от скриптов того же сайта. Отправка cookie также зависит от Secure, SameSite и политики браузера.

Для совместного использования cookie поддоменами можно задать родительский домен: страница catalog.example.com вправе установить Domain=example.com. Тогда cookie подходит и для example.com, и для его поддоменов. Начальная точка в .example.com игнорируется. Нельзя назначить чужой домен или публичный суффикс вроде com.

Атрибут Secure ограничивает передачу cookie защищённым соединением, обычно HTTPS. Его отсутствие не заставляет браузер использовать HTTP: cookie может отправляться и по HTTP, и по HTTPS при выполнении остальных условий. HttpOnly устанавливает сервер; такие cookie недоступны через document.cookie.

Чтение возвращает доступные пары имя=значение, а присваивание устанавливает одну cookie, не заменяя все остальные. HttpOnly-cookie недоступны JavaScript. Используйте Secure для HTTPS и подходящий SameSite; для SameSite=None требуется Secure. Cookie не изолируются по порту так же, как Web Storage; Path не является защитной границей. Восстановление сеанса может сохранить и сессионные cookie.

Поддержка браузерами

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

✓Поддерживается во всех основных браузерах с 2019 года.

Показать браузеры

ВсеКомпьютерыМобильные

Совместимостьapi.Document.cookie

Возможность	Компьютеры					Мобильные
	ChromeChrome	EdgeEdge	FirefoxFirefox	OperaOpera	SafariSafari	Chrome AndroidChromeAndroid	Firefox for AndroidFirefoxAndroid	Opera AndroidOperaAndroid	Safari on iOSSafariiOS	Samsung BrowserSamsungAndroid	WebView AndroidWebViewAndroid	WebView on iOSWebViewiOS
cookie	✓1	✓12	✓68…	✓3	✓4…	✓18	✓68…	✓10.1	✓3.2…	✓1.0	✓4.4	✓3.2…

✓поддерживается◐с ограниченияминет поддержки?нет данных≤31 — не позднее версии 31

JavaScript синтаксис

Получение всех cookies

const allCookies = document.cookie;

В коде выше allCookies представляет собой строку, содержащую разделенный точкой с запятой список всех файлов cookie (т. е. пары ключ=значение). Обратите внимание, что каждый ключ и значение могут быть окружены пробелами (пробелами и символами табуляции), на самом деле стандарт RFC 6265 требует одного пробела после каждой точки с запятой, но некоторые браузеры могут не соблюдать этого.

Установка нового cookie

document.cookie = newCookie;

В приведенном выше коде, newCookie представляет собой строку вида ключ=значение. Обратите внимание, что вы можете установить, или обновить только один файл cookie за раз с помощью этого метода. Учтите также, что:

• Любое из следующих значений атрибута cookie может дополнительно следовать за парой ключ-значение, указывая параметры устанавливаемого или обновляемого файла cookie; каждому атрибуту предшествует точка с запятой:
  • ;path=путь (например, "/", "/mydir") если не указано, то по умолчанию используется каталог текущего URL документа. Путь должен быть абсолютным.
  • ;domain=домен (например, "example.com", или "subdomain.example.com"). Если не указано, то по умолчанию используется часть узла текущего расположения документа. Если домен указан, то субдомены всегда включаются.
  • ;max-age=31536000 задаёт срок в секундах. Выражение 60 * 60 * 24 * 365 нужно вычислить в JavaScript перед включением результата в строку cookie.
  • ;expires=date-in-GMTString-format если ни expires, ни max-age не указаны, то срок действия истекает в конце сессии.
  • ;secure разрешает передачу cookie только по защищённому соединению. Без этого атрибута cookie может отправляться и по HTTP, и по HTTPS.
  • ;samesite управляет отправкой cookie в межсайтовых запросах. Возможные значения флага lax, strict или none:
    • lax - отправляет cookie при межсайтовой навигации верхнего уровня безопасными методами (например, при переходе по ссылке методом GET), но не во вложенных межсайтовых запросах. Это предотвращает многие атаки CSRF. Значение по умолчанию в современных браузерах.
    • strict - будет препятствовать отправке cookie браузером на целевой сайт во всех контекстах межсайтового просмотра, даже при переходе по обычной ссылке.
    • none разрешает межсайтовую отправку и требует Secure. Настройки приватности и блокировка сторонних cookie всё равно могут запретить отправку.
• Строка значения cookie может использовать метод encodeURIComponent(), чтобы гарантировать, что строка не содержит запятых, точек с запятой или пробелов (которые запрещены в значениях cookie).
• Некоторые браузеры поддерживают следующие префиксы cookie (эти флаги можно установить только с помощью атрибута ;secure):
  • __Secure- - сигнализирует браузеру, что он должен включать cookie только в запросы, передаваемые по защищенному каналу.
  • __Host- — требует безопасного источника, атрибута Secure, явно заданного Path=/ и отсутствия Domain. Cookie привязана к конкретному хосту.

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

HTML Standard.

Для удаления установите cookie с теми же именем, Path и Domain, но с Max-Age=0, например document.cookie = "theme=; Path=/; Max-Age=0". Присваивание пустой строки самому document.cookie не очищает хранилище. При одновременном указании Max-Age и Expires приоритет имеет Max-Age.

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

// устанавливаем значение cookie
document.cookie = "name=basicweb";
document.cookie = "uid=5454545454";

// выводим в консоль текущее значение cookie
console.log(document.cookie); // "name=basicweb; uid=5454545454"