2025-03-03 14:40:49 +01:00

46 KiB

Raw Blame History

Alpine.js

Alpine.js предоставляет реактивность и декларативность как в больших фреймворках вроде Vue или React, но с меньшими затратами.

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

Можете думать о Alpine.js как о Tailwind для JavaScript.

Замечание: синтаксис Alpine.js почти полностью заимствован из Vue (а, соответственно, и из Angular). Я безмерно благодарен разработчикам этих инструментов за тот вклад, который они внесли в Web.

Установка

С помощью CDN: Добавьте следующий <script> в конец секции <head>.

<script src="https://cdn.jsdelivr.net/gh/alpinejs/alpine@v2.x.x/dist/alpine.min.js" defer></script>

Вот и всё. Он инициализируется самостоятельно.

Для рабочего окружения рекомендуется использовать ссылку с конкретным номером версии, чтобы избежать неожиданных поломок после выпуска новых версий. Например, чтобы использовать версию 2.8.2:

<script src="https://cdn.jsdelivr.net/gh/alpinejs/alpine@v2.8.2/dist/alpine.min.js" defer></script>

С помощью npm: Установите пакет из npm.

npm i alpinejs

Добавьте его в свой код.

import 'alpinejs'

Для поддержки IE11 используйте вместо указанных выше следующие скрипты:

<script type="module" src="https://cdn.jsdelivr.net/gh/alpinejs/alpine@v2.x.x/dist/alpine.min.js"></script>
<script nomodule src="https://cdn.jsdelivr.net/gh/alpinejs/alpine@v2.x.x/dist/alpine-ie11.min.js" defer></script>

Паттерн, использующийся выше, называется паттерн module/nomodule. Он позволяет автоматически загружать современный пакет в современных браузерах, а в IE11 и других устаревших браузерах – пакет для IE11.

Использование

Выпадающий список/Модальное окно

<div x-data="{ open: false }">
    <button @click="open = true">Открыть</button>

    <ul
        x-show="open"
        @click.away="open = false"
    >
        Содержимое
    </ul>
</div>

Вкладки

<div x-data="{ tab: 'foo' }">
    <button :class="{ 'active': tab === 'foo' }" @click="tab = 'foo'">Foo</button>
    <button :class="{ 'active': tab === 'bar' }" @click="tab = 'bar'">Bar</button>

    <div x-show="tab === 'foo'">Вкладка Foo</div>
    <div x-show="tab === 'bar'">Вкладка Bar</div>
</div>

Alpine.js можно использовать и для более серьезных выражений. Например, предзагрузка HTML-содержимого при наведении мыши.

<div x-data="{ open: false }">
    <button
        @mouseenter.once="
            fetch('/dropdown-partial.html')
                .then(response => response.text())
                .then(html => { $refs.dropdown.innerHTML = html })
        "
        @click="open = true"
    >Показать</button>

    <div x-ref="dropdown" x-show="open" @click.away="open = false">
        Загрузка...
    </div>
</div>

Изучение

Всего в Alpine 14 директив:

Директива	Описание
`x-data`	Объявляет новый компонент и его данные.
`x-init`	Выполняет переданное выражение, когда компонент инициализируется.
`x-show`	Переключает `display: none;` на элементе, в зависимости от результата переданного выражения (true или false).
`x-bind`	Устанавливает значение атрибута равным результату переданного JS-выражения.
`x-on`	Устанавливает обработчик события на элемент. Когда событие срабатывает, выполняет переданное JS-выражение.
`x-model`	Добавляет "двустороннюю привязку данных" (two-way data binding) на элемент. Синхронизирует элемент и данные компонента.
`x-text`	Устанавливает значение `innerText` элемента равным результату переданного JS-выражения.
`x-html`	Устанавливает значение `innerHTML` элемента равным результату переданного JS-выражения.
`x-ref`	Удобный способ получения DOM-элементов вашего компонента.
`x-if`	При невыполнении переданного условия полностью удаляет элемент из DOM. Должна использоваться в теге `<template>`.
`x-for`	Создает новые DOM узлы для каждого элемента в массиве. Должна использоваться в теге `<template>`.
`x-transition`	Директивы для добавления css-классов различным стадиям перехода (transition) элемента.
`x-spread`	Позволяет привязывать объект с директивами Alpine к элементам, улучшая повторное использование кода.
`x-cloak`	Атрибут удаляется после инициализации Alpine. Используется для скрытия элементов до DOM инициализации.

