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-модулей.

Подробности

Примечание о политике безопасности содержимого (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();
}

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

Метод для переопределения промиса 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; для продолжения обновления необходимо разрешить 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(), а затем любого последующего состояния.

Вызывается после каждого обновления элемента. Реализуйте этот метод, чтобы выполнять задачи после обновления с помощью 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}`;
}

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

Параметры

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