Требования

Самое важное, что нужно знать о Lit для работы с различными браузерами и инструментами:

• Lit публикуется в формате ES2019.
• Для импорта модулей Lit использует «голые спецификаторы модулей».
• Lit использует современные веб-API, такие как <template>, пользовательские элементы, shadow DOM и ParentNode.

Эти возможности поддерживаются последними версиями основных браузеров (включая Chrome, Edge, Safari и Firefox) и большинством популярных инструментов (таких как Rollup, Webpack, Babel и Terser), за исключением поддержки голых спецификаторов модулей в браузерах.

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

• Современные браузеры поддерживают ES2019 и веб-компоненты. Инструменты должны разрешать голые спецификаторы модулей.
• Устаревшие браузеры поддерживают ES5 и не поддерживают веб-компоненты или более новые API DOM. Инструменты должны компилировать JavaScript и загружать полифилы.

На этой странице представлен общий обзор того, как обеспечить выполнение этих требований в средах разработки и эксплуатации.

Рекомендации по инструментам и конфигурациям, соответствующим этим требованиям, см. в разделах Разработка, Тестирование и Сборка для эксплуатации.

Для использования Lit в современных браузерах требуется только одно преобразование: замена голых спецификаторов модулей на URL-адреса, совместимые с браузерами.

Для импорта модулей между своими подпакетами Lit использует голые спецификаторы модулей, например:

import {html} from 'lit-html';

В настоящее время современные браузеры поддерживают загрузку модулей только по URL-адресам или относительным путям, но не по голым именам, ссылающимся на npm-пакет, поэтому это должно обрабатываться системой сборки. Для этого спецификатор можно преобразовать в совместимый с ES-модулями в браузере либо в результате сборки создать модуль другого типа.

Webpack автоматически обрабатывает голые спецификаторы модулей; для Rollup понадобится плагин (@rollup/plugin-node-resolve).

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

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

Для поддержки старых браузеров (в частности, Internet Explorer 11, а также старых версий браузеров с автоматическим обновлением) требуется выполнить несколько дополнительных действий:

• Скомпилировать современный синтаксис JavaScript в ES5.
• Преобразовать ES-модули в другую модульную систему.
• Загрузить полифилы.

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

Для Rollup, webpack и других инструментов сборки существуют плагины, поддерживающие компиляцию современного JavaScript для старых браузеров. Наиболее часто используется компилятор Babel.

В отличие от некоторых библиотек, Lit публикуется в виде набора ES-модулей с использованием современного JavaScript ES2019. При сборке приложения для старых браузеров необходимо компилировать как Lit, так и собственный код.

Если у вас уже настроена сборка, возможно, при компиляции она игнорирует папку node_modules. В таком случае мы рекомендуем изменить настройки так, чтобы компилировался пакет lit и его зависимости времени выполнения (lit-html и lit-element). Например, если вы используете плагин Babel для Rollup, ваша конфигурация может выглядеть так, чтобы исключить папку node_modules из компиляции:

exclude: [ 'node_modules/**' ]

Это можно заменить правилом, явно задающим папки для компиляции:

include: [
  'src/**',
  'node_modules/lit/**',
  'node_modules/lit-element/**',
  'node_modules/lit-html/**'
]

Почему нет сборки для ES5? Пакет Lit не включает сборку для ES5, поскольку современный JavaScript компактнее и обычно работает быстрее. При сборке приложения можно скомпилировать современный JavaScript и создать именно те сборки, которые нужны для поддержки целевых браузеров.

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

При создании сборки для старых браузеров без поддержки модулей, таких как IE11, обычно используют один из трех форматов:

• Без модулей (IIFE). Код объединяется в один файл, обернутый в немедленно вызываемое функциональное выражение (IIFE).
• Модули AMD. Используется формат Asynchronous Module Definition; требуется скрипт загрузчика модулей, например require.js.
• Модули SystemJS. SystemJS — это загрузчик модулей, задающий собственный формат модулей. Он также поддерживает AMD, CommonJS и стандартные модули JavaScript.