И 6 магических свойств (magic properties):

Магическое свойство	Описание
`$el`	Получить DOM-узел корневого компонента.
`$refs`	Получить DOM-элементы компонента, отмеченные `x-ref`.
`$event`	В обработчике события получить нативный объект браузера "Event".
`$dispatch`	Создать `CustomEvent` и вызвать его, используя `.dispatchEvent()`.
`$nextTick`	Выполнить переданное выражение ПОСЛЕ того, как Alpine сделает реактивное обновление DOM.
`$watch`	Выполнить переданный колбэк, когда наблюдаемое свойство компонента изменится.

Спонсоры

Хочешь здесь своё лого? Напиши мне сообщение в Twitter

Сообщество проекта

Директивы

`x-data`

Пример: <div x-data="{ foo: 'bar' }">...</div>

Синтаксис: <div x-data="[JSON-объект]">...</div>

x-data объявляет область видимости нового компонента с использованием переданного объекта данных.

Аналогична свойству data в компонентах Vue.

Задание логики компонента отдельной функцией

Можно получить данные (и задать поведение компонента) в повторно используемых функциях:

<div x-data="dropdown()">
    <button x-on:click="open">Открыть</button>

    <div x-show="isOpen()" x-on:click.away="close">
        // Dropdown
    </div>
</div>

<script>
    function dropdown() {
        return {
            show: false,
            open() { this.show = true },
            close() { this.show = false },
            isOpen() { return this.show === true },
        }
    }
</script>

Для пользователей бандлеров (bundler). Alpine.js получает доступ к функциям только из глобальной области видимости (window). Вам необходимо явно присвоить свои функции объекту window, чтобы использовать их с x-data. Например, вот так: window.dropdown = function () {} (с Webpack, Rollup, Parcel и другими бандлерами функции, которые вы объявляете, по умолчанию принадлежать области видимости бандлера, а не window).

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

<div x-data="{...dropdown(), ...tabs()}">

`x-init`

Пример: <div x-data="{ foo: 'bar' }" x-init="foo = 'baz'"></div>

Синтаксис: <div x-data="..." x-init="[выражение]"></div>

x-init выполняет переданное выражение, когда компонент инициализируется.

Если вы хотите выполнить код ПОСЛЕ первоначальных обновлений DOM Alpine (наподобие хука mounted() во VueJS), то можете передать в x-init колбэк, и он выполнит его после инициализации:

x-init="() => { // здесь уже есть доступ к состоянию после инициализации DOM // }"

`x-show`

Пример: <div x-show="open"></div>

Синтаксис: <div x-show="[выражение]"></div>

x-show переключает display: none; на элементе в зависимости от результата выполнения выражения (true или false).

x-show.transition

x-show.transition – удобный API для добавления к x-show CSS-переходов (transitions).

<div x-show.transition="open">
    Это содержимое будет иметь переходы при появлении и исчезновении.
</div>

Директива	Описание
`x-show.transition`	Одновременный fade и scale. (opacity, scale: 0.95, timing-function: cubic-bezier(0.4, 0.0, 0.2, 1), duration-in: 150ms, duration-out: 75ms)
`x-show.transition.in`	Переход только при появлении.
`x-show.transition.out`	Переход только при исчезновении.
`x-show.transition.opacity`	Использовать только fade.
`x-show.transition.scale`	Использовать только scale.
`x-show.transition.scale.75`	Кастомизация scale перехода `transform: scale(.75)`.
`x-show.transition.duration.200ms`	Устанавливает время перехода при появлении на 200мс. Переход при исчезновении будет равен половине этого значения (100мс).
`x-show.transition.origin.top.right`	Кастомизация места возникновения перехода `transform-origin: top right`.
`x-show.transition.in.duration.200ms.out.duration.50ms`	Различные длительности для переходов при появлении и исчезновении.

