LitElement

Синхронизирует значения свойств при изменении атрибутов.

Параметры

name

string

_old

null | string

value

null | string

Подробности

В частности, при установке атрибута устанавливается соответствующее свойство. Обычно реализовывать этот обратный вызов не требуется. Если этот метод переопределён, необходимо вызвать super.attributeChangedCallback(name, _old, value). Дополнительные сведения о attributeChangedCallback см. в разделе использование обратных вызовов жизненного цикла на MDN.

Возвращает список атрибутов, соответствующих зарегистрированным свойствам.

Регистрирует ReactiveController для участия в цикле реактивного обновления элемента. Во время обратных вызовов жизненного цикла элемент автоматически обращается ко всем зарегистрированным контроллерам.

Параметры

controller

ReactiveController

Подробности

Если элемент подключён к DOM в момент вызова addController(), обратный вызов hostConnected() контроллера будет вызван немедленно.

Удаляет ReactiveController из элемента.

Параметры

controller

ReactiveController

Отключает указанную категорию предупреждений для этого класса.

Подробности

Этот метод существует только в сборках для разработки, поэтому обращаться к нему следует с проверкой, например:

// Disable for all ReactiveElement subclasses
ReactiveElement.disableWarning?.('migration');
// Disable for only MyElement and subclasses
MyElement.disableWarning?.('migration');

Читает или задаёт все включённые категории предупреждений для этого класса.

Подробности

Это свойство используется только в сборках для разработки.

Включает указанную категорию предупреждений для этого класса.

Подробности

Этот метод существует только в сборках для разработки, поэтому обращаться к нему следует с проверкой, например:

// Enable for all ReactiveElement subclasses
ReactiveElement.enableWarning?.('migration');
// Enable for only MyElement and subclasses
MyElement.enableWarning?.('migration');

Вызывается, когда компонент добавляется в DOM документа.

Подробности

В connectedCallback() следует настраивать задачи, которые должны выполняться только при подключении элемента к документу. Чаще всего это добавление обработчиков событий к узлам вне элемента, например обработчика события keydown для окна.

connectedCallback() {
  super.connectedCallback();
  addEventListener('keydown', this._handleKeydown);
}

Как правило, всё, что выполняется в connectedCallback(), следует отменять при отключении элемента — в disconnectedCallback().

Вызывается, когда компонент удаляется из DOM документа.

Подробности

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

disconnectedCallback() {
  super.disconnectedCallback();
  window.removeEventListener('keydown', this._handleKeydown);
}

Элемент можно повторно подключить после отключения.

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

Параметры

initializer

Initializer

Подробности

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

const myDecorator = (target: typeof ReactiveElement, key: string) => {
  target.addInitializer((instance: ReactiveElement) => {
    // This is run during construction of the element
    new MyController(instance);
  });
}

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

class MyElement extends LitElement {
  @myDecorator foo;
}

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

Создаёт средства доступа к зарегистрированным свойствам, настраивает стили элемента и обеспечивает финализацию всех суперклассов. Возвращает true, если финализация элемента выполнена.

Убедитесь, что класс помечен как finalized, чтобы оптимизация исключила ненужные попытки finalize.

Подробности

Обратите внимание: имя этого свойства является строкой, чтобы не нарушать оптимизации Closure JS Compiler. Дополнительные сведения см. в @lit/reactive-element.

Создаёт средство доступа к свойству в прототипе элемента, если оно ещё не существует, и сохраняет PropertyDeclaration для свойства с заданными параметрами. Сеттер свойства вызывает параметр свойства hasChanged или использует проверку строгого равенства идентичности, чтобы определить, следует ли запрашивать обновление.

Параметры

name

PropertyKey

options?

PropertyDeclaration<unknown, unknown>

Подробности

Этот метод можно переопределить для настройки свойств, однако при этом важно вызвать super.createProperty, чтобы свойство было настроено правильно. Внутри метод вызывает getPropertyDescriptor, чтобы получить дескриптор для установки. Чтобы настроить поведение свойств при чтении или записи, переопределите getPropertyDescriptor. Чтобы настроить параметры свойства, реализуйте createProperty следующим образом:

static createProperty(name, options) {
  options = Object.assign(options, {myOption: true});
  super.createProperty(name, options);
}

Кэшированный список всех свойств элемента, включая свойства суперклассов. Лениво создаётся в пользовательских подклассах при финализации класса.

Возвращает дескриптор свойства, который следует определить для свойства с заданным именем. Если дескриптор не возвращён, свойство не станет средством доступа. Например:

Параметры

name

PropertyKey

key

string | symbol

options

PropertyDeclaration<unknown, unknown>

Подробности

