Phoenix.LiveView.JS

Добавляет классы элементам.

• names — Строка с одним или несколькими именами классов для добавления.

Параметры

• :to — Необязательный селектор DOM, к которому нужно добавить классы. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.
• :transition — Строка классов, применяемых перед добавлением классов, или кортеж из 3 элементов, содержащий класс перехода, класс для начала перехода и класс для завершения перехода, например: {"ease-out duration-300", "opacity-0", "opacity-100"}
• :time — Время в миллисекундах, в течение которого применяется переход из :transition. По умолчанию — 200.
• :blocking — Логический флаг, блокирующий интерфейс на время перехода. Значение по умолчанию — true.

Примеры

<div id="item">My Item</div>
<button phx-click={JS.add_class("highlight underline", to: "#item")}>
  highlight!
</button>

См. add_class/1.

См. add_class/1.

Объединяет две JS-команды, добавляя вторую в конец первой.

Отправляет событие в DOM.

• event — Строковое имя отправляемого события.

Примечание: Все отправляемые события имеют тип CustomEvent, за исключением "click". Для "click" отправляется MouseEvent, чтобы корректно имитировать щелчок в пользовательском интерфейсе.

Для отправленных CustomEvent'ов данные события будут содержать dispatcher, указывающий на узел DOM, отправивший JS-событие целевому элементу.

Параметры

• :to — Необязательный селектор DOM, которому нужно отправить событие. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.
• :detail — Необязательная карта данных, отправляемая вместе с событием на клиенте. Эти данные будут доступны в атрибуте event.detail обработчикам событий.
• :bubbles — Логический флаг, определяющий, будет ли событие всплывать. По умолчанию — true.
• :blocking — Логический флаг, блокирующий интерфейс до тех пор, пока обработчик события не вызовет event.detail.done(). Функция done добавляется LiveView и должна быть вызвана в конечном итоге, чтобы разблокировать интерфейс. Это полезно для интеграции со сторонними библиотеками анимации на JavaScript.

Примеры

window.addEventListener("click", e => console.log("clicked!", e.detail))

<button phx-click={JS.dispatch("click", to: ".nav")}>Click me!</button>

См. dispatch/2.

Выполняет JS-команды, указанные в атрибуте элемента.

• attr — Строковый атрибут, в котором указана JS-команда

Параметры

• :to — Необязательный селектор DOM, из которого нужно получить атрибут. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.

Примеры

<div id="modal" phx-remove={JS.hide()}>...</div>
<button phx-click={JS.exec("phx-remove", to: "#modal")}>close</button>

См. exec/1.

См. exec/1.

Устанавливает фокус на селектор.

Параметры

• :to — Необязательный селектор DOM, на который нужно установить фокус. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.

Примеры

JS.focus(to: "main")

См. focus/1.

Устанавливает фокус на первый элемент в селекторе, поддерживающий фокус.

Параметры

• :to — Необязательный селектор DOM, на который нужно установить фокус. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.

Примеры

JS.focus_first(to: "#modal")

См. focus_first/1.

Скрывает элементы.

Примечание: Целевыми становятся только видимые элементы, то есть элементы с высотой и/или шириной больше нуля.

Параметры

• :to — Необязательный селектор DOM, элементы которого нужно скрыть. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.
• :transition — Строка классов, применяемых перед скрытием, или кортеж из 3 элементов, содержащий класс перехода, класс для начала перехода и класс для завершения перехода, например: {"ease-out duration-300", "opacity-100", "opacity-0"}
• :time — Время в миллисекундах, в течение которого применяется переход из :transition. По умолчанию — 200.
• :blocking — Логический флаг, блокирующий интерфейс на время перехода. Значение по умолчанию — true.

В процессе к скрываемым элементам будут отправлены следующие события:

• При запуске действия на клиенте отправляется phx:hide-start.
• По истечении времени, указанного в :time, отправляется phx:hide-end.

Примеры

<div id="item">My Item</div>

<button phx-click={JS.hide(to: "#item")}>
  hide!
</button>

<button phx-click={JS.hide(to: "#item", transition: "fade-out-scale")}>
  hide fancy!