Замечание: Все эти модификаторы переходов могут использоваться в сочетании друг с другом. Это возможно (хоть и нелепо): x-show.transition.in.duration.100ms.origin.top.right.opacity.scale.85.out.duration.200ms.origin.bottom.left.opacity.scale.95

Замечание: x-show будет ждать окончания переходов всех дочерних элементов. Можно изменить это поведение модификатором .immediate:

<div x-show.immediate="open">
    <div x-show.transition="open">
</div>

`x-bind`

Сокращенный синтаксис ":". Например: :type="..."

Пример: <input x-bind:type="inputType">

Синтаксис: <input x-bind:[атрибут]="[выражение]">

x-bind устанавливает значение атрибута равным результату JS-выражения. Выражение имеет доступ ко всем ключам хранилища данных компонента и будет обновляться каждый раз при обновлении данных.

Замечание: обновление значения атрибута с x-bind будет происходить ТОЛЬКО при обновлении его зависимостей.

x-bind для атрибутов class

x-bind ведет себя немного иначе, когда привязан к атрибуту class.

Для css-классов необходимо передавать объект, где ключи – это имена классов, а значения – логические выражения, которые определяют применяются эти классы или нет.

Например: <div x-bind:class="{ 'hidden': foo }"></div>

В этом примере, класс "hidden" будет применен только если значение выражения foo равно true.

x-bind для логических атрибутов

x-bind поддерживает логические атрибуты так же, как и атрибуты значения, используя переменную как условие или любое JS-выражение, которое разрешается в true или false.

Например:

<!-- Дано: -->
<button x-bind:disabled="myVar">Нажми на меня</button>

<!-- Когда myVar == true: -->
<button disabled="disabled">Нажми на меня</button>

<!-- Когда myVar == false: -->
<button>Нажми на меня</button>

Это добавит или удалит атрибут disabled, в зависимости от того, равна myVar true или false.

Логические атрибуты поддерживаются в соответствии с HTML спецификацией, такие как, например, disabled, readonly, required, checked, hidden, selected, open и другие.

Замечание: Если нужно вернуть логическое (true/false) значение атрибута в виде текста, например для aria-*, используйте метод .toString(). Например :aria-expanded="isOpen.toString()" вернёт строку true или falseв зависимости от значения isOpen.

Модификатор .camel Пример: <svg x-bind:view-box.camel="myVar">

Модификатор camel позволяет задать имя атрибута, которое будет преобразовано к синтаксису "camelCase". В данном примере значение будет присвоено атрибуту viewBox, а не view-box.

`x-on`

Сокращенный синтаксис "@": @click="..."

Пример: <button x-on:click="foo = 'bar'"></button>

Синтаксис: <button x-on:[событие]="[выражение]"></button>

x-on цепляет слушатель события на элемент, в котором был объявлен. Когда событие срабатывает, выполняется переданное JS-выражение. Можно использовать x-on с любым событием. См. полный список событий в документации MDN.

Если в этом выражении меняются какие-либо данные, другие элементы, "привязанные" к этим данным, также будут обновлены.

Замечание: Также можно задать имя JS-функции.

Пример: <button x-on:click="myFunction"></button>

Это равноценно: <button x-on:click="myFunction($event)"></button>

Модификатор keydown

Пример: <input type="text" x-on:keydown.escape="open = false">

Можно обозначить конкретные клавиши для прослушивания, присоединяя их через точку к директиве x-on:keydown. Модификаторы – это значения Event.key, записанные в kebab-стиле.

Например: enter, escape, arrow-up, arrow-down

Замечание: Можно также прослушивать комбинации с системными клавишами, например: x-on:keydown.cmd.enter="foo"

Модификатор .away

Пример: <div x-on:click.away="showModal = false"></div>

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

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

Модификатор .prevent

Пример: <input type="checkbox" x-on:click.prevent>

При добавлении .prevent обработчик вызовет preventDefault на сработавшем событии. В примере выше это приведет к тому, что чекбокс не будет отмечен при нажатии на него.

Модификатор .stop

Пример: <div x-on:click="foo = 'bar'"><button x-on:click.stop></button></div>

При добавлении .stop обработчик вызовет stopPropagation на сработавшем событии. В примере выше это приведет к тому, что событие "click" не всплывет от кнопки к внешнему <div>. Другими словами, когда пользователь нажимает на кнопку, foo не устанавливается в 'bar'.

