ReactiveElement

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

Параметры

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');

При первом подключении создаёт renderRoot элемента, настраивает стили элемента и включает обновление.

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

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

Параметры

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, если инициализация элемента завершена.

Отмечает, что создание свойств класса завершено.

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

Возвращает узел, в который должен выполнять рендеринг элемент; по умолчанию создаёт и возвращает открытый shadowRoot. Реализуйте этот метод, чтобы настроить место рендеринга DOM элемента. Например, чтобы выполнять рендеринг в дочерние узлы элемента, верните this.

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

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

Подробности

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

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

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

Параметры

styles?

CSSResultGroup

Подробности

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

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

Подробности

Примечание о политике безопасности содержимого: стили элементов реализованы с помощью тегов <style>, если браузер не поддерживает adopted StyleSheets. Чтобы использовать такие теги <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>

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

Планирует обновление элемента. Этот метод можно переопределить, чтобы изменить время обновлений, возвратив 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>

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

Обновляет элемент. Этот метод отражает значения свойств в атрибутах. Его можно переопределить, чтобы отрисовывать и поддерживать DOM элемента в актуальном состоянии. Изменение свойств внутри этого метода не вызовет ещё одно обновление.

Параметры

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

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

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

Подробности

Чтобы дождаться дополнительной асинхронной работы, переопределите метод getUpdateComplete. Например, иногда полезно дождаться отрисовки элемента, прежде чем завершить этот Promise. Для этого сначала дождитесь 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}`;
}

Вызывается для преобразования значения атрибута в значение свойства.

Параметры

value

null | string

type?

TypeHint

Вызывается для преобразования значения свойства в значение атрибута.

Параметры

value

Type

type?

TypeHint

Подробности

Возвращает unknown вместо string для совместимости с https://github.com/WICG/trusted-types и аналогичными инициативами.

Указывает, становится ли свойство наблюдаемым атрибутом и каким образом. Если значение равно false, свойство не добавляется в observedAttributes. Если значение равно true или не задано, наблюдается имя свойства в нижнем регистре (например, fooBar становится foobar). Если задана строка, наблюдается это строковое значение (например, attribute: 'foo-bar').

Указывает, как преобразовывать атрибут в свойство и обратно. Если это значение является функцией, она используется для преобразования значения атрибута в значение свойства. Если это объект, он может содержать ключи fromAttribute и toAttribute. Если функция toAttribute не указана, а reflect установлено в true, значение свойства напрямую присваивается атрибуту. Если преобразователь converter не указан, используется преобразователь по умолчанию; он поддерживает Boolean, String, Number, Object и Array. Обратите внимание: когда свойство изменяется и преобразователь используется для обновления атрибута, последующее изменение атрибута не обновляет свойство, и наоборот.

Указывает, будет ли для этого свойства создан аксессор. По умолчанию для этого свойства создаётся аксессор, который запрашивает обновление при установке значения. Если этот флаг равен true, аксессор не создаётся, и пользователь должен самостоятельно вызывать this.requestUpdate(propertyName, oldValue) для запроса обновления при изменении свойства.

Указывает, следует ли отражать свойство в атрибуте. Если true, при установке свойства устанавливается атрибут с именем, определённым согласно правилам параметра свойства attribute, и значением свойства, преобразованным согласно правилам параметра свойства converter.

Если установлено значение true, указывает, что свойство является внутренним приватным состоянием. Пользователи не должны задавать это свойство. При использовании TypeScript это свойство следует пометить как private или protected; также принято добавлять в начало имени _. Свойство не добавляется в observedAttributes.

Указывает тип свойства. Используется только как подсказка для converter, определяющая способ преобразования атрибута в свойство и обратно.

Функция, определяющая, следует ли считать свойство изменившимся при его установке. Функция должна принимать newValue и oldValue и возвращать true, если следует запросить обновление.

Параметры

value

Type

oldValue

Type