</button>

См. hide/1.

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

Принимает одно имя атрибута или список имён атрибутов. В качестве подстановочного знака можно использовать звёздочку *.

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

Чтобы снять отметку с атрибута, нужно повторно вызвать ignore_attributes/1, передав обновлённый список атрибутов.

Чаще всего это полезно в сочетании с привязкой phx-mounted, например:

<dialog phx-mounted={JS.ignore_attributes("open")}>
  ...
</dialog>

Параметры

• :to — Необязательный селектор DOM для выбора целевого элемента. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.

Примеры

JS.ignore_attributes(["open", "data-*"], to: "#my-dialog")

Отправляет событие навигации на сервер и обновляет историю pushState браузера.

Параметры

• :replace — Заменять ли историю pushState браузера. По умолчанию — false.

Примеры

JS.navigate("/my-path")

См. navigate/1.

См. navigate/1.

Отправляет событие обновления на сервер и обновляет историю pushState браузера.

Параметры

• :replace — Заменять ли историю pushState браузера. По умолчанию — false.

Примеры

JS.patch("/my-path")

См. patch/1.

См. patch/1.

Устанавливает фокус на последний добавленный в стек элемент.

Примеры

JS.pop_focus()

Отправляет событие на сервер.

• event — Строковое имя отправляемого события.

Параметры

• :target — Селектор или идентификатор компонента, которому нужно отправить событие. Это значение заменит любой атрибут phx-target, присутствующий у элемента.
• :loading — Селектор, к которому нужно применить классы загрузки phx, например phx-click-loading, если событие было вызвано с помощью phx-click. Обновления с сервера будут заблокированы для элемента до подтверждения отправки сервером.
• :page_loading — Логическое значение, определяющее, нужно ли вызывать события phx:page-loading-start и phx:page-loading-stop для этой отправки. По умолчанию — false.
• :value — Карта значений для отправки на сервер. Эти значения объединяются с любыми атрибутами phx-value-*, присутствующими у элемента, и переопределяют их. При объединении все ключи рассматриваются как строки. Для событий формы, таких как phx-change или phx-submit, приоритет определяется следующим образом: JS.push value > phx-value-* > input value.

Примеры

<button phx-click={JS.push("clicked")}>click me!</button>
<button phx-click={JS.push("clicked", value: %{id: @id})}>click me!</button>
<button phx-click={JS.push("clicked", page_loading: true)}>click me!</button>

См. push/1.

См. push/1.

Сохраняет фокус с исходного элемента, чтобы позже его можно было восстановить.

Параметры

• :to — Необязательный селектор DOM, для которого нужно сохранить фокус. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.

Примеры

JS.push_focus()
JS.push_focus(to: "#my-button")

См. push_focus/1.

Удаляет атрибут у элементов.

• attr — Строковое имя удаляемого атрибута.

Параметры

• :to — Необязательный селектор DOM, у элементов которого нужно удалить атрибуты. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.

Примеры

<button phx-click={JS.remove_attribute("aria-expanded", to: "#dropdown")}>
  hide
</button>

См. remove_attribute/1.

См. remove_attribute/1.

Удаляет классы у элементов.

• names — Строка с одним или несколькими именами классов для удаления.

Параметры

• :to — Необязательный селектор DOM, у элементов которого нужно удалить классы. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.
• :transition — Строка классов, применяемых перед удалением классов, или кортеж из 3 элементов, содержащий класс перехода, класс для начала перехода и класс для завершения перехода, например: {"ease-out duration-300", "opacity-0", "opacity-100"}
• :time — Время в миллисекундах, в течение которого применяется переход из :transition. По умолчанию — 200.
• :blocking — Логический флаг, блокирующий интерфейс на время перехода. Значение по умолчанию — true.

Примеры

<div id="item">My Item</div>
<button phx-click={JS.remove_class("highlight underline", to: "#item")}>
  remove highlight!
</button>

См. remove_class/1.

См. remove_class/1.

Устанавливает атрибуты для элементов.

Принимает кортеж со строковыми именем и значением атрибута.

Параметры