Модификатор .self

Пример: <div x-on:click.self="foo = 'bar'"><button></button></div>

При добавлении .self обработчик события сработает, только если $event.target – это сам элемент. В примере выше это приведет к тому, что событие "click", всплыв от кнопки к внешнему <div>, не вызовет его обработчик.

Модификатор .window

Пример: <div x-on:resize.window="isOpen = window.outerWidth > 768 ? false : open"></div>

При добавлении .window слушатель события установится не на узел DOM, на котором был вызван, а на глобальный объект window. Это используется, когда нужно изменить состояние компонента при изменении чего-либо в window, например, при событии "resize". В примере выше, когда ширина окна будет больше 768 пикселей, модальное окно закроется.

Замечание: Также можно использовать модификатор .document для добавления слушателей к document.

Модификатор .once

Пример: <button x-on:mouseenter.once="fetchSomething()"></button>

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

Модификатор .passive

Пример: <button x-on:mousedown.passive="interactive = true"></button>

Добавление модификатора .passive к слушателю события сделает его пассивным. Это значит, что preventDefault() не будет работать ни с какими обрабатываемыми событиями. Это может помочь например с производительностью при прокрутке на сенсорных устройствах.

Модификатор .debounce

Пример: <input x-on:input.debounce="fetchSomething()">

Модификатор debounce позволяет избавиться от ложных повторных вызовов обработчика события. Другими словами, обработчик НЕ будет вызван, пока не пройдет определенное количество времени с предыдущего вызова. Когда обработчик будет готов, будет вызван последний вызов.

Время ожидания по умолчанию 250 миллисекунд.

Вы также можете указать свое время:

<input x-on:input.debounce.750="fetchSomething()">
<input x-on:input.debounce.750ms="fetchSomething()">

Модификатор .camel

Пример: <input x-on:event-name.camel="doSomething()">

Модификатор camel позволяет задать событие, которое будет преобразовано к синтаксису "camelCase". В данном примере слушатель будет добавлен к событию eventName.

`x-model`

Пример: <input type="text" x-model="foo">

Синтаксис: <input type="text" x-model="[хранилище данных]">

x-model добавляет элементу "двустороннюю привязку данных" (two-way data binding). Другими словами, значение поля ввода будет синхронизировано со значением в хранилище данных компонента.

Замечание: x-model достаточно умен, чтобы замечать изменения в текстовых полях ввода, чекбоксах, радио-кнопках, textarea, select, и множественных select. В данных сценариях x-model ведет себя аналогично v-model во Vue.

Модификатор .number Пример: <input x-model.number="age">

Модификатор number преобразует входное значение в число. Если оно не может быть преобразовано, то возвращается исходное значение.

Модификатор .debounce Пример: <input x-model.debounce="search">

Модификатор debounce позволяет избавиться от ложных повторных изменений значения. Другими словами, обработчик НЕ будет вызван, пока не пройдет определенное количество времени с предыдущего вызова. Когда обработчик будет готов, будет вызван последний вызов.

Время ожидания по умолчанию 250 миллисекунд.

Вы также можете указать свое время:

<input x-model.debounce.750="search">
<input x-model.debounce.750ms="search">

`x-text`

Пример: <span x-text="foo"></span>

Синтаксис: <span x-text="[выражение]"

x-text устанавливает значение innerText элемента равным результату переданного JS-выражения. Другими словами, работает аналогично x-bind, но не для атрибута, а для innerText элемента.

`x-html`

Пример: <span x-html="foo"></span>

Синтаксис: <span x-html="[выражение]"

x-html устанавливает значение innerHTML элемента равным результату переданного JS-выражения. Другими словами, работает аналогично x-bind, но не для атрибута, а для innerHTML элемента.

⚠️ Используйте только надежные источники контента и никогда не используйте контент, предоставленный пользователем. ⚠️

Динамически отрендеренный HTML от третьих сторон может легко привести к XSS уязвимостям.

`x-ref`

Пример: <div x-ref="foo"></div><button x-on:click="$refs.foo.innerText = 'bar'"></button>