class MyElement extends LitElement {
  static getPropertyDescriptor(name, key, options) {
    const defaultDescriptor =
        super.getPropertyDescriptor(name, key, options);
    const setter = defaultDescriptor.set;
    return {
      get: defaultDescriptor.get,
      set(value) {
        setter.call(this, value);
        // custom action.
      },
      configurable: true,
      enumerable: true
    }
  }
}

Возвращает параметры, связанные с указанным свойством. Эти параметры задаются с помощью PropertyDeclaration через объект properties или декоратор @property и регистрируются в createProperty(...).

Параметры

name

PropertyKey

Подробности

Обратите внимание: этот метод следует считать «финальным» и не переопределять. Чтобы настроить параметры свойства, переопределите createProperty.

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

Подробности

По умолчанию свойства являются открытыми полями, поэтому предполагается, что их в первую очередь устанавливают пользователи элемента — через атрибут или непосредственно через свойство. Как правило, свойства, изменяемые самим элементом, должны быть закрытыми или защищёнными полями и использовать параметр state: true. Свойства, помеченные как state, не отражаются в соответствующем атрибуте. Однако иногда коду элемента требуется установить открытое свойство. Обычно это следует делать только в ответ на взаимодействие с пользователем, отправляя событие, которое его об этом уведомляет; например, флажок при нажатии устанавливает свойство checked и отправляет событие changed. Как правило, не следует изменять открытые свойства, содержащие не примитивные значения (объекты или массивы). В остальных случаях, когда элементу необходимо управлять состоянием, следует использовать закрытое свойство с параметром state: true. При необходимости свойства состояния можно инициализировать через открытые свойства, чтобы обеспечить сложные взаимодействия.

Вызывается при каждом обновлении для выполнения задач рендеринга. Этот метод может возвращать любое значение, которое можно отобразить средствами ChildPart lit-html, обычно TemplateResult. Установка свойств внутри этого метода не приведёт к обновлению элемента.

Узел или ShadowRoot, в который выполняется рендеринг DOM элемента. По умолчанию используется открытый shadowRoot.

Параметры, используемые при вызове attachShadow. Задайте это свойство, чтобы настроить параметры shadowRoot; например, создать закрытый shadowRoot: {mode: 'closed'}.

Подробности

Обратите внимание: эти параметры используются в createRenderRoot. Если этот метод настроен, по возможности следует учитывать заданные параметры.

Кэшированный список всех стилей элемента. Лениво создаётся в пользовательских подклассах при финализации класса.

Получает стили, заданные пользователем через свойство static styles, и возвращает массив стилей для применения к элементу. Переопределите этот метод для интеграции с системой управления стилями.

Параметры

styles?

CSSResultGroup

Подробности

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

Массив стилей для применения к элементу. Стили следует определять с помощью теговой функции css, конструктивных таблиц стилей или импортировать из нативных CSS-модулей.

Подробности

Примечание о политике безопасности содержимого (CSP): если браузер не поддерживает принятые таблицы стилей, стили элементов реализуются с помощью тегов <style>. Чтобы использовать такие теги <style> с директивой CSP style-src, значение style-src должно включать либо 'unsafe-inline', либо nonce-<base64-value>, где <base64-value> заменено на nonce, сгенерированный сервером. Чтобы задать nonce для создаваемых элементов <style>, до загрузки кода приложения установите window.litNonce в nonce, сгенерированный сервером, в HTML-коде страницы:

<script>
  // Generated and unique per request:
  window.litNonce = 'a1b2c3d4';
</script>

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

Параметры

_requestedUpdate

boolean

Вызывается при первом обновлении элемента. Реализуйте этот метод, чтобы выполнить разовую задачу с элементом после обновления.

Параметры

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

Отображение изменённых свойств с их старыми значениями

Подробности

firstUpdated() {
  this.renderRoot.getElementById('my-text-area').focus();
}

Изменение свойств внутри этого метода приведёт к повторному обновлению элемента после завершения текущего цикла обновления.

Точка переопределения для Promise updateComplete.

Подробности

