LitElement

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

Параметры

name

string

_old

null | string

value

null | string

Подробности

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

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

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

Параметры

controller

ReactiveController

Подробности

Если элемент подключен к документу в момент вызова 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, добавленного к window.

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.

Подробности

Примечание о политике безопасности содержимого: стили элементов реализуются с помощью тегов <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();
}

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

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

Подробности

Непосредственно переопределять геттер updateComplete небезопасно из-за ограничения TypeScript: при целевом языке ES5 невозможно вызвать геттер суперкласса (например, super.updateComplete.then(...)) (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>

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

Планирует обновление элемента. Чтобы изменить время выполнения обновлений, можно переопределить этот метод и вернуть промис. Обновление будет ожидать завершения возвращённого промиса; чтобы продолжить обновление, необходимо выполнить этот промис. При переопределении этого метода необходимо вызвать 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>

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

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

Подробности

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

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

Параметры

_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, перед которым нужно отрисовать содержимое контейнера.