Синтаксис: <div x-ref="[имя рефа]"></div><button x-on:click="$refs.[имя рефа].innerText = 'bar'"></button>

x-ref предоставляет удобный способ получения DOM-элементов ваших компонентов. При установлении атрибута x-ref на элемент, вы делаете его доступным всем обработчикам событий в объекте $refs.

Это удобная альтернатива установке id и использования document.querySelector.

Замечание: при необходимости также можно привязывать x-ref динамические значения: <span :x-ref="item.id"></span>.

`x-if`

Пример: <template x-if="true"><div>Какой-то элемент</div></template>

Синтаксис: <template x-if="[выражение]"><div>Какой-то элемент</div></template>

В случаях, когда x-show недостаточно (x-show устанавливает элементу display: none, если выражение ложно), можно использовать x-if, чтобы полностью удалить элемент из DOM.

Alpine не использует Virtual DOM, поэтому важно, чтобы x-if использовался в теге <template></template>.

Замечание: Внутри тега <template></template> с x-if должен быть лишь один корневой элемент.

Замечание: При использовании template в тэге svg, используйте полифил. Он должен быть запущен до инициализации Alpine.js.

`x-for`

Пример:

<template x-for="item in items" :key="item">
    <div x-text="item"></div>
</template>

Замечание: привязка :key опциональна, хотя КРАЙНЕ рекомендуется.

x-for используется для создания новых DOM-узлов для каждого элемента в массиве. x-for похоже на v-for во Vue, с одним отличием: x-for может использовался только в теге <template></template>.

Если вы хотите получить доступ к индексу текущей итерации, используйте следующий синтаксис:

<template x-for="(item, index) in items" :key="index">
    <!-- Если необходимо, вы также можете ссылаться на "index" внутри итерации. -->
    <div x-text="index"></div>
</template>

Если нужно получить доступ к массиву данных (collection) внутри цикла, используйте такой синтаксис:

<template x-for="(item, index, collection) in items" :key="index">
    <!-- Можно ссылаться на массив "collection" -->
    <!-- Текущий элемент -->
    <div x-text="item"></div>
    <!-- или так -->
    <div x-text="collection[index]"></div>
    <!-- Предыдущий элемент -->
    <div x-text="collection[index - 1]"></div>
</template>

Замечание: Внутри тега <template></template> с x-for должен быть лишь один корневой элемент.

Замечание: При использовании template в тэге svg, используйте полифил. Он должен быть запущен до инициализации Alpine.js.

Вложенные `x-for`

Можно вкладывать x-for друг в друга, но НУЖНО оборачивать каждый цикл в какой-нибудь элемент. Например:

<template x-for="item in items">
    <div>
        <template x-for="subItem in item.subItems">
            <div x-text="subItem"></div>
        </template>
    </div>
</template>

Количество итераций

Alpine поддерживает синтаксис i in n, где n число, указывающее на количество итераций цикла.

<template x-for="i in 10">
    <span x-text="i"></span>
</template>

`x-transition`

Пример:

<div
    x-show="open"
    x-transition:enter="transition ease-out duration-300"
    x-transition:enter-start="opacity-0 transform scale-90"
    x-transition:enter-end="opacity-100 transform scale-100"
    x-transition:leave="transition ease-in duration-300"
    x-transition:leave-start="opacity-100 transform scale-100"
    x-transition:leave-end="opacity-0 transform scale-90"
>...</div>

<template x-if="open">
    <div
        x-transition:enter="transition ease-out duration-300"
        x-transition:enter-start="opacity-0 transform scale-90"
        x-transition:enter-end="opacity-100 transform scale-100"
        x-transition:leave="transition ease-in duration-300"
        x-transition:leave-start="opacity-100 transform scale-100"
        x-transition:leave-end="opacity-0 transform scale-90"
    >...</div>
</template>

Пример выше использует классы из Tailwind CSS

Alpine предлагает 6 разных transition-директив для добавления классов к различным стадиям перехода элемента от состояния "скрытого" к "видимому". Все эти директивы работают как с x-show, так и с x-if.

Они ведут себя абсолютно так же, как transition-директивы во VueJS, но у них более понятные названия:

