Декораторы

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

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

Дополнительную информацию см. в разделе Включение декораторов.

Lit предоставляет набор декораторов, которые сокращают объём шаблонного кода, необходимого для определения компонента. Например, декораторы @customElement и @property делают определение простого элемента более компактным:

@customElement('my-element')
export class MyElement extends LitElement {
  @property() greeting = "Welcome";
  @property() name = "Sally";
  @property({type: Boolean}) emphatic = true;
  //...
}

Декоратор @customElement определяет пользовательский элемент и эквивалентен вызову:

customElements.define('my-element', MyElement);

Декоратор @property объявляет реактивное свойство.

Дополнительную информацию о настройке свойств см. в разделе Реактивные свойства.

Вы можете импортировать все декораторы 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, включите параметр компилятора experimentalDecorators.

Также убедитесь, что параметр useDefineForClassFields установлен в значение false. Обратите внимание: это требуется только в том случае, если для параметра target задано значение esnext или выше, однако рекомендуется явно убедиться, что для этого параметра установлено значение false.

"experimentalDecorators": true,
"useDefineForClassFields": false,

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

Если вы компилируете JavaScript с помощью Babel, можно включить декораторы, добавив следующие плагины и параметры:

• @babel/plugin-proposal-decorators
• @babel/plugin-proposal-class-properties

Обратите внимание: в последних версиях Babel @babel/plugin-proposal-class-properties может не требоваться.

Чтобы настроить плагины, добавьте в конфигурацию Babel код, подобный этому:

"assumptions": {
  "setPublicClassFields": true
},
"plugins": [
  ["@babel/plugin-proposal-decorators", {
    "version": "2018-09",
    "decoratorsBeforeExport": true
  }],
  ["@babel/plugin-proposal-class-properties"]
]

При использовании TypeScript с Babel важно в конфигурации Babel расположить преобразование TypeScript перед преобразованием декораторов, как показано ниже:

{
  "assumptions": {
    "setPublicClassFields": true
  },
  "plugins": [
    ["@babel/plugin-transform-typescript", {
      "allowDeclareFields": true
    }],
    ["@babel/plugin-proposal-decorators", {
      "version": "2018-09",
      "decoratorsBeforeExport": true
    }],
    ["@babel/plugin-proposal-class-properties"]
  ]
}

Параметр allowDeclareFields обычно не требуется, но он может быть полезен, если нужно определить реактивное свойство без использования декоратора. Например:

static properties = { foo: {} };

declare foo: string;

constructor() {
  super();
  this.foo = 'bar';
}

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

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

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

Редактировать эту страницу