Декларативные частичные обновления

Дата публикации: 19 мая 2026 г. Последнее обновление: 8 сентября 2026 г.

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

HTML, несмотря на все его преимущества, по-прежнему доставляется по порядку сверху вниз, практически без учета того, когда контент готов или когда пользователь его потребляет. CSS позволяет изменить порядок контента, но часто со значительными побочными эффектами доступности. JavaScript позволяет манипулировать DOM через различные API, чтобы в некоторой степени освободиться от этого, но для этого часто требуется подробный синтаксис или построение деревьев DOM для подключения к HTML.

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

Команда Chrome изучила эту проблему и разработала новые дополнения к веб-платформе под названием Declarative Partial Updates.

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

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

Browser Support

  • Chrome: 150.
  • Edge: 150.
  • Firefox: not supported.
  • Safari: not supported.

Source

Первый набор изменений – это новые API для потоковой передачи вне очереди, в которых используются плейсхолдеры инструкций по обработке и элемент HTML <template> с атрибутом for. Пример:

<div>
  <?marker name="placeholder">
</div>

...

<template for="placeholder">
  Here is some <em>HTML content</em>!
</template>

Инструкции по обработке давно используются в XML, но в HTML они обрабатываются как комментарии и игнорируются. Новый API меняет это и добавляет инструкции по обработке в HTML. Например, когда браузер видит инструкцию по обработке <?marker name="placeholder">, он не выполняет никаких действий сразу, но может обратиться к ней позже.

Элемент <template> с атрибутом for ищет соответствующие инструкции по обработке с атрибутом name и заменяет контент. В этом случае после синтаксического анализа DOM будет выглядеть следующим образом (без учета некоторых различий в пробелах):

<div>
  Here is some <em>HTML content</em>!
</div>

Помимо атрибута <?marker> для замен, существуют также маркеры диапазона <?start> и <?end>, которые позволяют показывать временный контент-плейсхолдер до обработки шаблона:

<div>
  <?start name="another-placeholder">
  Loading…
  <?end>
</div>

...

<template for="another-placeholder">
  Here is some <em>HTML content</em>!
</template>

В этом случае строка Loading… будет показываться до тех пор, пока не появится <template>, а затем будет заменена новым контентом.

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

<ul id="results">
  <?start name="results">
  Loading…
  <?end>
</ul>

...

<template for="results">
  <li>Result One</li>
  <?marker name="results">
</template>

...

<template for="results">
  <li>Result Two</li>
  <?marker name="results">
</template>

...

После обработки и анализа HTML-код будет выглядеть следующим образом:

<ul id="results">
  <li>Result One</li>
  <li>Result Two</li>
  <?marker name="results">
</ul>

С инструкцией по окончательной обработке в конце, на случай если в документ позже будут добавлены другие плейсхолдеры <template for="results">.

Почему используются инструкции по обработке, а не стандартные элементы HTML?

Это распространенный вопрос среди тех, кто только начинает использовать API. В качестве решения предлагается использовать элементы <slot> или даже <template>. В первоначальной версии этого предложения использовались стандартные элементы HTML, но в процессе доработки дизайна были выбраны инструкции по обработке. Инструкции по обработке позволяют выполнять исправления, не затрагивая DOM. Это позволяет использовать его в <head>, например для обновлений <title>, или даже внутри других элементов, таких как <table> (например, чтобы добавить дополнительные строки).

Хотя синтаксис инструкций по обработке незнаком многим веб-разработчикам, они обеспечивают гораздо большую гибкость и снижают вероятность проблем с обратной совместимостью. Они уже используются в XML, а благодаря этому предложению теперь стали частью стандарта HTML.

Демоверсии

В этом видео показано, как создать простое приложение для фотоальбома с помощью потоковой передачи HTML.

Демонстрация фотоальбома, реализованная с помощью потоковой передачи вне очереди (источник)

И статус, и фотографии передаются в HTML-код после первоначальной загрузки макета.

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