• :to — Необязательный селектор DOM, элементам которого нужно добавить атрибуты. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.

Примеры

<button phx-click={JS.set_attribute({"aria-expanded", "true"}, to: "#dropdown")}>
  show
</button>

<.button phx-click={JS.set_attribute({"value", ""}, to: "#my_input")}>...</.button>

<script :type={Phoenix.LiveView.ColocatedJS} name="clear_input">
  window.addEventListener("input:clear", (e) => {
    e.target.value = ""
    e.target.dispatchEvent(new Event("input", {bubbles: true}))
  })
</script>
<.button phx-click={JS.dispatch("input:clear", to: "#my_input")}>...</.button>

См. set_attribute/1.

См. set_attribute/1.

Показывает элементы.

Примечание: Целевыми становятся только скрытые элементы, то есть элементы с высотой и/или шириной, равной нулю.

Параметры

• :to — Необязательный селектор DOM, элементы которого нужно показать. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.
• :transition — Строка классов, применяемых перед показом, или кортеж из 3 элементов, содержащий класс перехода, класс для начала перехода и класс для завершения перехода, например: {"ease-out duration-300", "opacity-0", "opacity-100"}
• :time — Время в миллисекундах, в течение которого применяется переход из :transition. По умолчанию — 200.
• :blocking — Логический флаг, блокирующий интерфейс на время перехода. Значение по умолчанию — true.
• :display — Необязательное значение display, устанавливаемое при показе. По умолчанию — "block", кроме строк и ячеек таблицы, для которых по умолчанию используются "table-row" и "table-cell".

В процессе к показываемым элементам будут отправлены следующие события:

• При запуске действия на клиенте отправляется phx:show-start.
• По истечении времени, указанного в :time, отправляется phx:show-end.

Примеры

<div id="item">My Item</div>

<button phx-click={JS.show(to: "#item")}>
  show!
</button>

<button phx-click={JS.show(to: "#item", transition: "fade-in-scale")}>
  show fancy!
</button>

См. show/1.

@spec to_encodable(js :: t()) :: internal()

Возвращает непрозрачное промежуточное представление JS-команды, которое можно закодировать в JSON.

В большинстве случаев вызывать эту функцию напрямую не потребуется, поскольку JS-команды автоматически кодируются в местах их обычного использования: в шаблонах HEEx или в составе данных Phoenix.LiveView.push_event/3.

Эта функция полезна при использовании пользовательской библиотеки JSON. JS-команды реализуют протоколы Jason.Encoder и JSON.Encoder, поэтому они автоматически кодируются при использовании любой из этих библиотек JSON.

Примеры

На сервере динамически сформируйте JS-команды и отправьте их клиенту:

socket
|> push_event("myapp:exec_js", %{
  to: "#items-#{item.id}",
  js: js_commands_for(item) |> JS.to_encodable()
})

socket
|> push_event("myapp:exec_js", %{
  to: "#items-#{item.id}",
  js: JS.show()
})

На клиенте обработайте событие и выполните команды:

window.addEventListener("phx:myapp:exec_js", e => {
  const {to, js} = e.detail;
  const el = document.querySelector(to);
  if (el && js) {
    window.liveSocket.execJS(el, js);
  }
});

Однако обычно JS-команды хранятся в атрибуте HTML (phx-* или data-*), чтобы JavaScript на стороне клиента мог обратиться к ним позже. Например, в шаблоне LiveView:

<div id={"items-#{item.id}"} data-js={JS.show()}>
  Hello!
</div>

Теперь сервер может отправить событие, ссылающееся на атрибут data-js:

socket
|> push_event("myapp:exec_attr", %{
  to: "#items-#{item.id}",
  attr: "data-js"
})

Наконец, на клиенте можно прочитать и выполнить команды:

window.addEventListener("phx:myapp:exec_attr", e => {
  const {to, attr} = e.detail;
  const el = document.querySelector(to);
  const js = el && attr && el.getAttribute(attr);
  if (el && js) {
    window.liveSocket.execJS(el, js);
  }
});

Обратите внимание: в приведённом выше коде нам не пришлось явно кодировать JS-команды или передавать их в данных события, поскольку они были отрендерены в шаблоне.