Формат IIFE подходит, если весь код можно объединить в один файл. Чтобы использовать разделение кода с помощью динамического import() в старых браузерах, таких как IE11, необходимо создать сборку в формате модулей AMD или SystemJS и загрузить соответствующий загрузчик модулей или полифил.

Для использования Lit в старых браузерах необходимо загрузить полифилы стандартных возможностей JavaScript, таких как Promises и async/await, полифилы веб-компонентов, а также скрипт polyfill-support из пакета Lit, обеспечивающий взаимодействие Lit с полифилами веб-компонентов.

Рекомендуются следующие полифилы:

• Полифилы для возможностей JavaScript:
  • core-js — стандартная библиотека JS
  • regenerator-runtime — поддержка генераторов и async/await
• Полифилы для динамического import() (если используется в приложении; выберите вариант в зависимости от способа преобразования модулей):
  • systemjs — загрузчик модулей systemjs
  • requirejs — загрузчик модулей AMD
• Полифилы для веб-компонентов:
  • @webcomponents/webcomponentsjs — полифилы для пользовательских элементов, shadow DOM, шаблонов и некоторых новых API DOM
  • lit/polyfill-support.js — файл из пакета lit, который необходимо загрузить при использовании webcomponentsjs

Обратите внимание: в зависимости от используемых приложением возможностей могут понадобиться и другие полифилы.

Полифилы JavaScript следует объединять отдельно от пакета приложения и загружать до полифилов веб-компонентов, поскольку для работы последних необходимы современные возможности JS, такие как Promise. В итоге код на странице следует загружать в таком порядке:

<script src="path/to/js/polyfills/you/need.js"></script>
<script src="node_modules/lit/polyfill-support.js"></script>
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
<!-- Load application code here -->

Подробные сведения о загрузке и настройке полифилов веб-компонентов см. в документации webcomponentsjs. Ниже приведено описание некоторых ключевых моментов.

Существует два основных способа загрузки полифилов веб-компонентов:

• webcomponents-bundle.js включает все полифилы, необходимые для работы в любом из поддерживаемых браузеров. Поскольку все браузеры получают все полифилы, браузерам, поддерживающим одну или несколько возможностей, передаются лишние байты.
• webcomponents-loader.js выполняет обнаружение возможностей на стороне клиента и загружает только необходимые полифилы. Для этого требуется дополнительный обмен данными с сервером, зато экономится трафик для браузеров, поддерживающих одну или несколько возможностей.

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

Загрузите custom-elements-es5-adapter.js после полифилов Babel и до веб-компонентов, например:

<script src="path/to/js/polyfills/you/need.js"></script>
<script src="node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js"></script>
<script src="node_modules/lit/polyfill-support.js"></script>
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
<!-- Load application code here -->

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

Хотя полифилы веб-компонентов стремятся соответствовать спецификации, в некоторых случаях их поведение отличается, особенно в части стилей (см. ограничения ShadyCSS). Мы рекомендуем проводить тестирование как с включенными, так и с отключенными полифилами — в браузерах, которым они нужны, или принудительно включая их. Чтобы принудительно включить полифилы, добавьте фрагмент JavaScript перед импортом полифилов:

<script>
  // Force all polyfills on
  if (window.customElements) window.customElements.forcePolyfill = true;
  ShadyDOM = { force: true };
  ShadyCSS = { shimcssproperties: true};
</script>
<script src="./node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>

Если вы используете файл webcomponents-bundle.js, можно принудительно включить полифилы, добавив параметры запроса к URL-адресу приложения:

https://www.example.com/my-application/view1?wc-ce&wc-shadydom&wc-shimcssproperties

В следующей таблице перечислены фрагменты JavaScript и параметры запроса для каждого полифила.

Изменить эту страницу