Существует множество вариантов использования такого внеочередного исправления HTML в сочетании со стримингом HTML:

  • Островная архитектура. Распространенный шаблон, популяризированный такими фреймворками, как Astro, – это островная архитектура, в которой компоненты гидратируются независимо поверх статического HTML. API <template for> позволяет обрабатывать статический контент аналогичным образом непосредственно в HTML. Фреймворки JavaScript также могут использовать его для более интерактивных островов или для обработки компонентов.
  • Публикуйте контент, когда он готов. Благодаря такой архитектуре контент может передаваться по мере готовности, а не задерживаться из-за контента, требующего дополнительной обработки, например поиска в базе данных. Хотя многие платформы поддерживают потоковую передачу HTML, из-за последовательной природы HTML контент часто задерживается или приходится прибегать к сложным манипуляциям с DOM в JavaScript. Теперь вы можете показывать статический контент, пока ожидаете, а затем вставлять более дорогой и динамический контент в конце HTML-потока.
  • HTML-код может передаваться в порядке, оптимальном для загрузки страницы. Вы можете изменить заказ, даже когда он уже готов. Например, мегаменю – это распространенный элемент навигации, который содержит много HTML-кода, невидимого для пользователя, пока страница не станет интерактивной. Этот большой фрагмент HTML-кода можно передать позже в HTML-документе, чтобы отдать приоритет более важному HTML-коду, необходимому для начальной загрузки страницы. Порядок больше не является препятствием для HTML.

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

Ограничения и особенности

При работе с API необходимо учитывать следующие ограничения и особенности:

  • Из соображений безопасности <template for> может обновлять инструкции по обработке только в пределах одного родительского элемента. Если добавить <template for> непосредственно в элемент <body>, он получит доступ ко всему документу (включая <head>).
  • Инструкция по обработке <?end> необязательна. Если она отсутствует, будет заменен контент между элементом <?start> и концом содержащего его элемента.
  • Если переместить инструкции по обработке после того, как начнется трансляция <template for>, это также может привести к непредвиденным последствиям, например к тому, что новый контент будет по-прежнему передаваться в старое местоположение.
  • Обратите внимание, что при динамической вставке <template for> с помощью такого метода, как setHTML, или свойства innerHTML родительским элементом шаблона при его анализе является промежуточный фрагмент документа. Это означает, что вставка HTML с помощью этих методов не может изменить существующую DOM, а исправление происходит "на месте" внутри фрагмента. Однако при потоковой передаче с использованием таких методов, как streamHTMLUnsafe (описано ниже), промежуточный фрагмент отсутствует, поэтому шаблоны могут заменять существующий контент.

Статус стандартизации

Атрибут <template for> входит в стандарт HTML, но пока поддерживается не во всех браузерах.

Возможные дополнения в будущем

Вот некоторые из возможных дополнений, которые мы рассматриваем:

  • Включения на стороне клиента. Например, <template for="footer" src="/partials/footer.html"> или даже без исправления <template src="/partials/footer.html">. Подробную информацию можно найти в пояснении. Эта функция доступна за параметром chrome://flags/#enable-experimental-web-platform-features.
  • Предотвращение перезаписи контента, который не будет меняться. Для этого можно использовать номер редакции или версии контента. Это позволит сохранять состояние при изменении маршрута или других обновлениях, а не сбрасывать контент.
  • Очистка при исправлении. Пример: <template for=icon safe><svg id="from-untrusted-source">...</svg></template>.

Полифил

Команда Chrome выпустила полифил template-for-polyfill, который доступен в npm. Он позволяет сайтам использовать новую функцию, даже если она ещё не поддерживается в других браузерах.

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

Обновленные методы вставки HTML и потоковой передачи

Не весь контент можно передавать в формате HTML. Вторая часть работы Chrome в этой области направлена на то, чтобы упростить обновление контента с помощью JavaScript.

Существует несколько способов динамически вставить HTML в существующий документ с помощью JavaScript:

  • setHTML
  • setHTMLUnsafe
  • innerHTML и outerHTML
  • createContextualFragment
  • insertAdjacentHTML

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

  • Новый контент перезаписывает или дополняет существующий?
  • Очищают ли они потенциально опасный HTML-код, например экранируя теги <script>?
  • Если нет, то должен ли выполняться <script>?
  • Как они работают с доверенными типами?

Мало кто из разработчиков мог честно взглянуть на эти API и уверенно ответить на эти вопросы для каждого из них.

