Директивы

Директива, отображающая элементы асинхронного итерируемого объекта[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 для совместимости с повторным подключением. Обратите внимание, что обновления могут происходить, пока директива отключена. Поэтому во время render/update директивам обычно следует проверять флаг this.isConnected, чтобы определить, безопасно ли подписываться на ресурсы, которые могут препятствовать сборке мусора.

Директива, отображающая элементы асинхронного итерируемого объекта[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 для совместимости с повторным подключением. Обратите внимание, что обновления могут происходить, пока директива отключена. Поэтому во время render/update директивам обычно следует проверять флаг this.isConnected, чтобы определить, безопасно ли подписываться на ресурсы, которые могут препятствовать сборке мусора.

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

Импорт

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>
`

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

Базовый класс для создания пользовательских директив. Пользователям следует расширить этот класс, реализовать 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 или вызывает callback-функцию ref с элементом, к которому привязана директива.

Импорт

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

Сигнатура

ref(_ref): DirectiveResult<RefDirective>

Параметры

_ref

RefOrCallback

Подробности

Объект Ref служит контейнером для ссылки на элемент. Callback-функция ref — это функция, принимающая элемент в качестве единственного аргумента. Директива ref задаёт значение объекта Ref или вызывает callback-функцию ref во время рендеринга, если связанный элемент изменился. Примечание: если callback-функция 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);

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

Импорт

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 директивы будет вызван перед её следующими callback-вызовами update/render. При реализации disconnected также следует реализовать reconnected, чтобы обеспечить совместимость с повторным подключением. Обратите внимание, что обновления могут происходить, пока директива отключена. Поэтому директивам обычно следует проверять флаг 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';

Отображает в части одно из нескольких значений, включая Promise.

Импорт

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

Сигнатура

until(values): DirectiveResult<UntilDirective>

Параметры

values

Array<unknown>

Подробности

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

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

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

Импорт

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

Подробности

Если впоследствии для содержащей части будет вызван 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.