# Alpine.js
[](https://alpinejs.codewithhugo.com/chat/)
Alpine.js предлагает вам реактивность и декларативность таких больших фреймворков, как Vue или React, но за значительно меньшую цену.
Вы сможете использовать обычный DOM, при этом изменяя поведение по своему усмотрению.
Можете думать о Alpine.js как о [Tailwind](https://tailwindcss.com/) для JavaScript.
> Замечание: синтаксис Alpine.js почти полностью заимствован из [Vue](https://vuejs.org/) (а, соответственно, и из [Angular](https://angularjs.org/)). Я безмерно благодарен разработчикам этих инструментов за тот вклад, который они внесли в Web.
## Установка
**С помощью CDN:** Добавьте следующий `
```
Вот и всё. Он инициализируется самостоятельно.
Для продакшн-окружения, рекомендуется использовать ссылку с конкретным номером версии, чтобы избежать неожиданных поломок после выпуска новых версий.
Например, чтобы использовать версию `2.7.3`:
```html
```
**С помощью npm:** Установите пакет из npm.
```js
npm i alpinejs
```
Добавьте его в свой код.
```js
import 'alpinejs'
```
**Для поддержки IE11** используйте вместо указанных выше следующие скрипты:
```html
```
Паттерн, использующийся выше, называется [паттерн module/nomodule](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/). Он позволяет автоматически загружать современный бандл в современных браузерах, а в IE11 и других устаревших браузерах – бандл для IE11.
## Использование
*Дропдаун/Модальное окно*
```html
Содержимое дропдаун
```
*Вкладки*
```html
Вкладка Foo
Вкладка Bar
```
Alpine.js можно использовать и для более серьезных выражений:
*Предзагрузка HTML-содержания дропдауна при наведении мыши*
```html
Загрузка...
```
## Изучение
Всего в Alpine 14 директив:
| Директива | Описание |
| --- | --- |
| [`x-data`](#x-data) | Объявляет новый компонент и его данные. |
| [`x-init`](#x-init) | Выполняет переданное выражение, когда компонент инициализируется. |
| [`x-show`](#x-show) | Переключает `display: none;` на элементе, в зависимости от результата переданного выражения (true или false). |
| [`x-bind`](#x-bind) | Устанавливает значение атрибута равным результату переданного JS-выражения. |
| [`x-on`](#x-on) | Устанавливает обработчик события на элемент. Когда событие срабатывает, выполняет переданное JS-выражение. |
| [`x-model`](#x-model) | Добавляет "двустороннюю привязку данных" (two-way data binding) на элемент. Синхронизирует элемент и данные компонента. |
| [`x-text`](#x-text) | Устанавливает значение `innerText` элемента равным результату переданного JS-выражения. |
| [`x-html`](#x-html) | Устанавливает значение `innerHTML` элемента равным результату переданного JS-выражения. |
| [`x-ref`](#x-ref) | Удобный способ получения DOM-элементов вашего компонента. |
| [`x-if`](#x-if) | При невыполнении переданного условия полностью удаляет элемент из DOM. Должна использоваться в теге ``. |
| [`x-for`](#x-for) | Создает новые DOM узлы для каждого элемента в массиве. Должна использоваться в теге ``. |
| [`x-transition`](#x-transition) | Директивы для добавления классов различным стадиям перехода (transition) элемента. |
| [`x-spread`](#x-spread) | Позволяет вам привязывать объект с директивами Alpine к элементам, улучшая переиспользуемость. |
| [`x-cloak`](#x-cloak) | Удаляется при инициализации Alpine. Полезна для скрытия DOM до инициализации. |
И 6 магических свойств (magic properties):
| Магическое свойство | Описание |
| --- | --- |
| [`$el`](#el) | Получить DOM-узел корневого компонента. |
| [`$refs`](#refs) | Получить DOM-элементы компонента, отмеченные `x-ref`. |
| [`$event`](#event) | В обработчике события получить нативный объект браузера "Event". |
| [`$dispatch`](#dispatch) | Создать `CustomEvent` и вызвать его, используя `.dispatchEvent()`. |
| [`$nextTick`](#nexttick) | Выполнить переданное выражение ПОСЛЕ того, как Alpine сделает реактивное обновление DOM. |
| [`$watch`](#watch) | Выполнить переданный колбэк, когда наблюдаемое свойство компонента изменится. |
## Спонсоры
**Хочешь здесь своё лого? [Напиши мне сообщение в Twitter](https://twitter.com/calebporzio)**
## VIP контрибьюторы
`
`x-data` объявляет область видимости нового компонента с использованием переданного объекта данных.
Аналогична свойству `data` в компонентах Vue.
**Извлечение логики компонента**
Вы можете извлечь данные (и поведение) в переиспользуемые функции:
```html
// Dropdown
```
> **Для пользователей бандлеров**. Alpine.js получает доступ к функциям только из глобальной области видимости (`window`). Вам необходимо явно присвоить свои функции объекту `window`, чтобы использовать их с `x-data`. Например, вот так: `window.dropdown = function () {}` (с Webpack, Rollup, Parcel и другими бандлерами функции, которые вы объявляете, по умолчанию принадлежать области видимости бандлера, а не `window`).
Вы также можете объединять несколько объектов с данными с помощью деструктуризации:
```html
```
---
### `x-init`
**Пример:** ``
**Синтаксис:** ``
`x-init` выполняет переданное выражение, когда компонент инициализируется.
Если вы хотите выполнить код ПОСЛЕ первоначальных обновлений DOM Alpine (наподобие хука `mounted()` во VueJS), вы можете передать `x-init` колбэк, и он выполнит его после инициализации:
`x-init="() => { // здесь уже есть доступ к стейту после инициализации DOM // }"`
---
### `x-show`
**Пример:** ``
**Синтаксис:** ``
`x-show` переключает `display: none;` на элементе в зависимости от результата выполнения выражения (`true` или `false`).
**x-show.transition**
`x-show.transition` – удобный API для добавления `x-show` CSS-переходов.
```html
Это содержимое будет иметь переходы при появлении и исчезновении.
```
| Директива | Описание |
| --- | --- |
| `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`:
```html
```
---
### `x-bind`
> Сокращенный синтаксис ":". Например: `:type="..."`
**Пример:** ``
**Синтаксис:** ``
`x-bind` устанавливает значение атрибута равным результату JS-выражения. Выражение имеет доступ ко всем ключам хранилища данных компонента и будет обновляться каждый раз при обновлении данных.
> Замечание: обновление значения атрибута с `x-bind` будет происходить ТОЛЬКО при обновлении его зависимостей.
**`x-bind` для атрибутов class**
`x-bind` ведет себя немного иначе, когда привязан к атрибуту `class`.
Для классов необходимо передавать объект, где ключи – это имена классов, а значения – логические выражения, которые определяют применяются эти классы или нет.
Например:
``
В этом примере, класс "hidden" будет применен только если значение выражения `foo` равно `true`.
**`x-bind` для логических атрибутов**
`x-bind` поддерживает логические атрибуты так же, как и атрибуты значения, используя переменную как условие или любое JS-выражение, которое разрешается в `true` или `false`.
Например:
```html
```
Это добавит или удалит атрибут `disabled`, в зависимости от того, равна `myVar` true или false.
Логические атрибуты поддерживаются в соответствии с [HTML спецификацией](https://html.spec.whatwg.org/multipage/indices.html#attributes-3:boolean-attribute), такие как, например, `disabled`, `readonly`, `required`, `checked`, `hidden`, `selected`, `open` и другие.
---
### `x-on`
> Сокращенный синтаксис "@": `@click="..."`
**Пример:** ``
**Синтаксис:** ``
`x-on` цепляет слушатель события на элемент, на котором был объявлен. Когда событие срабатывает, выполняется переданное JS-выражение.
Если в этом выражении меняются какие-либо данные, другие элементы, "привязанные" к этим данным, будут обновлены.
> Замечание: Вы также можете задать имя JS-функции.
**Пример:** ``
Это равноценно: ``
**Модификатор `keydown`**
**Пример:** ``
Можно обозначить конкретные клавиши для прослушивания, присоединяя их через точку к директиве `x-on:keydown`. Модификаторы – это значения `Event.key`, записанные в kebab-стиле.
Например: `enter`, `escape`, `arrow-up`, `arrow-down`
> Замечание: Можно также прослушивать комбинации с системными клавишами, например: `x-on:keydown.cmd.enter="foo"`
**Модификатор `.away`**
**Пример:** ``
При добавлении модификатора `.away` обработчик события сработает, только когда событие произошло на другом источнике, а не на этом элементе или его потомках.
Это полезно для скрытия дропдаунов или модальных окон, когда пользователь кликает в другом месте.
**Модификатор `.prevent`**
**Пример:** ``
При добавлении `.prevent` обработчик вызовет `preventDefault` на сработавшем событии. В примере выше это приведет к тому, что чекбокс не будет отмечен при нажатии на него.
**Модификатор `.stop`**
**Пример:** ``
При добавлении `.stop` обработчик вызовет `stopPropagation` на сработавшем событии. В примере выше это приведет к тому, что событие "click" не всплывет от кнопки внешнему `
`. Другими словами, когда пользователь нажимает на кнопку, `foo` не устанавливается в `'bar'`.
**Модификатор `.self`**
**Пример:** ``
При добавлении `.self` обработчик события сработает, только если `$event.target` – это сам элемент. В примере выше это приведет к тому, что событие "click", всплыв от кнопки внешнему `
`, **не** вызовет обработчик.
**Модификатор `.window`**
**Пример:** ``
При добавлении `.window` прослушиватель события установится не на узел DOM, на котором был вызван, а на глобальный объект window. Это полезно, когда нужно изменить состояние компонента при изменении чего-либо в window, например, при событии "resize". В примере выше, когда ширина окна будет больше 768 пикселей, мы закроем модальное окно/дропдаун, иначе сохраним то же состояние.
>Замечание: Также можно использовать модификатор `.document` для добавления слушателей к `document`.
**Модификатор `.once`**
**Пример:** ``
При добавлении `.once` обработчик события будет вызван лишь единожды. Это полезно для вещей, которые вы хотите сделать только один раз, например, загрузка данных и т.п.
**Модификатор `.debounce`**
**Пример:** ``
Модификатор `debounce` позволяет вам избавиться от ложных повторных вызовов обработчика события. Другими словами, обработчик НЕ будет вызван, пока не пройдет определенное количество времени с предыдущего вызова. Когда обработчик будет готов к вызову, будет вызван последний вызов.
Время ожидания по умолчанию 250 миллисекунд.
Вы также можете указать свое время:
```
```
---
### `x-model`
**Пример:** ``
**Синтаксис:** ``
`x-model` добавляет элементу "двустороннюю привязку данных" (two-way data binding). Другими словами, значение поля ввода будет синхронизировано со значением в хранилище данных компонента.
> Замечание: `x-model` достаточно умен, чтобы замечать изменения в текстовых полях ввода, чекбоксах, радио-кнопках, textarea, select, и множественных select. В данных сценариях `x-model` ведет себя аналогично `v-model` [во Vue](https://vuejs.org/v2/guide/forms.html).
**Модификатор `.debounce`**
**Пример:** ``
Модификатор `debounce` позволяет вам избавиться от ложных повторных изменений значения. Другими словами, обработчик НЕ будет вызван, пока не пройдет определенное количество времени с предыдущего вызова. Когда обработчик будет готов к вызову, будет вызван последний вызов.
Время ожидания по умолчанию 250 миллисекунд.
Вы также можете указать свое время:
```
```
---
### `x-text`
**Пример:** ``
**Синтаксис:** ``
**Синтаксис:** ` :warning: **Используйте только надежные источники контента и никогда не используйте контент, предоставленный пользователем.** :warning:
>
> Динамически отрендеренный HTML от третьих сторон может легко привести к [XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting) уязвимостям.
---
### `x-ref`
**Пример:** ``
**Синтаксис:** ``
`x-ref` предоставляет удобный способ получения DOM-элементов ваших компонентов. При установлении атрибута `x-ref` на элемент, вы делаете его доступным всем обработчикам событий в объекте `$refs`.
Это удобная альтернатива установке id и использованию повсюду `document.querySelector`.
> Замечание: при необходимости вы также можете привязывать x-ref динамические значения: ``.
---
### `x-if`
**Пример:** `
Какой-то элемент
`
**Синтаксис:** `
Какой-то элемент
`
В случаях, когда `x-show` недостаточно (`x-show` устанавливает элементу `display: none`, если выражение ложно), можно использовать `x-if`, чтобы полностью удалить элемент из DOM.
Alpine не использует Virtual DOM, поэтому важно, чтобы `x-if` использовался в теге ``.
> Замечание: Внутри тега `` с `x-if` должен быть лишь один корневой элемент.
---
### `x-for`
**Пример:**
```html
```
> Замечание: привязка `:key` опциональна, хотя КРАЙНЕ рекомендуется.
`x-for` используется для создания новых DOM-узлов для каждого элемента в массиве. `x-for` похоже на `v-for` во Vue, с одним отличием: `x-for` может использовался только в теге ``.
Если вы хотите получить доступ к индексу текущей итерации, используйте следующий синтаксис:
```html
```
> Замечание: Внутри тега `` с `x-for` должен быть лишь один корневой элемент.
#### Вложенные `x-for`
Вы можете вкладывать `x-for` друг в друга, но вы ДОЛЖНЫ оборачивать каждый цикл в какой-нибудь элемент. Например:
```html
```
---
### `x-transition`
**Пример:**
```html
...
```
```html
...
```
> Пример выше использует классы из [Tailwind CSS](https://tailwindcss.com)
Alpine предлагает 6 разных transition-директив для добавления классов к различным стадиям перехода элемента от состояния "скрытого" к "видимому". Все эти директивы работают как с `x-show`, так и с `x-if`.
Они ведут себя абсолютно так же, как transition-директивы во Vue, не считая того, что у них другие, более понятные названия:
| Директива | Описание |
| --- | --- |
| `:enter` | Применяется в ходе всей фазы появления. |
| `:enter-start` | Добавляется до введения элемента, удаляется на следующий фрейм после с введения элемента. |
| `:enter-end` | Добавляется на следующий фрейм после с введения элемента (одновременно с удалением `enter-start`), удаляется, когда переход/анимация заканчивается.
| `:leave` | Применяется в ходе всей фазы исчезновения. |
| `:leave-start` | Добавляется, как только вызвано исчезновение, удаляется на следующий фрейм. |
| `:leave-end` | Добавляется на следующий фрейм, как только вызвано исчезновение (одновременно с удалением `leave-start`), удаляется, когда переход/анимация заканчивается.
---
### `x-spread`
**Пример:**
```html
Содержимое дропдауна
```
`x-spread` позволяем вам вынести привязки Alpine из элементов в переиспользуемый объект.
Ключи объекта – это директивы (любые, в том числе и с модификаторами), а значения – колбэки, с которыми будет работать Alpine.
> Замечание: Единственная особенность при работе с x-spread – это то, как обрабатывается `x-for`. Когда директива, используемая в x-spread – это `x-for`, в колбэке необходимо возвращать выражение в виде строки. К примеру: `['x-for']() { return 'item in items' }`.
---
### `x-cloak`
**Пример:** ``
`x-cloak` атрибуты удаляются с элементов, когда Alpine проинициализирован. Это полезно для скрытия DOM до его инициализации. Для этого необходимо добавить следующие глобальные стили:
```html
```
### Магические свойства
> Не считая `$el`, магические свойства **не доступны внутри `x-data`**, так как компонент еще не инициализирован.
---
### `$el`
**Пример:**
```html
```
`$el` – магическое свойство, которое используется для получения корневого компонента DOM-узла.
> Замечание: Свойство $event доступно только в DOM-выражениях.
Если вам нужен доступ к $event внутри JS-функции, вы можете передать его напрямую:
``
### `$refs`
**Пример:**
```html
```
`$refs` – это магическое свойство, которое используется для получения DOM-элементов внутри компонента, помеченных `x-ref`. Это полезно, когда вам нужно вручную манипулировать элементами DOM.
---
### `$event`
**Пример:**
```html
```
`$event` – это магическое свойство, которое можно использовать в слушателе событий для получения нативного объекта "Event".
---
### `$dispatch`
**Пример:**
```html
```
**Примечание по распространению событий (event propagation)**
Когда вам нужно перехватить событие, вызванное из узла на том же уровне вложенности, вам нужно использовать модификатор [`.window`](https://github.com/alpinejs/alpine/blob/master/README.ru.md#x-on):
**Неправильный пример:**
```html
**Хочешь здесь своё лого? [Напиши мне сообщение в Twitter](https://twitter.com/calebporzio)**
## VIP контрибьюторы