Большим ограничением является то, что их можно использовать только для полного набора HTML, известного заранее, когда поступали вызовы, разрешающие потоковую передачу HTML. На практике это означает, что вам нужно скачать весь контент, прежде чем вставлять его, тогда как одним из преимуществ HTML является возможность сразу же передавать контент в потоковом режиме. Эту проблему можно частично решить, разделив полезную нагрузку или используя устаревшие методы, такие как document.write, но они создают свои собственные проблемы.

Новый набор API для статических и потоковых данных

Browser Support

  • Chrome: behind a flag.
  • Edge: behind a flag.
  • Firefox: not supported.
  • Safari: not supported.

В Chrome был разработан набор новых API и расширений для существующих setHTML и setHTMLUnsafe, которые решают эту проблему, а также добавляют функцию потоковой передачи.

Они доступны для тестирования разработчиками в Chrome 148 с помощью флага chrome://flags/#enable-experimental-web-platform-features. Запуск запланирован в Chrome 155.

Существуют методы для установки или замены, а также методы для вставки контента до или после существующего HTML. У каждого метода есть эквиваленты для потоков:

Действие Статический Потоковая передача
Задать HTML-контент элемента setHTML(html, options); streamHTML(options);
Заменить весь элемент этим HTML-кодом replaceWithHTML(html, options); streamReplaceWithHTML(options);
Добавить HTML-код перед элементом beforeHTML(html, options); streamBeforeHTML(options);
Добавьте HTML-код в качестве первого дочернего элемента. prependHTML(html, options); streamPrependHTML(options);
Добавить HTML-код в качестве последнего дочернего элемента appendHTML(html, options); streamAppendHTML(options);
Добавить HTML-код после элемента afterHTML(html, options); streamAfterHTML(options);
Новые методы вставки и потоковой передачи

Также есть Unsafe версии, о которых мы расскажем далее. Хотя их может показаться много, особенно если добавить эквиваленты Unsafe, благодаря единообразному соглашению об именовании становится более очевидно, что делает каждый из них, по сравнению с несвязанными методами, упомянутыми ранее.

Статические версии принимают новый HTML-код в качестве аргумента DOMString, а также необязательные параметры:

const newHTML = "<p>This is a new paragraph</p>";
const contentElement = document.querySelector('#content-to-update');

contentElement.setHTML(newHTML);

Потоковые версии работают с Streams API, например с getWriter():

const contentElement = document.querySelector('#content-to-update');
const writer = contentElement.streamHTMLUnsafe().getWriter();

// Example stream of updating content
while (true) {
  await writer.write(`<p>${++i}</p>`);
  await new Promise((resolve) => setTimeout(resolve, 1000));
}

writer.close();

Или из ответа на запрос на получение с помощью цепочек каналов:

const contentElement = document.querySelector('#content-to-update');
const response = await fetch('/api/content.html');

response.body
  .pipeThrough(new TextDecoderStream())
  .pipeTo(contentElement.streamHTMLUnsafe());

textStream() удобный способ

Browser Support

  • Chrome: 151.
  • Edge: 151.
  • Firefox: not supported.
  • Safari: not supported.

Source

Также был добавлен удобный метод textStream, позволяющий вести трансляцию напрямую без промежуточного шага TextDecoderStream():

const contentElement = document.querySelector('#content-to-update');
const response = await fetch('/api/content.html');

response.textStream().pipeTo(contentElement.streamHTMLUnsafe());

options

Аргумент options позволяет указать пользовательский sanitizer, который по умолчанию имеет значение default, что означает конфигурацию очистителя по умолчанию. Пример:

const newHTML = '<p>This is a new paragraph</p>';
const contentElement = document.querySelector('#content-to-update');

// Only allows basic formatting
const basicFormattingSanitzer = new Sanitizer({ elements: ['em', 'i', 'b', 'strong'] });

contentElement.setHTML(newHTML, {sanitizer: basicFormattingSanitzer});

"Небезопасные" методы

Также существуют "небезопасные" версии каждого из API:

