Декораторы

Декораторы — это функции, которые можно использовать для декларативного аннотирования классов и изменения их поведения.

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

Например, декораторы @customElement и @property() позволяют зарегистрировать пользовательский элемент и декларативно определить реактивное свойство в компактной форме:

@customElement('my-element')
export class MyElement extends LitElement {

  @property()
  greeting = 'Welcome';

}

Вы можете импортировать все декораторы Lit из модуля lit/decorators.js:

import {customElement, property, eventOptions, query} from 'lit/decorators.js';

Чтобы уменьшить объём кода, необходимого для работы компонента, декораторы можно импортировать в код компонента по отдельности. Все декораторы доступны в lit/decorators/<decorator-name>.js. Например:

import {customElement} from 'lit/decorators/custom-element.js';
import {eventOptions} from 'lit/decorators/event-options.js';

Чтобы использовать декораторы, необходимо собрать код с помощью компилятора, например TypeScript или Babel.

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

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

Чтобы использовать экспериментальные декораторы, необходимо включить параметр компилятора experimentalDecorators.

Также следует убедиться, что параметр useDefineForClassFields имеет значение false. Это необходимо только в том случае, если target имеет значение ES2022 или выше, однако рекомендуется явно установить значение false. Это нужно, чтобы избежать проблем с полями классов при объявлении свойств.

// tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "useDefineForClassFields": false,
  }
}

Включать emitDecoratorMetadata не требуется и не рекомендуется.

Декораторы Lit разработаны для поддержки синтаксиса стандартных декораторов (с использованием accessor для декораторов полей класса) в режиме экспериментальных декораторов TypeScript.

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

// tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": false, // default for TypeScript 5.0 and up
    "useDefineForClassFields": true, // default when "target" is "ES2022" or higher
  }
}

Примечание. Ключевое слово accessor появилось в TypeScript 4.9, а для стандартных декораторов с метаданными требуется TypeScript версии ≥5.2.

Babel поддерживает стандартные декораторы с помощью плагина @babel/plugin-proposal-decorators начиная с версии 7.23. Babel не поддерживает экспериментальные декораторы TypeScript, поэтому декораторы Lit необходимо использовать с синтаксисом стандартных декораторов, добавляя ключевое слово accessor к декорируемым полям класса.

Включите поддержку декораторов, добавив @babel/plugin-proposal-decorators со следующими параметрами конфигурации Babel:

// babel.config.json
{
  "plugins": [
    ["@babel/plugin-proposal-decorators", {"version": "2023-05"}]
  ]
}

Примечание. Декораторы Lit работают только с "version": "2023-05". Другие версии, включая ранее поддерживаемую "2018-09", не поддерживаются.

Декораторы — это предложение третьего этапа о включении в стандарт ECMAScript. Компиляторы, такие как Babel и TypeScript, поддерживают декораторы, хотя пока ни один браузер их не реализовал. Декораторы Lit работают с Babel и TypeScript и будут работать в браузерах после их встроенной реализации.

До того как предложение TC39 достигло третьего этапа, компиляторы реализовывали более ранние версии спецификации декораторов.

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

Babel также поддерживал разные версии спецификации в разное время, что отражено в параметре "version" плагина декораторов. Ранее Lit 2 поддерживал версию "2018-09" для пользователей Babel, но теперь её поддержка прекращена в пользу стандартной версии "2023-05", описанной ниже.

Стандартные декораторы — это версия декораторов, получившая консенсус на третьем этапе TC39 — организации, определяющей ECMAScript/JavaScript.

Стандартные декораторы поддерживаются в TypeScript и Babel; встроенная поддержка в браузерах появится в ближайшем будущем.

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

Поскольку многие декораторы Lit создают аксессоры, их необходимо применять к аксессорам, а не к полям класса.

Для удобства спецификация стандартных декораторов добавляет ключевое слово accessor для объявления «автоаксессоров»:

class MyClass {
  accessor foo = 42;
}

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

Декораторы Lit, применяемые к полям класса с экспериментальными декораторами, — например, @property(), @state(), @query() и т. д. — при использовании стандартных декораторов необходимо применять к аксессорам или автоаксессорам:

@customElement('my-element')
export class MyElement extends LitElement {

  @property()
  accessor greeting = 'Welcome';

}

К сожалению, результат компиляции стандартных декораторов получается объёмным, поскольку необходимо генерировать аксессоры, приватное хранилище и другие объекты, входящие в API декораторов.

Поэтому мы рекомендуем пользователям, которые хотят применять декораторы, по возможности пока использовать экспериментальные декораторы TypeScript.

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

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