Переключает видимость элемента.

Параметры

• :to — Необязательный селектор DOM, для которого нужно переключить видимость. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.
• :in — Строка классов, применяемых при появлении, или кортеж из 3 элементов, содержащий класс перехода, класс для начала перехода и класс для завершения перехода, например: {"ease-out duration-300", "opacity-0", "opacity-100"}
• :out — Строка классов, применяемых при исчезновении, или кортеж из 3 элементов, содержащий класс перехода, класс для начала перехода и класс для завершения перехода, например: {"ease-out duration-300", "opacity-100", "opacity-0"}
• :time — Время в миллисекундах, в течение которого применяются классы перехода :in и :out. По умолчанию — 200.
• :display — Необязательное значение display, устанавливаемое при появлении. По умолчанию — "block", кроме строк и ячеек таблицы, для которых по умолчанию используются "table-row" и "table-cell".
• :blocking — Логический флаг, блокирующий интерфейс на время перехода. Значение по умолчанию — true.

После завершения переключения на клиенте для переключаемых элементов будут отправлены события phx:show-start или phx:hide-start, а также phx:show-end или phx:hide-end.

Примеры

<div id="item">My Item</div>

<button phx-click={JS.toggle(to: "#item")}>
  toggle item!
</button>

<button phx-click={JS.toggle(to: "#item", in: "fade-in-scale", out: "fade-out-scale")}>
  toggle fancy!
</button>

См. toggle/1.

Устанавливает или удаляет атрибут элемента в зависимости от наличия атрибута.

Принимает кортеж из двух или трёх элементов:

• {attr, val} — устанавливает атрибуту заданное значение или удаляет его
• {attr, val1, val2} — переключает атрибут между val1 и val2

Параметры

• :to — необязательный селектор DOM, указывающий, у каких элементов устанавливать или удалять атрибуты. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.

Примеры

<button phx-click={JS.toggle_attribute({"aria-expanded", "true", "false"}, to: "#dropdown")}>
  toggle
</button>

<button phx-click={JS.toggle_attribute({"open", "true"}, to: "#dialog")}>
  toggle
</button>

См. toggle_attribute/1.

См. toggle_attribute/1.

Добавляет или удаляет классы элемента в зависимости от их наличия.

• names — строка с одним или несколькими именами классов для переключения.

Параметры

• :to — необязательный селектор DOM для выбора целевых элементов. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.
• :transition — строка с классами, которые нужно применить перед добавлением классов, или кортеж из трёх элементов, содержащий класс перехода, класс для начала перехода и класс для завершения перехода, например: {"ease-out duration-300", "opacity-0", "opacity-100"}
• :time — время в миллисекундах, в течение которого применяется переход из :transition. По умолчанию — 200.
• :blocking — логический флаг, блокирующий интерфейс во время перехода. По умолчанию — true.

Примеры

<div id="item">My Item</div>
<button phx-click={JS.toggle_class("active", to: "#item")}>
  toggle active!
</button>

Выполняет переходы для элементов.

• transition — строка с классами, которые нужно применить во время перехода, или кортеж из трёх элементов, содержащий класс перехода, класс для начала перехода и класс для завершения перехода, например: {"ease-out duration-300", "opacity-0", "opacity-100"}

Переходы полезны для временного добавления к элементам класса анимации, например для выделения изменившегося содержимого.

Параметры

• :to — необязательный селектор DOM, к элементам которого нужно применить переходы. По умолчанию используется элемент, с которым взаимодействовали. Подробности см. в разделе DOM selectors.
• :time — время в миллисекундах, в течение которого применяется переход из :transition. По умолчанию — 200.
• :blocking — логический флаг, блокирующий интерфейс во время перехода. По умолчанию — true.

Примеры

<div id="item">My Item</div>
<button phx-click={JS.transition("shake", to: "#item")}>Shake!</button>

<div phx-mounted={JS.transition({"ease-out duration-300", "opacity-0", "opacity-100"}, time: 300)}>
    duration-300 milliseconds matches time: 300 milliseconds
</div>

См. transition/1.

См. transition/1.