Действие Статический Потоковая передача
Задать HTML-контент элемента setHTMLUnsafe(html,options); streamHTMLUnsafe(options);
Заменить весь элемент этим HTML-кодом replaceWithHTMLUnsafe(html, options); streamReplaceWithHTMLUnsafe(options);
Добавить HTML-код перед элементом beforeHTMLUnsafe(html, options); streamBeforeHTMLUnsafe(options);
Добавьте HTML-код в качестве первого дочернего элемента. prependHTMLUnsafe(html, options); streamPrependHTMLUnsafe(options);
Добавить HTML-код в качестве последнего дочернего элемента appendHTMLUnsafe(html, options); streamAppendHTMLUnsafe(options);
Добавить HTML-код после элемента afterHTMLUnsafe(html, options); streamAfterHTMLUnsafe(options);
"Небезопасные" методы вставки и потоковой передачи

Эти "небезопасные" методы по умолчанию отключают дезинфектор, но вы можете указать собственный дезинфектор. Эти методы также позволяют запускать скрипты с необязательным параметром runScripts, значение которого по умолчанию – false.

Как и setHTML, setHTMLUnsafe – это существующий метод, но в него был добавлен параметр runScripts, чтобы его можно было использовать при выполнении скрипта:

const newHTML = `<p>This is a new paragraph</p>
                 <script src=script.js></script>`;
const contentElement = document.querySelector('#content-to-update');

contentElement.setHTMLUnsafe(newHTML, {runScripts: true});

Слово "unsafe" (небезопасный) в названии метода напоминает разработчикам о потенциальном риске и о том, что им может потребоваться очистить или ограничить скрипты. Это не означает, что такие методы нельзя использовать.

Насколько это небезопасно, зависит от того, насколько надежны входные данные. Все статические методы Unsafe работают как со строкой DOM, так и с TrustedHTML в качестве аргументов html, а также позволяют использовать дезинфекторы. Однако runScript предназначен для того, чтобы разрешать скрипты, поэтому по умолчанию дезинфектор не используется.

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

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

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

  • Динамическая потоковая передача больших обновлений контента в одностраничных приложениях. Как упоминалось ранее, большим недостатком текущей архитектуры SPA является то, что она не использует преимущества потоковой передачи начальных загрузок HTML – до сих пор!
  • Вставка стандартного контента, например нижних колонтитулов HTML. Используя JavaScript API, вы можете извлекать фрагменты и вставлять их на страницу, используя кеширование, а не повторять их на каждой отправляемой странице. Однако, поскольку для работы этого метода требуется JavaScript, его следует использовать только для контента, который не будет виден при первоначальной загрузке.

Это лишь пара примеров. Мы с нетерпением ждем ваших идей!

Ограничения и особенности

При работе с новыми API необходимо учитывать следующие ограничения и особенности:

  • Чтобы интегрировать потоковую передачу с Trusted Types API, необходимо использовать новый метод createParserOptions, который позволяет внедрять дезинфектор в любую операцию настройки HTML. Подробнее об интеграции доверенных типов…
  • Как и в случае с <template for>, перемещение элементов, в которые выполняется трансляция, может привести к непредвиденным последствиям или ошибкам трансляции.
  • streamHTMLUnsafe во многом работает как основной синтаксический анализатор, в том числе обрабатывает инструкции <template for> по мере их добавления в основной документ и откладывает скрипты defer до конца потока.

Статус стандартизации

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

Полифил

Команда Chrome выпустила полифил html-setters-polyfill, который доступен в npm. Он позволяет сайтам использовать новую функцию, даже если она ещё не поддерживается в других браузерах.

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

Кроме того, настройка безопасного контента зависит от setHTML и Sanitizer API, который не поддерживается в Safari.

Используйте оба инструмента вместе

Хотя это два разных API, их можно использовать вместе. Передавая новые элементы <template for> в HTML, вы можете динамически обновлять разные части контента, не обращаясь к каждой из них с помощью отдельных ссылок JavaScript на DOM.

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

Несомненно, у обоих API есть и другие возможности и варианты использования, поэтому не ограничивайтесь нашими примерами. Упростив управление частичными обновлениями, вы сможете сократить объем шаблонного кода, упростить обновления и открыть новые возможности для интернета.

В рамках проекта Declarative Partial Updates мы работаем над другими API, но пока рады представить вам эти два. Мы будем держать вас в курсе и сообщим, когда появится больше информации.