Переопределять непосредственно геттер updateComplete небезопасно из-за ограничения TypeScript, которое не позволяет вызвать геттер суперкласса (например, super.updateComplete.then(...)), если целевой язык — ES5 (https://github.com/microsoft/TypeScript/issues/338). Вместо этого следует переопределить этот метод. Например:

class MyElement extends LitElement {
  override async getUpdateComplete() {
    const result = await super.getUpdateComplete();
    await this._myChild.updateComplete;
    return result;
  }
}

После первого обновления принимает значение true. Код элемента не может предполагать, что renderRoot существует до вызова hasUpdated элемента.

Значение True, если ожидается обновление, вызванное requestUpdate(). Следует только считывать.

Выполняет обновление элемента. Обратите внимание: если во время обновления возникает исключение, вызовы firstUpdated и updated не выполняются.

Подробности

Вызовите performUpdate(), чтобы немедленно обработать ожидающее обновление. Обычно в этом нет необходимости, но в редких случаях это можно сделать, если требуется синхронное обновление. Примечание: чтобы performUpdate() синхронно завершал ожидающее обновление, его не следует переопределять. В LitElement 2.x предлагалось переопределять performUpdate(), чтобы также настраивать планирование обновлений. Вместо этого теперь следует переопределять scheduleUpdate(). Для обратной совместимости с LitElement 2.x планирование обновлений с помощью performUpdate() по-прежнему работает, но затрудняет синхронную обработку обновлений при вызове performUpdate().

Запрашивает обновление, которое будет выполнено асинхронно. Этот метод следует вызывать, когда элемент должен обновиться в ответ на изменение состояния, не вызванное установкой реактивного свойства. В этом случае не передавайте аргументы. Его также следует вызывать при ручной реализации сеттера свойства. В этом случае передайте свойство name и oldValue, чтобы применялись все настроенные параметры свойства.

Параметры

name?

PropertyKey

имя свойства, для которого запрашивается обновление

oldValue?

unknown

старое значение свойства, для которого запрашивается обновление

options?

PropertyDeclaration<unknown, unknown>

параметры свойства, используемые вместо ранее настроенных параметров

Планирует обновление элемента. Можно переопределить этот метод, чтобы изменить время выполнения обновлений, возвращая Promise. Обновление будет ожидать выполнения возвращённого Promise; для продолжения обновления необходимо выполнить его. При переопределении этого метода необходимо вызвать super.scheduleUpdate().

Подробности

Например, чтобы запланировать обновления непосредственно перед следующим кадром:

override protected async scheduleUpdate(): Promise<unknown> {
  await new Promise((resolve) => requestAnimationFrame(() => resolve()));
  super.scheduleUpdate();
}

Определяет, следует ли вызывать update() при запросе обновления элемента. По умолчанию этот метод всегда возвращает true, но его можно настроить, чтобы управлять моментом обновления.

Параметры

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

Отображение изменённых свойств с их старыми значениями

Обновляет элемент. Этот метод отражает значения свойств в атрибутах и вызывает render для отображения DOM с помощью lit-html. Изменение свойств внутри этого метода не вызовет повторное обновление.

Параметры

changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

Отображение изменённых свойств с их старыми значениями

Возвращает Promise, который выполняется после завершения обновления элемента. Значение Promise — логическое значение: true, если элемент завершил обновление, не вызвав нового обновления. Результат Promise равен false, если внутри updated() было установлено свойство. Если Promise отклонён, во время обновления возникло исключение.

Подробности

Чтобы дождаться завершения дополнительной асинхронной работы, переопределите метод getUpdateComplete. Например, иногда полезно дождаться отображения элемента, прежде чем выполнить этот Promise. Для этого сначала дождитесь super.getUpdateComplete(), а затем любого последующего состояния.

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

Параметры

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

Отображение изменённых свойств с их старыми значениями

Подробности

Изменение свойств внутри этого метода приведёт к повторному обновлению элемента после завершения текущего цикла обновления.

Вызывается перед update() для вычисления значений, необходимых во время обновления.

Параметры

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

Подробности

Реализуйте willUpdate, чтобы вычислять значения свойств, зависящие от других свойств и используемые на остальных этапах обновления.

willUpdate(changedProperties) {
  // only need to check changed properties for an expensive computation.
  if (changedProperties.has('firstName') || changedProperties.has('lastName')) {
    this.sha = computeSHA(`${this.firstName} ${this.lastName}`);
  }
}
render() {
  return html`SHA: ${this.sha}`;
}

Узел, используемый для клонирования шаблона (для этого узла будет вызван importNode). Это определяет ownerDocument отображаемого DOM вместе с любым унаследованным контекстом. По умолчанию используется глобальный document.

Объект, используемый в качестве значения this для обработчиков событий. Часто полезно указать здесь хост-компонент, выполняющий рендеринг шаблона.

Начальное состояние подключения верхнеуровневой части, для которой выполняется рендеринг. Если параметр isConnected не задан, AsyncDirective по умолчанию будут подключены. Установите значение false, если первоначальный рендеринг выполняется в отключённом дереве и AsyncDirective должны видеть isConnected === false при первоначальном рендеринге. Для изменения состояния подключения части после первоначального рендеринга необходимо использовать метод part.setConnected().

Узел DOM, перед которым следует отобразить содержимое контейнера.