Директивы

Директива, которая отображает элементы асинхронного итерируемого объекта[1], добавляя новые значения после предыдущих, подобно встроенной поддержке итерируемых объектов. Эту директиву можно использовать только в дочерних выражениях.

Импорт

import { asyncAppend } from 'lit/directives/async-append.js';

Сигнатура

asyncAppend(value, _mapper?): DirectiveResult<AsyncAppendDirective>

Параметры

value

AsyncIterable<unknown>

Асинхронный итерируемый объект

_mapper?

(v: unknown, index?: number) => unknown

Подробности

Асинхронные итерируемые объекты — это объекты с методом [Symbol.asyncIterator], который возвращает итератор, чей метод next() возвращает Promise. Когда становится доступно новое значение, Promise разрешается, и значение добавляется в Part, управляемый директивой. Если для Part задано другое значение, не являющееся этой директивой, прослушивание итерируемого объекта прекращается, и новые значения не будут записываться в Part. [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of

Абстрактный базовый класс Directive, метод disconnected которого будет вызван, когда содержащий директиву Part очищается в результате повторного рендеринга или когда пользователь вызывает part.setConnected(false) для Part, ранее отрендеренного с этой директивой (например, когда LitElement отключается от DOM).

Импорт

import { AsyncAppendDirective } from 'lit/directives/async-append.js';

Подробности

Если впоследствии для содержащего Part вызывается part.setConnected(true), метод reconnected директивы будет вызван до её следующих обратных вызовов update/render. При реализации disconnected для совместимости с повторным подключением также следует реализовать reconnected. Обратите внимание, что обновления могут происходить, пока директива отключена. Поэтому директивам обычно следует проверять флаг this.isConnected во время render/update, чтобы определить, безопасно ли подписываться на ресурсы, которые могут препятствовать сборке мусора.

Директива, которая отображает элементы асинхронного итерируемого объекта[1], заменяя предыдущие значения новыми, так что одновременно отображается только одно значение. Эту директиву можно использовать в выражении любого типа.

Импорт

import { asyncReplace } from 'lit/directives/async-replace.js';

Сигнатура

asyncReplace(value, _mapper?): DirectiveResult<AsyncReplaceDirective>

Параметры

value

AsyncIterable<unknown>

Асинхронный итерируемый объект

_mapper?

Mapper<unknown>

Подробности

Асинхронные итерируемые объекты — это объекты с методом [Symbol.asyncIterator], который возвращает итератор, чей метод next() возвращает Promise. Когда становится доступно новое значение, Promise разрешается, и значение отображается в Part, управляемом директивой. Если для Part задано другое значение, не являющееся этой директивой, прослушивание итерируемого объекта прекращается, и новые значения не будут записываться в Part. [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of

Абстрактный базовый класс Directive, метод disconnected которого будет вызван, когда содержащий директиву Part очищается в результате повторного рендеринга или когда пользователь вызывает part.setConnected(false) для Part, ранее отрендеренного с этой директивой (например, когда LitElement отключается от DOM).

Импорт

import { AsyncReplaceDirective } from 'lit/directives/async-replace.js';

Подробности

Если впоследствии для содержащего Part вызывается part.setConnected(true), метод reconnected директивы будет вызван до её следующих обратных вызовов update/render. При реализации disconnected для совместимости с повторным подключением также следует реализовать reconnected. Обратите внимание, что обновления могут происходить, пока директива отключена. Поэтому директивам обычно следует проверять флаг this.isConnected во время render/update, чтобы определить, безопасно ли подписываться на ресурсы, которые могут препятствовать сборке мусора.

Позволяет быстро переключаться между несколькими шаблонами, кешируя узлы DOM и экземпляры TemplateInstance, созданные этими шаблонами.

Импорт

import { cache } from 'lit/directives/cache.js';

Сигнатура

cache(v): DirectiveResult<CacheDirective>

Параметры

v

unknown

Подробности

Пример:

let checked = false;
html`
  ${cache(checked ? html`input is checked` : html`input is not checked`)}
`

Базовый класс для создания пользовательских директив. Пользователям следует унаследовать этот класс, реализовать render и/или update, а затем передать подкласс в directive.

Импорт

import { CacheDirective } from 'lit/directives/cache.js';

Выбирает и вычисляет функцию шаблона из списка на основе соответствия заданного value одному из вариантов.

Импорт

import { choose } from 'lit/directives/choose.js';

Сигнатура

choose(value, cases, defaultCase?): undefined | V

Параметры

value

T

cases

Array<[T, () => V]>

defaultCase?

() => V

Подробности

Варианты задаются в виде [caseValue, func]. value сопоставляется с caseValue с помощью строгого равенства. Выбирается первое совпадение. Значения вариантов могут быть любого типа, включая примитивы, объекты и символы. Это похоже на оператор switch, но представлено в виде выражения и не допускает перехода к следующему варианту.

Директива для применения динамических CSS-классов.

Импорт

import { classMap } from 'lit/directives/class-map.js';

Сигнатура

classMap(classInfo): DirectiveResult<ClassMapDirective>

Параметры

classInfo

ClassInfo

Подробности

Эту директиву необходимо использовать в атрибуте class, и она должна быть единственной частью этого атрибута. Для каждого свойства аргумента classInfo она добавляет имя свойства в classList элемента, если значение свойства истинно; если значение свойства ложно, имя свойства удаляется из class элемента. Например, {foo: bar} применяет класс foo, если значение bar истинно.

Базовый класс для создания пользовательских директив. Пользователям следует унаследовать этот класс, реализовать render и/или update, а затем передать подкласс в directive.

Импорт

import { ClassMapDirective } from 'lit/directives/class-map.js';

Набор пар «ключ—значение», где имена классов сопоставлены с истинными значениями.

Импорт

import { ClassInfo } from 'lit/directives/class-map.js';

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

Импорт

import { guard } from 'lit/directives/guard.js';

Сигнатура

guard(_value, f): DirectiveResult<GuardDirective>

Параметры

_value

unknown

f

() => unknown

функция шаблона

Подробности

Значения сравниваются с предыдущими с помощью строгого равенства (===), поэтому проверка не обнаруживает изменения вложенных свойств объектов или массивов. Для значений-массивов каждый элемент сравнивается с предыдущим значением по тому же индексу с помощью строгого равенства. Вложенные массивы также проверяются только на строгое равенство. Пример:

html`
  <div>
    ${guard([user.id, company.id], () => html`...`)}
  </div>
`

В этом случае шаблон повторно отрисовывается, только если изменится user.id или company.id. guard() полезна при использовании шаблонов проектирования с неизменяемыми данными: она предотвращает выполнение затратных операций до обновления данных. Пример:

html`
  <div>
    ${guard([immutableItems], () => immutableItems.map(i => html`${i}`))}
  </div>
`

В этом случае элементы отображаются из массива только при изменении ссылки на массив.

Базовый класс для создания пользовательских директив. Пользователям следует унаследовать этот класс, реализовать render и/или update, а затем передать подкласс в directive.

Импорт

import { GuardDirective } from 'lit/directives/guard.js';

Для AttributeParts задаёт атрибут, если значение определено, и удаляет его, если значение равно undefined.

Импорт

import { ifDefined } from 'lit/directives/if-defined.js';

Сигнатура

ifDefined(value): nothing | NonNullable<T>

Параметры

value

T

Подробности

Для других типов Part эта директива ничего не делает.

Возвращает итерируемый объект, содержащий значения из items, разделённые значением joiner.

Импорт

import { join } from 'lit/directives/join.js';

Сигнатура

join(items, joiner): Iterable<I | J>

Параметры

items

undefined | Iterable<I>

joiner

(index: number) => J

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

Импорт

import { keyed } from 'lit/directives/keyed.js';

Сигнатура

keyed(k, v): DirectiveResult<Keyed>

Параметры

k

unknown

v

unknown

Подробности

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

Базовый класс для создания пользовательских директив. Пользователям следует унаследовать этот класс, реализовать render и/или update, а затем передать подкласс в directive.

Импорт

import { Keyed } from 'lit/directives/keyed.js';

При определении необходимости обновить значение сравнивает значения привязки с текущими значениями DOM, а не с ранее привязанными значениями.

Импорт

import { live } from 'lit/directives/live.js';

Сигнатура

live(value): DirectiveResult<LiveDirective>

Параметры

value

unknown

Подробности

Это полезно в случаях, когда значение DOM может измениться вне lit-html, например при привязке к свойству value элемента <input>, к тексту элемента с редактируемым содержимым или к пользовательскому элементу, который изменяет собственные свойства или атрибуты. В таких случаях, если значение DOM изменится, а значение, заданное с помощью привязок lit-html, останется прежним, lit-html не узнает о необходимости обновить значение DOM и оставит его без изменений. Если вам нужно другое поведение — если вы хотите перезаписывать значение DOM привязанным значением в любом случае, — используйте директиву live():

html`<input .value=${live(x)}>`

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

Базовый класс для создания пользовательских директив. Пользователям следует наследовать этот класс, реализовать render и/или update, а затем передать подкласс в directive.

Импорт

import { LiveDirective } from 'lit/directives/live.js';

Возвращает итерируемый объект, содержащий результат вызова f(value) для каждого значения в items.

Импорт

import { map } from 'lit/directives/map.js';

Сигнатура

map(items, f): Generator<unknown, void, unknown>

Параметры

items

undefined | Iterable<T>

f

(value: T, index: number) => unknown

Возвращает итерируемый объект с целыми числами от start до end (не включая его), увеличивая значение на step.

Импорт

import { range } from 'lit/directives/range.js';

Сигнатура

range(end): Iterable<number>

Параметры

end

number

Подробности

Если start не задан, диапазон начинается с 0. Значение step по умолчанию равно 1.

Создает новый объект Ref — контейнер для ссылки на элемент.

Импорт

import { createRef } from 'lit/directives/ref.js';

Сигнатура

createRef(): Ref<T>

Задает значение объекта Ref или вызывает обратный вызов ref с элементом, к которому он привязан.

Импорт

import { ref } from 'lit/directives/ref.js';

Сигнатура

ref(_ref): DirectiveResult<RefDirective>

Параметры

_ref

RefOrCallback

Подробности

Объект Ref служит контейнером для ссылки на элемент. Обратный вызов ref — это функция, принимающая элемент в качестве единственного аргумента. Во время рендеринга директива ref задает значение объекта Ref или вызывает обратный вызов ref, если связанный элемент изменился. Примечание. Если обратный вызов ref при последующем рендеринге привязывается к другой позиции элемента или удаляется, сначала он будет вызван с аргументом undefined, а затем еще раз — с новым элементом, для которого он был отрендерен (если такой есть).

// Using Ref object
const inputRef = createRef();
render(html`<input ${ref(inputRef)}>`, container);
inputRef.value.focus();
// Using callback
const callback = (inputElement) => inputElement.focus();
render(html`<input ${ref(callback)}>`, container);

Объект, хранящий значение ссылки.

Импорт

import { Ref } from 'lit/directives/ref.js';

Абстрактный базовый класс Directive, метод disconnected которого будет вызван, когда содержащая директиву часть будет очищена в результате повторного рендеринга или когда пользователь вызовет part.setConnected(false) для части, ранее отрендеренной с этой директивой (например, при отключении LitElement от DOM).

Импорт

import { RefDirective } from 'lit/directives/ref.js';

Подробности

Если впоследствии для содержащей части будет вызван part.setConnected(true), метод reconnected директивы будет вызван до ее следующих обратных вызовов update/render. При реализации disconnected также следует реализовать reconnected, чтобы обеспечить совместимость с повторным подключением. Обратите внимание, что обновления могут происходить, пока директива отключена. Поэтому во время render/update директивам обычно следует проверять флаг this.isConnected, чтобы определить, безопасно ли подписываться на ресурсы, которые могут помешать сборке мусора.

Импорт

import { RefOrCallback } from 'lit/directives/ref.js';

Тип

Директива, которая повторяет последовательность значений (обычно TemplateResults), сформированных из итерируемого объекта, и эффективно обновляет эти элементы при изменении итерируемого объекта на основе предоставленных пользователем keys, связанных с каждым элементом.

Импорт

import { repeat } from 'lit/directives/repeat.js';

Сигнатура

repeat(items, keyFnOrTemplate, template?): unknown

Параметры

items

Iterable<T>

keyFnOrTemplate

KeyFn<T> | ItemTemplate<T>

template?

ItemTemplate<T>

Подробности

Обратите внимание: если задан keyFn, поддерживается строгое соответствие ключей элементам DOM: при необходимости существующий DOM для заданного ключа перемещается на новую позицию, а DOM никогда не переиспользуется для значений с другими ключами (для новых ключей всегда создается новый DOM). Обычно это наиболее эффективный способ использования repeat, поскольку при вставке и удалении он выполняет минимум лишней работы. keyFn принимает два параметра — элемент и его индекс — и возвращает уникальное значение ключа.

html`
  <ol>
    ${repeat(this.items, (item) => item.id, (item, index) => {
      return html`<li>${index}: ${item.name}</li>`;
    })}
  </ol>
`

Важно: если задан keyFn, ключи должны быть уникальными для всех элементов в одном вызове repeat. Поведение при наличии двух или более элементов с одинаковым ключом не определено. Если keyFn не задан, эта директива работает аналогично отображению элементов в значения, и DOM может использоваться повторно для других элементов.

Базовый класс для создания пользовательских директив. Пользователям следует наследовать этот класс, реализовать render и/или update, а затем передать подкласс в directive.

Импорт

import { RepeatDirective } from 'lit/directives/repeat.js';

Импорт

import { ItemTemplate } from 'lit/directives/repeat.js';

Тип

Импорт

import { KeyFn } from 'lit/directives/repeat.js';

Тип

Импорт

import { RepeatDirectiveFn } from 'lit/directives/repeat.js';

Сигнатура

RepeatDirectiveFn(items, keyFnOrTemplate, template?): unknown

Параметры

items

Iterable<T>

keyFnOrTemplate

KeyFn<T> | ItemTemplate<T>

template?

ItemTemplate<T>

Директива, применяющая CSS-свойства к элементу.

Импорт

import { styleMap } from 'lit/directives/style-map.js';

Сигнатура

styleMap(styleInfo): DirectiveResult<StyleMapDirective>

Параметры

styleInfo

Readonly<StyleInfo>

Подробности

styleMap можно использовать только в атрибуте style, и это должно быть единственное выражение в атрибуте. Директива берет имена свойств из объекта styleInfo и добавляет их во встроенный стиль элемента. Имена с дефисами (-) считаются допустимыми именами CSS-свойств и задаются в объекте style элемента с помощью setProperty(). Имена без дефисов считаются именами свойств JavaScript в camelCase и задаются в объекте style элемента путем присваивания свойства, что позволяет объекту style преобразовывать имена в стиле JavaScript в имена CSS-свойств. Например, styleMap({backgroundColor: 'red', 'border-top': '5px', '--size': '0'}) задает свойства background-color, border-top и --size.

Базовый класс для создания пользовательских директив. Пользователям следует наследовать этот класс, реализовать render и/или update, а затем передать подкласс в directive.

Импорт

import { StyleMapDirective } from 'lit/directives/style-map.js';

Набор пар «ключ-значение» для CSS-свойств и их значений.

Импорт

import { StyleInfo } from 'lit/directives/style-map.js';

Подробности

Ключом должна быть либо строка с допустимым именем CSS-свойства, например 'background-color', либо допустимое имя свойства CSSStyleDeclaration в camelCase в JavaScript, например backgroundColor.

Рендерит содержимое элемента template как HTML.

Импорт

import { templateContent } from 'lit/directives/template-content.js';

Сигнатура

templateContent(template): DirectiveResult<TemplateContentDirective>

Параметры

template

HTMLTemplateElement

Подробности

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

Базовый класс для создания пользовательских директив. Пользователям следует наследовать этот класс, реализовать render и/или update, а затем передать подкласс в directive.

Импорт

import { TemplateContentDirective } from 'lit/directives/template-content.js';

Рендерит результат как HTML, а не как текст.

Импорт

import { unsafeHTML } from 'lit/directives/unsafe-html.js';

Сигнатура

unsafeHTML(value): DirectiveResult<UnsafeHTMLDirective>

Параметры

value

undefined | null | string | noChange | nothing

Подробности

Значения undefined, null и nothing приведут к тому, что ничего не будет отрисовано (пустая строка). Обратите внимание: это небезопасно использовать с пользовательскими данными, которые не были очищены или экранированы, поскольку это может привести к уязвимостям межсайтового скриптинга.

Базовый класс для создания пользовательских директив. Пользователям следует унаследовать этот класс, реализовать render и/или update, а затем передать его подкласс в directive.

Импорт

import { UnsafeHTMLDirective } from 'lit/directives/unsafe-html.js';

Отрисовывает результат как SVG, а не как текст.

Импорт

import { unsafeSVG } from 'lit/directives/unsafe-svg.js';

Сигнатура

unsafeSVG(value): DirectiveResult<UnsafeSVGDirective>

Параметры

value

undefined | null | string | noChange | nothing

Подробности

Значения undefined, null и nothing приведут к тому, что ничего не будет отрисовано (пустая строка). Обратите внимание: это небезопасно использовать с пользовательскими данными, которые не были очищены или экранированы, поскольку это может привести к уязвимостям межсайтового скриптинга.

Базовый класс для создания пользовательских директив. Пользователям следует унаследовать этот класс, реализовать render и/или update, а затем передать его подкласс в directive.

Импорт

import { UnsafeSVGDirective } from 'lit/directives/unsafe-svg.js';

Отрисовывает в Part одно из ряда значений, включая Promise.

Импорт

import { until } from 'lit/directives/until.js';

Сигнатура

until(values): DirectiveResult<UntilDirective>

Параметры

values

Array<unknown>

Подробности

Значения отрисовываются в порядке приоритета: первый аргумент имеет наивысший приоритет, а последний — наименьший. Если значение представляет собой Promise, значения с низким приоритетом будут отрисовываться до его разрешения. Приоритет значений можно использовать для создания содержимого-заполнителя для асинхронных данных. Например, Promise с ожидаемым содержимым может быть первым аргументом с наивысшим приоритетом, а шаблон индикатора загрузки non_promise — вторым аргументом с более низким приоритетом. Индикатор загрузки отобразится сразу, а основное содержимое — после разрешения Promise. Пример:

const content = fetch('./content.txt').then(r => r.text());
html`${until(content, html`<span>Loading...</span>`)}`

Абстрактный базовый класс Directive, метод disconnected которого вызывается, когда содержащий директиву Part очищается в результате повторной отрисовки или когда пользователь вызывает part.setConnected(false) для Part, ранее отрисованного с этой директивой (например, когда LitElement отсоединяется от DOM).

Импорт

import { UntilDirective } from 'lit/directives/until.js';

Подробности

Если впоследствии для содержащего Part вызывается part.setConnected(true), метод reconnected директивы будет вызван перед следующими обратными вызовами update/render. При реализации disconnected также следует реализовать reconnected, чтобы обеспечить корректную работу при повторном подключении. Обратите внимание, что обновления могут происходить, пока директива отключена. Поэтому директивам обычно следует проверять флаг this.isConnected при отрисовке/обновлении, чтобы определить, безопасно ли подписываться на ресурсы, которые могут препятствовать сборке мусора.

Если condition равно true, возвращает результат вызова trueCase(), иначе, если falseCase определен, возвращает результат вызова falseCase().

Импорт

import { when } from 'lit/directives/when.js';

Сигнатура

when(condition, trueCase, falseCase?): T

Параметры

condition

true

trueCase

() => T

falseCase?

() => F

Подробности

Это удобная обертка над тернарным выражением, которая упрощает запись встроенного условного выражения без ветви else.