API возврата/пересылки notRestoredReasons

Узнайте, какие переходы были заблокированы при использовании bfcache и почему.

Крис Миллс
Барри Поллард

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

Текущий статус

API notRestoredReasons появился в Chrome 123 и развертывается постепенно.

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

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

Раньше у разработчиков не было возможности узнать, почему их страницам было заблокировано использование bfcache в полевых условиях, хотя в инструментах разработчика Chrome была проверка . Чтобы включить мониторинг в полевых условиях, класс PerformanceNavigationTiming был расширен за счет включения свойства notRestoredReasons . Это возвращает объект, содержащий связанную информацию о верхнем фрейме и всех iframe, присутствующих в документе:

  • Причины, по которым им было заблокировано использование bfcache.

  • Такие сведения, как id и name фрейма, помогают идентифицировать iframe в HTML.

    Это позволяет разработчикам предпринимать действия, чтобы сделать эти страницы совместимыми с bfcache, тем самым повышая производительность сайта.

Примеры

Экземпляр PerformanceNavigationTiming можно получить с помощью таких функций, как Performance.getEntriesByType() и PerformanceObserver .

Например, вы можете вызвать следующую функцию, чтобы вернуть все объекты PerformanceNavigationTiming присутствующие на временной шкале производительности, и записать их notRestoredReasons :

function returnNRR() {
  const navEntries = performance.getEntriesByType("navigation");
  for (let i = 0; i < navEntries.length; i++) {
    console.log(`Navigation entry ${i}`);
    let navEntry = navEntries[i];
    console.log(navEntry.notRestoredReasons);
  }
}

Для навигации по истории свойство PerformanceNavigationTiming.notRestoredReasons возвращает объект со следующей структурой, которая представляет заблокированное состояние фрейма верхнего уровня:

{
  children: [],
  id: null,
  name: null,
  reasons: [
    {"reason", "unload-listener"}
  ],
  src: null,
  url: "https://www.example.com/page/"
}

Свойства следующие:

children
Массив объектов, представляющих заблокированное состояние любых кадров того же происхождения, встроенных в кадр верхнего уровня. Каждый объект имеет ту же структуру, что и родительский объект — таким образом, любое количество уровней встроенных фреймов может быть рекурсивно представлено внутри объекта. Если у фрейма нет дочерних элементов, массив будет пустым.
id
Строка, представляющая значение атрибута id кадра (например <iframe id="foo" src="..."> ). Если у кадра нет id , значение будет null . Для страницы верхнего уровня это значение null .
name
Строка, представляющая значение атрибута name кадра (например <iframe name="bar" src="..."> ). Если у фрейма нет name , значением будет пустая строка. Для страницы верхнего уровня это значение null .
reasons
Массив строк, каждая из которых представляет причину, по которой на странице навигации было заблокировано использование bfcache. Существует много разных причин, по которым может произойти блокировка. Подробности смотрите в разделе Причины блокировки .
src
Строка, представляющая путь к источнику кадра (например <iframe src="b.html"> ). Если в кадре нет src , значением будет пустая строка. Для страницы верхнего уровня это значение null .
url
Строка, представляющая URL-адрес страницы навигации или iframe.

Для объектов PerformanceNavigationTiming , которые не представляют навигацию по истории, свойство notRestoredReasons вернет null .

Обратите внимание, что notRestoredReasons также возвращает null , если нет причин блокировки, поэтому значение null не является индикатором того, что bfcache использовался или не использовался. Для этого вы должны использовать свойство event.persisted .

Сообщать о блокировке bfcache в кадрах одного происхождения

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

Например:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example.com/"
    },
    {
      children: [],
      id: "iframe-id2",
      name: "iframe-name2",
      reasons: [
        {"reason": "unload-listener"}
      ],
      src: "./unload-examples.html",
      url: "https://www.example.com/unload-examples.html"
    },
  ],
  id: null,
  name: null,
  reasons: [],
  src: null,
  url:"https://www.example.com"
}

Сообщать о блокировке bfcache в кадрах с перекрестным происхождением

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

Например:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example2.com/"
    }
  ],
  id: null,
  name: null,
  reasons: [
        {"reason": "masked"}
  ],
  src: null,
  url:"https://www.example.com"
}

Для всех iframe с перекрестным происхождением мы сообщаем значение null для значения reasons для кадра, а в кадре верхнего уровня будет отображаться причина "masked" . Обратите внимание, что "masked" также может использоваться по причинам, специфичным для пользовательского агента, поэтому не всегда может указывать на проблему в iframe.

Дополнительные сведения о вопросах безопасности и конфиденциальности см. в разделе «Безопасность и конфиденциальность» пояснения.

Причины блокировки

Как мы уже говорили ранее, существует множество разных причин, по которым может произойти блокировка:

Ниже приведены примеры некоторых наиболее распространенных причин, по которым невозможно использовать bfcache:

  • unload-listener : страница регистрирует обработчик unload , который предотвращает использование bfcache в некоторых браузерах. Дополнительную информацию см. в разделе «Отказ от события выгрузки» .
  • response-cache-control-no-store : страница использует no-store в качестве значения cache-control .
  • related-active-contents : страница была открыта с другой страницы (либо с помощью «дубликата вкладки»), на которой все еще есть ссылка на эту страницу.

Обратная связь

Команда Chromium хочет услышать о вашем опыте работы с API bfcache notRestoredReasons .

Расскажите нам о дизайне API

Что-то в API работает не так, как вы ожидали? Или вам не хватает методов или свойств, необходимых для реализации вашей идеи? У вас есть вопрос или комментарий по модели безопасности? Сообщите о проблеме спецификации в соответствующем репозитории GitHub или добавьте свои мысли к существующей проблеме.

Сообщить о проблеме с реализацией

Вы нашли ошибку в реализации Chromium? Или реализация отличается от спецификации? Сообщите об ошибке в нашем трекере проблем . Обязательно включите как можно больше подробностей, простые инструкции по воспроизведению и укажите компонент как UI > Browser > Navigation > BFCache . Glitch отлично подходит для быстрого и простого обмена репродукциями.

Показать поддержку API

Планируете ли вы использовать API bfcache notRestoredReasons ? Ваша публичная поддержка помогает команде Chromium расставлять приоритеты в функциях и показывает другим поставщикам браузеров, насколько важно их поддерживать.

Отправьте твит @ChromiumDev, используя хэштег #NotRestoredReasons , и сообщите нам, где и как вы его используете.

Полезные ссылки