Директива	Описание
`:enter`	Применяется в ходе всей фазы появления.
`:enter-start`	Добавляется до введения элемента, удаляется на следующий фрейм после с введения элемента.
`:enter-end`	Добавляется на следующий фрейм после с введения элемента (одновременно с удалением `enter-start`), удаляется, когда переход/анимация заканчивается.
`:leave`	Применяется в ходе всей фазы исчезновения.
`:leave-start`	Добавляется, как только вызвано исчезновение, удаляется на следующий фрейм.
`:leave-end`	Добавляется на следующий фрейм, как только вызвано исчезновение (одновременно с удалением `leave-start`), удаляется, когда переход/анимация заканчивается.

`x-spread`

Пример:

<div x-data="dropdown()">
    <button x-spread="trigger">Открыть</button>

    <span x-spread="dialogue">Содержимое</span>
</div>

<script>
    function dropdown() {
        return {
            open: false,
            trigger: {
                ['@click']() {
                    this.open = true
                },
            },
            dialogue: {
                ['x-show']() {
                    return this.open
                },
                ['@click.away']() {
                    this.open = false
                },
            }
        }
    }
</script>

x-spread позволяет вынести привязки Alpine из элементов в объект (он может повторно использоваться в других компонентах).

Ключи объекта – это директивы (любые, в том числе и с модификаторами), а значения – колбэки, с которыми будет работать Alpine.

Замечание: Единственная особенность при работе с x-spread – это то, как обрабатывается x-for. Когда директива, используемая в x-spread – это x-for, в колбэке необходимо возвращать выражение в виде строки. К примеру: ['x-for']() { return 'item in items' }.

Замечание: Директивы x-data и x-init не могут использоваться в "spread"-объекте.

`x-cloak`

Пример: <div x-data="{}" x-cloak></div>

Атрибуты x-cloak удаляются с элементов, когда Alpine будет проинициализирован. Это полезно для скрытия элемента до построения DOM. Для использования x-cloak необходимо добавить следующие css-правила:

<style>
    [x-cloak] { display: none; }
</style>

Магические свойства

Не считая $el, магические свойства не доступны внутри x-data, так как компонент еще не инициализирован.

`$el`

Пример:

<div x-data>
    <button @click="$el.innerHTML = 'foo'">Замени меня на "foo"</button>
</div>

$el – магическое свойство, которое используется для получения корневого DOM-узла компонента.

`$refs`

Пример:

<span x-ref="foo"></span>

<button x-on:click="$refs.foo.innerText = 'bar'"></button>

$refs – это магическое свойство, которое используется для получения DOM-элементов внутри компонента, помеченных x-ref. Оно используется, когда нужно вручную манипулировать элементами DOM.

`$event`

Пример:

<input x-on:input="alert($event.target.value)">

$event – это магическое свойство, которое можно использовать в слушателе событий для получения нативного объекта "Event".

Замечание: свойство $event доступно только в DOM-выражениях.

Если нужно получить доступ к $event внутри функции JavaScript, вы можете передать его как параметр:

<button x-on:click="myFunction($event)"></button>

`$dispatch`

Пример:

<div @custom-event="console.log($event.detail.foo)">
    <button @click="$dispatch('custom-event', { foo: 'bar' })"></button>
    <!-- После нажатия кнопки выводит в консоль "bar" -->
</div>

Примечание по распространению событий (event propagation)

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

Пример неверного использования:

<div x-data>
    <span @custom-event="console.log($event.detail.foo)"></span>
    <button @click="$dispatch('custom-event', { foo: 'bar' })"></button>
<div>

Это не будет работать, потому что, когда вызывается custom-event, он сразу всплывает (event bubbling) к родителю div.

Диспетчеризация для компонентов

Вы также можете использовать предыдущую технику для общения компонентов друг с другом:

Пример:

<div x-data @custom-event.window="console.log($event.detail)"></div>

<button x-data @click="$dispatch('custom-event', 'Hello World!')"></button>
<!-- При нажатии в консоль выведется "Hello World!". -->

$dispatch – это удобное сокращение для создания CustomEvent (пользовательские события) и их вызова с помощью .dispatchEvent(). Существует множество сценариев использования передачи данных между компонентами с помощью пользовательских событий. Пройдите по этой ссылке, чтобы больше узнать о системе, лежащей в основе CustomEvent в браузерах.

Любые данные, переданные как второй параметр в $dispatch('some-event', { some: 'data' }), становятся доступны через свойство "detail" события: $event.detail.some. Добавление событию пользовательских данных через свойство .detail – стандартная практика для CustomEvent в браузерах. Подробнее здесь.

Вы также можете использовать $dispatch() для вызова обновления данных в привязках x-model. Например:

<div x-data="{ foo: 'bar' }">
    <span x-model="foo">
        <button @click="$dispatch('input', 'baz')"></button>
        <!-- После нажатия кнопки, `x-model` перехватит всплывающее событие "input" (oninput), и обновит foo на "baz". -->
    </span>
</div>

Замечание: Свойство $dispatch доступно только в DOM-выражениях.

Если нужен доступ к $dispatch внутри JavaScript-функции, вы можете передать его напрямую:

<button x-on:click="myFunction($dispatch)"></button>

`$nextTick`

Пример:

<div x-data="{ fruit: 'яблоко' }">
    <button
        x-on:click="
            fruit = 'груша';
            $nextTick(() => { console.log($event.target.innerText) });
        "
        x-text="fruit"
    ></button>
</div>

$nextTick – это магическое свойство, которое выполняет переданное выражение только ПОСЛЕ того, как Alpine реактивно обновит DOM. Это полезно в тех случаях, когда вы хотите взаимодействовать с состоянием DOM, ПОСЛЕ того, как оно отразит сделанное вами обновление данных.

`$watch`

Пример:

<div x-data="{ open: false }" x-init="$watch('open', value => console.log(value))">
    <button @click="open = ! open">Toggle Open</button>
</div>

Магический метод $watch позволяет следить за выбранным свойством компонента. В примере выше при нажатии на кнопку: 1) значение open изменится; 2) выполнится переданный в $watch колбэк; 3) в консоль выведется новое значение.

Безопасность

Если вы нашли уязвимость, пожалуйста, отправьте письмо на calebporzio@gmail.com.

Alpine полагается на собственную реализацию, которая использует объект Function для оценки своих директив. Несмотря на то, что он безопаснее, чем eval(), его использование запрещено в некоторых средах, таких как Google Chrome App, т.е. использующих Политику защиты контента (CSP).

Если вы используете Alpine на веб-сайте, имеющем дело с конфиденциальными данными и требующим CSP, вы должны включить unsafe-eval в свою политику. Правильно настроенная политика поможет защитить ваших пользователей при использовании их личных или финансовых данных.

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

Планы на третью версию

Перейти с x-ref на ref для соответствия с Vue?
Добавить Alpine.directive()
Добавить Alpine.component('foo', {...}) (с магическим методом __init())
Вызывать Alpine-события для "loaded", "transition-start", и т.д. (#299) ?
Удалить синтаксис объекта (и массива) у x-bind:class="{ 'foo': true }" (#236, чтобы добавить поддержку синтаксиса объекта для атрибута style)
Улучшить изменение реактивности x-for (#165)
Добавить поддержку "deep watching" (#294)
Добавить сокращение для $el
Изменить @click.away на @click.outside?

Лицензия

Лицензировано по лицензии MIT, смотрите LICENSE.md для подробностей.

46 KiB Raw Blame History Unescape Escape

Alpine.js

Установка

Использование

Изучение

Спонсоры

Сообщество проекта

Директивы

x-data

x-init

x-show

x-bind

x-on

x-model

x-text

x-html

x-ref

x-if

x-for

Вложенные x-for

Количество итераций

x-transition

x-spread

x-cloak

Магические свойства

$el

$refs

$event

$dispatch

$nextTick

$watch

Безопасность

Планы на третью версию

Лицензия

46 KiB

Raw Blame History

`x-data`

`x-init`

`x-show`

`x-bind`

`x-on`

`x-model`

`x-text`

`x-html`

`x-ref`

`x-if`

`x-for`

Вложенные `x-for`

`x-transition`

`x-spread`

`x-cloak`

`$el`

`$refs`

`$event`

`$dispatch`

`$nextTick`

`$watch`